build: package signage with ekklesia 0.2.3

Signage no longer needs an Ekklesia checkout. A clean clone installs with
`pnpm install --frozen-lockfile` and runs lint, typecheck, test, build, and validate by itself, taking
Ekklesia's module-development packages from Ekklesia's public registry (ADRs 0053 and 0054).

- Dependencies: every `workspace:*` becomes `^0.2.0`. @ekklesia/module-pack is added as a
  devDependency pinned exactly to 0.2.0, as ADR 0053 requires; it is not invoked yet. No
  @ekklesia/contracts dependency. drizzle-orm stays a direct dependency, satisfying the adapter's
  optional peer.
- .npmrc points the @ekklesia scope at
  https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/ with no credential, because
  reading needs none.
- pnpm-workspace.yaml holds this repository's pnpm settings only:
  - `allowBuilds: esbuild: true`, as the platform's standalone fixture does;
  - exact-version minimumReleaseAgeExclude entries for the 0.2.0 train, which pnpm 11 otherwise holds
    back on its release day;
  - the platform's narrowly scoped override for GHSA-67mh-4wv8-2f99 (esbuild via drizzle-kit), which
    Signage inherited while it built inside Ekklesia's workspace.
- engines.node `>=24.11.0 <25` and packageManager `[email protected].0`, both from Ekklesia 0.2.0. Node
  24.18.0 goes in .node-version for CI, as in Ekklesia.
- biome.json carries the platform's Biome configuration, which `biome lint` used to pick up from the
  workspace root, so lint rules are unchanged.
- pnpm-lock.yaml is Signage's own: registry tarballs with integrity hashes, and no workspace or file
  links.
- `prepack` runs this package's own build instead of the workspace root's turbo.
- `pnpm validate` (scripts/validate-module.mjs) checks the built package and its migrations with the
  published SDK parsers only:
  - the manifest, its identity, and its entrypoints;
  - that the built runtime's id, version, and database ABI match the manifest;
  - that the built schema metadata is plain, namespaced, and has module-internal foreign keys;
  - the SDK compatibility range;
  - that the migration journal and policy agree.

  Core's own `modules:validate` and `migrations:validate` are not published. What only an Ekklesia
  installation can check is named in the script.

Removed: ci/assemble.sh, ci/platform.env, ci/pnpm-lock.yaml, ci/update-lock.sh. The lint, typecheck,
test, and build jobs check out only this repository; build also runs `pnpm validate`. The integration
job stays disabled. Its first step is now an explicit placeholder rather than the deleted assembly,
and its explanation says it returns when Signage is a canonical linux-x64-glibc Module Package
installed into Ekklesia's generic image.

No source, behaviour, schema, or version change: Signage stays 0.1.2.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

.gitea/workflows/ci.yml

@@ -0,0 +1,208 @@
+name: CI
+
+# Signage is a standalone repository: every job checks out only this repository, installs it with
+# --frozen-lockfile from its own pnpm-lock.yaml, and takes Ekklesia's module-development packages
+# (@ekklesia/*) from Ekklesia's public package registry (.npmrc; platform ADRs 0053 and 0054). No job
+# clones Ekklesia.
+#
+# The same trust rules as the platform's own CI (docs/development/security.md there):
+#   * every action is pinned by a full commit SHA;
+#   * every checkout sets `persist-credentials: false`, and nothing in this workflow pushes;
+#   * no repository, organization, or instance secret is referenced;
+#   * there is no `pull_request_target`;
+#   * the self-hosted runner executes trusted, reviewed code only.
+#
+# The server is Gitea 1.27, which honours `concurrency` cancellation; `permissions` and
+# `timeout-minutes` are declared so the workflow is correct wherever they are enforced.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Nothing here pushes, so the job token is never needed after checkout and must not be left
+          # in .git/config for a later step to read.
+          persist-credentials: false
+
+      - name: Set up Node.js at the repository's version
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      # pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
+      # .npmrc: no token, and no Ekklesia checkout.
+      - name: Install (frozen lockfile)
+        run: |
+          corepack enable
+          corepack install
+          pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Check that CI cleans up every stack it starts
+        run: bash ci/check-cleanup.sh
+
+  typecheck:
+    name: typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Nothing here pushes, so the job token is never needed after checkout and must not be left
+          # in .git/config for a later step to read.
+          persist-credentials: false
+
+      - name: Set up Node.js at the repository's version
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      # pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
+      # .npmrc: no token, and no Ekklesia checkout.
+      - name: Install (frozen lockfile)
+        run: |
+          corepack enable
+          corepack install
+          pnpm install --frozen-lockfile
+
+      - name: Typecheck the server, browser, and browser-test projects
+        run: pnpm typecheck
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Nothing here pushes, so the job token is never needed after checkout and must not be left
+          # in .git/config for a later step to read.
+          persist-credentials: false
+
+      - name: Set up Node.js at the repository's version
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      # pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
+      # .npmrc: no token, and no Ekklesia checkout.
+      - name: Install (frozen lockfile)
+        run: |
+          corepack enable
+          corepack install
+          pnpm install --frozen-lockfile
+
+      - name: Unit, browser, and display contract tests
+        run: pnpm test
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Nothing here pushes, so the job token is never needed after checkout and must not be left
+          # in .git/config for a later step to read.
+          persist-credentials: false
+
+      - name: Set up Node.js at the repository's version
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      # pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
+      # .npmrc: no token, and no Ekklesia checkout.
+      - name: Install (frozen lockfile)
+        run: |
+          corepack enable
+          corepack install
+          pnpm install --frozen-lockfile
+
+      - name: Build the server and both browser artifacts
+        run: pnpm build
+
+      # The built package and its migrations, read the way the platform reads them, with only the
+      # published SDK parsers (scripts/validate-module.mjs says what only Ekklesia itself can check).
+      - name: Validate the built module and its migrations
+        run: pnpm validate
+
+  # Signage inside Ekklesia, end to end, in a real browser: the platform's own Dockerfile builds the
+  # deployment image with Signage in it, and the platform's split-topology deployment smoke runs
+  # against it, pairing a kiosk display and running the scenarios in ci/display-scenarios. A
+  # disposable database and object store with generated secrets; nothing is pushed or logged in to.
+  #
+  # DISABLED. From Ekklesia 0.2.0 on, the platform's image is the one generic image (platform ADR
+  # 0048): deploy/Dockerfile keeps `modules/` out of its build context and refuses one that has it,
+  # and the deployment smoke installs modules only as canonical Module Packages (ADR 0049). Signage is
+  # not one yet: its static sharp dependency needs the native linux-x64-glibc package flow. Run as it
+  # was, this job would build an image without Signage and drive the module template's display
+  # instead, so it is switched off rather than left reporting on something else.
+  #
+  # It returns when Signage is built as a canonical linux-x64-glibc Module Package and installed into
+  # Ekklesia's generic image; that change removes `if: false` and rewrites these steps. They still
+  # expect the platform tree ci/assemble.sh used to build at build/workspace, and that assembly is
+  # gone now that Signage builds on its own. The platform's deployment smoke and stack sweep will
+  # still come from Ekklesia, at the release Signage targets, because they are the platform's to run.
+  integration:
+    name: integration
+    if: false
+    needs:
+      - test
+      - build
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      DOCKER_BUILDKIT: "1"
+      # Names this job's stacks, so its final step removes exactly these (the platform's
+      # scripts/lib/ci-project.sh).
+      EKKLESIA_CI_JOB_KEY: signage-integration
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Fetch Ekklesia's deployment smoke and build Signage's Module Package
+        run: |
+          echo "integration: rewritten when Signage is a canonical linux-x64-glibc Module Package." >&2
+          exit 1
+
+      # A job the runner killed (cancelled, or past the runner's own time limit) never ran its
+      # cleanup. Anything a CI job left on this shared daemon more than three hours ago goes first.
+      - name: Sweep stale CI stacks from the runner
+        run: bash build/workspace/scripts/ci-sweep.sh --stale
+
+      - name: Build the image and run the display scenarios
+        run: bash ci/integration.sh
+
+      # Whatever happened above, this job's own stacks do not outlive it. If the first step failed,
+      # nothing was started.
+      - name: Remove this job's CI stacks
+        if: always()
+        run: |
+          if [ -f build/workspace/scripts/ci-sweep.sh ]; then
+            bash build/workspace/scripts/ci-sweep.sh --job
+          fi

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+.pnpm-store/
 dist/
 .turbo/
 coverage/

.node-version

@@ -0,0 +1 @@
+24.18.0

.npmrc

@@ -0,0 +1,3 @@
+# Ekklesia's module-development packages (@ekklesia/*) come from Ekklesia's public package registry
+# (platform ADRs 0053 and 0054). Reading needs no account and no token; never put a credential here.
+@ekklesia:registry=https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -12,13 +12,14 @@ Ekklesia and vendors none of its SDKs.
 
 - Module id: `signage`
 - Package: `@ekklesia/signage`
-- Manifest version: 7
+- Manifest version: 8, with the Module Database ABI v1 (`database: { abi: 1 }`)
 
 ## Status
 
-Version 0.1.1 is feature-complete for its declared scope and unreleased. What exists today:
+Version 0.1.2 is feature-complete for its declared scope, and Signage has run in production since
+0.1.1. What exists today:
 
-- The module package, manifest (v7), four capabilities, six permissions, ten operator settings, and
+- The module package, manifest (v8), four capabilities, six permissions, ten operator settings, and
   one logical storage bucket.
 - Eleven tables and a single initial migration, declared non-destructive.
 - Native image ingest: one image per streamed request, 25 MiB, content-addressed, with display and
@@ -34,10 +35,10 @@ Version 0.1.1 is feature-complete for its declared scope and unreleased. What ex
   renderers mounted as browser contributions, the built-in "Content unavailable" slate, deliberate
   blackout, and offline continuation from this display's own persisted state.
 
-Nothing here is deployed, and no cutover from the legacy Announcements container has happened or is
+No cutover from the legacy Announcements container has happened or is planned by this repository.
-planned by this repository. Video, audio, MQTT, Home Assistant, Companion, and a notification outbox
+Video, audio, MQTT, Home Assistant, Companion, and a notification outbox are out of scope; so is
-are out of scope; so is any content module — Signage ships with no announcements, scripture, or
+any content module — Signage ships with no announcements, scripture, or trivia, and cannot render
-trivia, and cannot render any until one is installed.
+any until one is installed.
 
 ### Offline cold start is not yet possible
 
@@ -50,66 +51,71 @@ Mounting requires an authenticated module descriptor, and Core does not yet cach
 cold start depends on a Core-provided authorized offline display descriptor or lease; until that
 exists, this module does not claim it. See ADR 0006.
 
-## Developing against Ekklesia
+## Developing Signage
 
-Signage is developed **inside the authoritative Ekklesia workspace**, checked out at the path it will
+Signage builds and tests on its own. You need no Ekklesia checkout and no Ekklesia account:
-eventually be installed at:
+
+- **Node.js** in the range `engines.node` declares (`>=24.11.0 <25`); `.node-version` names the
+  version CI uses.
+- **pnpm** at the version `packageManager` pins, through Corepack (`corepack enable`).
 
 ```bash
-git clone <ekklesia>            ekklesia
+git clone <this repository> signage
-git clone <this repository>     ekklesia/modules/signage
+cd signage
-cd ekklesia
+corepack enable
-pnpm install
+pnpm install --frozen-lockfile
 ```
 
-`modules/*` is an Ekklesia workspace glob, so the checkout is picked up with no registry edit,
+Ekklesia's module-development packages (`@ekklesia/module-sdk`, `@ekklesia/module-database`,
-no second copy of Ekklesia, and no vendored SDK. `@ekklesia/module-sdk`, `@ekklesia/module-ui-sdk`,
+`@ekklesia/module-ui-sdk`, `@ekklesia/ui`, `@ekklesia/design-tokens`, `@ekklesia/module-ui-build`,
-`@ekklesia/design-tokens`, `@ekklesia/ui`, and `@ekklesia/module-ui-build` all resolve through the
+`@ekklesia/module-pack`, `@ekklesia/typescript-config`) come from Ekklesia's public package registry.
-workspace as `workspace:*` dependencies.
+The committed `.npmrc` points the `@ekklesia` scope at it, and reading it needs **no token** and no
+login (platform ADRs 0053 and 0054); never add a credential to that file. Everything else comes from
+the public npm registry. `package.json` takes the Ekklesia packages as `^0.2.0` ranges, except
+`@ekklesia/module-pack`, which is pinned exactly; `pnpm-lock.yaml` pins every package's exact version
+and integrity, so always install with `--frozen-lockfile` unless you mean to change a dependency.
 
-Two consequences worth knowing:
+`pnpm-workspace.yaml` holds this repository's own pnpm settings: it allows esbuild's install script,
+exempts exactly the Ekklesia package train in the lockfile from pnpm's minimum release age, and keeps
+one narrowly scoped advisory override. It does not make Signage part of any other workspace.
 
-- Ekklesia uses a shared workspace lockfile, so installing here writes an importer entry for
+Signage requires Ekklesia 0.2: manifest version 8 and the Module Database ABI v1 (platform ADR 0050).
-  `modules/signage` into Ekklesia's `pnpm-lock.yaml`. That entry belongs to whoever maintains the
+It reaches PostgreSQL only through the ABI v1 executor the platform hands it, with its own Drizzle
-  Ekklesia checkout; it is not committed from this repository.
+tables and the module-side adapter from `@ekklesia/module-database/drizzle`. Core receives SQL text,
-- Signage requires the Ekklesia platform prerequisites for shared design tokens, module stylesheets,
+bound values, and plain schema metadata, never a Drizzle object.
-  browser contributions, bounded streaming request bodies, and display offline code
-  (ADRs 0039–0043). An Ekklesia checkout without them cannot build or validate this module.
 
 ### Commands
 
-Run from the **Ekklesia repository root**:
-
 ```bash
-pnpm --filter @ekklesia/signage build       # tsc + the canonical module UI build
+pnpm lint        # Biome, with this repository's biome.json
-pnpm --filter @ekklesia/signage test        # unit and browser-artifact tests
+pnpm typecheck   # node, browser, and browser-test projects
-pnpm --filter @ekklesia/signage typecheck   # node, browser, and browser-test projects
+pnpm test        # unit, browser-artifact, and display contract tests (vitest.config.ts)
-pnpm --filter @ekklesia/signage lint
+pnpm build       # tsc, then the canonical module UI build of the primary and display artifacts
-
+pnpm validate    # after build: the built package and its migrations, as the platform reads them
-pnpm boundaries                             # four-layer boundary enforcement
-pnpm modules:validate                       # static manifest, entrypoint, and schema validation
-pnpm migrations:validate                    # migration journal, policy, ordering, and checksums
-pnpm verify                                 # the full Docker-free gate
 ```
 
-Signage's tests are its own: `pnpm test` here runs `vitest` against this package's `vitest.config.ts`,
+CI runs exactly these, from a clean checkout.
-which includes `.test.tsx` as well as `.test.ts`. The workspace-root config includes only `.test.ts`,
-so a browser test added here without that config would be silently skipped.
 
-Never run `pnpm migrations:apply` against a persistent database while developing this module. Signage
+`pnpm validate` uses only the published SDK parsers. It cannot check what only an Ekklesia
-reads no environment variable, constructs no database client, configures no object storage, hardcodes
+installation knows: compatibility with that installation, other installed modules' capabilities and
-no Ekklesia URL, opens no socket of its own, and applies no migration: every one of those reaches it
+dependencies, or a migration's checksum against a database's applied history. Ekklesia checks those
+when Signage is installed.
+
+Never run a migration against a persistent database while developing this module. Signage reads no
+environment variable, constructs no database client, configures no object storage, hardcodes no
+Ekklesia URL, opens no socket of its own, and applies no migration: every one of those reaches it
 through the host.
 
 ### Changing the schema
 
 ```bash
-pnpm --filter @ekklesia/signage migration:generate   # drizzle-kit, into drizzle/
+pnpm migration:generate   # drizzle-kit, into drizzle/
 ```
 
 `tests/schema.test.ts` pins the checksum of the generated SQL, so a regenerated migration fails the
 suite until the pin is updated deliberately. `drizzle/meta/_ekklesia.json` declares the migration
-non-destructive; `pnpm migrations:validate` enforces that.
+non-destructive: `tests/schema.test.ts` asserts it, and Ekklesia's own migration validation enforces
+it when Signage is packaged and installed.
 
 ### Verifying what only a browser can show
 

biome.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
+  "files": {
+    "includes": [
+      "**",
+      "!**/.pnpm-store",
+      "!**/.turbo",
+      "!**/coverage",
+      "!**/dist",
+      "!**/node_modules",
+      "!pnpm-lock.yaml"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  }
+}

ci/check-cleanup.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Checks that Signage's CI cleans up every stack it starts, even when the runner kills a job (the
+# platform's rule: docs/development/security.md, "Disposable stacks never outlive their job").
+#
+#   bash ci/check-cleanup.sh
+#
+# The `integration` job is the one that starts Docker stacks. It must have its own
+# EKKLESIA_CI_JOB_KEY, sweep stale CI stacks before it starts anything, and remove its own in a final
+# `if: always()` step; and the image ci/integration.sh builds must carry the CI labels the sweep finds.
+set -Eeuo pipefail
+
+root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+workflow="$root/.gitea/workflows/ci.yml"
+failures=0
+check() {
+  if eval "$1"; then
+    echo "ok   $2"
+  else
+    echo "FAIL $2"
+    failures=$((failures + 1))
+  fi
+}
+
+# The integration job's lines, from its key to the next job (or the end of the file).
+job="$(awk '/^  integration:$/ { inside = 1; print; next } inside && /^  [a-z][a-z-]*:$/ { exit } inside { print }' "$workflow")"
+line_of() { grep -n -F -- "$1" <<<"$job" | head -1 | cut -d: -f1 || true; }
+
+stale="$(line_of 'ci-sweep.sh --stale')"
+run="$(line_of 'bash ci/integration.sh')"
+own="$(line_of 'ci-sweep.sh --job')"
+last_step="$(grep -n -- "      - name:" <<<"$job" | tail -1 | cut -d: -f1 || true)"
+
+check '[[ -n "$job" ]]' "the workflow has an integration job"
+check 'grep -q "EKKLESIA_CI_JOB_KEY:" <<<"$job"' "the integration job names its stacks with its own key"
+check '[[ -n "$stale" && -n "$run" ]] && ((stale < run))' "it sweeps stale CI stacks before it starts anything"
+check '[[ -n "$own" && -n "$run" ]] && ((own > run)) && ((own > last_step))' \
+  "its last step removes its own stacks"
+check 'sed -n "${last_step},\$p" <<<"$job" | grep -q "if: always()"' "that last step always runs"
+check 'grep -q "EKKLESIA_CI_LABEL" "$root/ci/integration.sh" && grep -q "EKKLESIA_CI_CREATED_LABEL" "$root/ci/integration.sh"' \
+  "the image ci/integration.sh builds carries the CI labels"
+
+((failures == 0)) || {
+  echo "check-cleanup: ${failures} check(s) failed." >&2
+  exit 1
+}

ci/display-scenarios

@@ -0,0 +1,7 @@
+# The platform's display-device scenarios this repository's CI runs against Signage, one per line
+# (scripts/lib/deploy-smoke-display.mjs in the pinned platform). Pairing a kiosk and restarting it on
+# the same profile always run first. A change that makes another scenario pass adds it here.
+two-pages
+session-blip
+stream-failure
+stream-recycle

ci/integration.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Signage inside Ekklesia, end to end: builds the deployment image from the assembled workspace with
+# the platform's own Dockerfile, then runs the platform's split-topology deployment smoke against it
+# with the display-device scenarios listed in ci/display-scenarios. A disposable PostgreSQL and object
+# store, generated secrets, and an explicit migration apply against that fresh database only; nothing
+# is pushed, published, or logged in to. The image is removed afterwards.
+#
+#   bash ci/integration.sh
+#
+# NOT RUN: the integration job is disabled (.gitea/workflows/ci.yml says why). This script still
+# expects Ekklesia's deployment tree at build/workspace, which the removed ci/assemble.sh used to
+# build; it is rewritten when Signage is installed into the generic image as a Module Package.
+set -Eeuo pipefail
+
+root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+workspace="$root/build/workspace"
+[[ -f "$workspace/deploy/Dockerfile" ]] || {
+  echo "integration: Ekklesia's deployment tree is not at build/workspace." >&2
+  exit 1
+}
+
+# Named and labeled as a CI stack of this run and job (the platform's scripts/lib/ci-project.sh), so
+# the workflow's final `ci-sweep.sh --job` removes it even if this script is killed before its trap.
+# shellcheck source=/dev/null
+source "$workspace/scripts/lib/ci-project.sh"
+project="$(ci_project_name signage-image)"
+image="${project}:latest"
+trap 'docker image rm --force "$image" >/dev/null 2>&1 || true' EXIT
+
+scenarios="$(sed -e 's/#.*//' -e '/^[[:space:]]*$/d' "$root/ci/display-scenarios" | tr '\n' ' ')"
+[[ -n "${scenarios// /}" ]] || {
+  echo "integration: ci/display-scenarios lists no scenario." >&2
+  exit 1
+}
+
+DOCKER_BUILDKIT=1 docker build --quiet --file "$workspace/deploy/Dockerfile" --tag "$image" \
+  --label "${EKKLESIA_CI_LABEL}=${project}" --label "${EKKLESIA_CI_CREATED_LABEL}=$(date +%s)" \
+  "$workspace" >/dev/null
+echo "integration: built the deployment image with Signage; scenarios: ${scenarios}"
+
+cd "$workspace"
+EKKLESIA_SMOKE_TOPOLOGY=split \
+  EKKLESIA_SMOKE_IMAGE="$image" \
+  EKKLESIA_SMOKE_DISPLAY_DEVICE=1 \
+  EKKLESIA_SMOKE_DISPLAY_SCENARIOS="$scenarios" \
+  EKKLESIA_SMOKE_WATCH_MS=120000 \
+  EKKLESIA_SMOKE_RECYCLE_WATCH_MS=120000 \
+  bash scripts/smoke-deploy.sh

ekklesia.module.json

@@ -1,12 +1,15 @@
 {
-  "manifestVersion": 7,
+  "manifestVersion": 8,
   "id": "signage",
   "name": "Signage",
   "description": "Visual programming, timelines, synchronized channels, and display delivery for church screens.",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
+  },
+  "database": {
+    "abi": 1
   },
   "capabilities": [
     {

package.json

@@ -1,8 +1,13 @@
 {
   "name": "@ekklesia/signage",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": true,
+  "license": "AGPL-3.0-or-later",
   "type": "module",
+  "packageManager": "[email protected]",
+  "engines": {
+    "node": ">=24.11.0 <25"
+  },
   "description": "Ekklesia's visual programming, timeline, synchronization, and display-delivery module.",
   "files": [
     "dist",
@@ -23,24 +28,27 @@
     "build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui",
     "lint": "biome lint .",
     "migration:generate": "drizzle-kit generate --config=drizzle.config.ts",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/signage",
+    "prepack": "pnpm run build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json && tsc --noEmit --project tsconfig.ui-test.json"
+    "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json && tsc --noEmit --project tsconfig.ui-test.json",
+    "validate": "node scripts/validate-module.mjs"
   },
   "dependencies": {
-    "@ekklesia/design-tokens": "workspace:*",
+    "@ekklesia/design-tokens": "^0.2.3",
-    "@ekklesia/module-sdk": "workspace:*",
+    "@ekklesia/module-database": "^0.2.3",
-    "@ekklesia/module-ui-sdk": "workspace:*",
+    "@ekklesia/module-sdk": "^0.2.3",
-    "@ekklesia/ui": "workspace:*",
+    "@ekklesia/module-ui-sdk": "^0.2.3",
+    "@ekklesia/ui": "^0.2.3",
     "drizzle-orm": "0.45.2",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "sharp": "0.35.4"
+    "sharp": "0.35.5"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
-    "@ekklesia/module-ui-build": "workspace:*",
+    "@ekklesia/module-pack": "0.2.3",
-    "@ekklesia/typescript-config": "workspace:*",
+    "@ekklesia/module-ui-build": "^0.2.3",
+    "@ekklesia/typescript-config": "^0.2.3",
     "@types/node": "24.13.3",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",

pnpm-workspace.yaml

@@ -0,0 +1,30 @@
+# This repository's own pnpm settings. Signage is a single standalone package, not part of any other
+# workspace; pnpm reads its settings from this file.
+
+# esbuild, which the module UI build and the module packager run, has an install script. pnpm runs
+# none it was not told to.
+allowBuilds:
+  esbuild: true
+
+# pnpm holds back any package younger than its minimum release age, and refuses a lockfile that names
+# one. A new Ekklesia package train is that young on its release day. These exact versions, and only
+# these, are the train this lockfile pins (published by Ekklesia's release workflow, ADR 0053), so
+# they are exempt by version; a train bump replaces them, and everything else keeps the policy.
+minimumReleaseAgeExclude:
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+  - '@ekklesia/[email protected]'
+
+# The narrowly scoped advisory remediation Signage had while it was built inside Ekklesia's workspace,
+# kept now that it is not. GHSA-67mh-4wv8-2f99 (moderate): the vulnerable esbuild 0.18.20 is reached
+# only through the deprecated @esbuild-kit/core-utils (drizzle-kit -> @esbuild-kit/esm-loader), whose
+# pinned range predates the fix. Scoped to that one edge, exactly as Ekklesia's own workspace does,
+# so drizzle-kit's direct esbuild and Vite's are not dragged to another version.
+overrides:
+  "@esbuild-kit/core-utils>esbuild": "0.25.12"

scripts/validate-module.mjs

@@ -0,0 +1,145 @@
+// Validates the built Signage package and its migrations the way the platform reads them, with only
+// Ekklesia's published module-development packages: no Ekklesia checkout, no database.
+//
+//   pnpm build && pnpm validate
+//
+// What it checks:
+//   - the manifest parses, and its id and version match package.json and the built runtime;
+//   - every declared entrypoint exists in the built package;
+//   - the built runtime declares the same Module Database ABI as the manifest (Core refuses a
+//     mismatch);
+//   - the built schema entrypoint's only export is plain ABI v1 metadata for this module's own,
+//     namespaced tables, and every foreign key targets one of them;
+//   - the installed module SDK satisfies the manifest's `compatibility.moduleSdk`;
+//   - the migration journal and policy parse, name the same migrations in the same order, and every
+//     migration's SQL is present.
+//
+// What it cannot check, because only Ekklesia itself can: compatibility with a particular platform
+// installation, capability and module dependencies between installed modules, and a migration's
+// checksum against a database's applied history. The module packager and the platform's package
+// verifier re-check all of the above when Signage is built as a Module Package.
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { defineModuleSchemaMetadata, moduleTablePrefix } from "@ekklesia/module-database";
+import {
+  parseDrizzleMigrationJournal,
+  parseModuleManifest,
+  parseModuleMigrationPolicy,
+} from "@ekklesia/module-sdk";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const failures = [];
+const passes = [];
+
+function check(condition, description) {
+  (condition ? passes : failures).push(description);
+}
+
+async function json(relative) {
+  return JSON.parse(await readFile(new URL(relative, pathToFileURL(root)), "utf8"));
+}
+
+async function exists(relative) {
+  try {
+    return (await stat(new URL(relative, pathToFileURL(root)))).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** A caret range, `^X.Y.Z`, as the platform's manifests write them. Anything else is refused here
+ * rather than half understood. */
+function satisfiesCaret(version, range) {
+  const wanted = /^\^(\d+)\.(\d+)\.(\d+)$/u.exec(range);
+  const actual = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version);
+  if (!wanted || !actual) {
+    return false;
+  }
+  const [w, a] = [wanted.slice(1).map(Number), actual.slice(1).map(Number)];
+  if (w[0] !== a[0] || (w[0] === 0 && w[1] !== a[1])) {
+    return false;
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== w[index]) {
+      return a[index] > w[index];
+    }
+  }
+  return true;
+}
+
+const packageJson = await json("package.json");
+const manifest = parseModuleManifest(await json("ekklesia.module.json"));
+check(true, "ekklesia.module.json is a valid manifest");
+check(packageJson.version === manifest.version, "package.json and the manifest name one version");
+check(packageJson.type === "module", "the package is ESM");
+check(packageJson.ekklesia?.layer === "module", "the package carries the module layer marker");
+
+const { server, schema, migrations, ui, display } = manifest.entrypoints;
+for (const entrypoint of [server, schema, ui, display?.artifact].filter(Boolean)) {
+  check(await exists(entrypoint), `the built package has ${entrypoint}`);
+}
+
+const runtime = (await import(new URL(server, pathToFileURL(root)).href)).default;
+check(runtime?.id === manifest.id, "the built runtime's id is the manifest's");
+check(runtime?.version === manifest.version, "the built runtime's version is the manifest's");
+check(
+  JSON.stringify(runtime?.database ?? null) === JSON.stringify(manifest.database ?? null),
+  "the built runtime declares the manifest's database ABI",
+);
+
+if (schema) {
+  const namespace = await import(new URL(schema, pathToFileURL(root)).href);
+  check(
+    Object.keys(namespace).join() === "default",
+    "the schema entrypoint exports nothing but its metadata",
+  );
+  const metadata = defineModuleSchemaMetadata(namespace.default);
+  check(
+    JSON.stringify(JSON.parse(JSON.stringify(metadata))) === JSON.stringify(metadata),
+    "the schema metadata is plain data",
+  );
+  check(metadata.moduleId === manifest.id, "the schema metadata is this module's");
+  const prefix = moduleTablePrefix(manifest.id);
+  const owned = new Set(metadata.tables.map((table) => table.name));
+  check(
+    metadata.tables.every((table) => table.name.startsWith(prefix)),
+    `every table is in the ${prefix} namespace`,
+  );
+  check(
+    metadata.tables.every((table) => table.foreignKeys.every((key) => owned.has(key.table))),
+    "every foreign key targets one of this module's own tables",
+  );
+}
+
+const sdkVersion = (await json("node_modules/@ekklesia/module-sdk/package.json")).version;
+check(
+  satisfiesCaret(sdkVersion, manifest.compatibility.moduleSdk),
+  `the installed module SDK ${sdkVersion} satisfies compatibility.moduleSdk ${manifest.compatibility.moduleSdk}`,
+);
+
+if (migrations) {
+  const directory = migrations.endsWith("/") ? migrations : `${migrations}/`;
+  const journal = parseDrizzleMigrationJournal(await json(`${directory}meta/_journal.json`));
+  const policy = parseModuleMigrationPolicy(await json(`${directory}meta/_ekklesia.json`));
+  check(policy.moduleId === manifest.id, "the migration policy is this module's");
+  check(
+    journal.entries.map((entry) => entry.tag).join() ===
+      policy.entries.map((entry) => entry.tag).join(),
+    "the migration journal and policy name the same migrations in the same order",
+  );
+  for (const entry of journal.entries) {
+    check(await exists(`${directory}${entry.tag}.sql`), `${entry.tag}.sql is present`);
+  }
+}
+
+for (const description of passes) {
+  console.log(`ok   ${description}`);
+}
+for (const description of failures) {
+  console.log(`FAIL ${description}`);
+}
+if (failures.length > 0) {
+  console.error(`validate: ${failures.length} check(s) failed.`);
+  process.exit(1);
+}
+console.log(`validate: ${manifest.id}@${manifest.version} passed ${passes.length} checks.`);

src/browser/backoff.ts

@@ -0,0 +1,21 @@
+/**
+ * How long a display waits before trying a failed request again.
+ *
+ * Exponential from one second to a one-minute ceiling, so a screen whose server is restarting is
+ * back within seconds, and one whose server is down for an evening asks once a minute rather than
+ * hammering it. The wait is jittered between half and all of that step, so a building's worth of
+ * screens that lost the server at the same moment do not all come back at the same moment.
+ *
+ * There is no attempt limit. A television on a wall has nobody to press Retry, so giving up is the
+ * one thing it must never do.
+ */
+export const DISPLAY_RETRY_BASE_MS = 1_000;
+export const DISPLAY_RETRY_MAX_MS = 60_000;
+
+export function displayRetryDelayMs(attempt: number, random: () => number = Math.random): number {
+  const step = Math.min(
+    DISPLAY_RETRY_MAX_MS,
+    DISPLAY_RETRY_BASE_MS * 2 ** Math.min(Math.max(0, attempt), 16),
+  );
+  return Math.round(step / 2 + (step / 2) * Math.min(1, Math.max(0, random())));
+}

src/browser/storage.ts

@@ -36,6 +36,9 @@ export interface SignageMediaCache {
    * can never leave a screen with less than it had. */
   prune(keep: readonly string[]): Promise<void>;
   count(): Promise<number>;
+  /** Gives back every local URL this cache handed out. Called when a display stops; a URL handed
+   * out before this is no longer valid afterwards. */
+  release(): void;
 }
 
 /** The stable key a native image's bytes are cached under. Deliberately built from identity, never
@@ -86,6 +89,9 @@ export function createMemoryMediaCache(): SignageMediaCache {
       }
       return Promise.resolve();
     },
+    release(): void {
+      // Holds plain URLs, nothing the browser has to be given back.
+    },
     store(key: string, url: string): Promise<string | undefined> {
       stored.set(key, url);
       return Promise.resolve(url);
@@ -179,14 +185,45 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
     return `${origin}/${key}`;
   }
 
-  async function localUrl(cache: Cache, url: string): Promise<string | undefined> {
+  /**
-    const response = await cache.match(url);
+   * The one object URL each cached slide is rendered from, by cache entry.
+   *
+   * An object URL pins its blob in the browser until it is revoked. Every state refresh looks every
+   * cached slide up again, so minting a URL per lookup leaked a blob per slide per refresh, and
+   * within minutes the browser refused the display's own requests for want of resources. So each
+   * entry gets exactly one URL, revoked when the entry is pruned or replaced, and all of them when
+   * the display stops.
+   */
+  const objectUrls = new Map<string, string>();
+
+  function forget(request: string): void {
+    const url = objectUrls.get(request);
+    if (url !== undefined) {
+      objectUrls.delete(request);
+      URL.revokeObjectURL(url);
+    }
+  }
+
+  async function localUrl(cache: Cache, request: string): Promise<string | undefined> {
+    const existing = objectUrls.get(request);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const response = await cache.match(request);
     if (!response) {
       return undefined;
     }
     try {
       const blob = await response.blob();
-      return URL.createObjectURL(blob);
+      // Two lookups of one slide can be in flight at once; the first to finish wins, and the other
+      // gives its URL straight back rather than leaving it pinned.
+      const raced = objectUrls.get(request);
+      if (raced !== undefined) {
+        return raced;
+      }
+      const url = URL.createObjectURL(blob);
+      objectUrls.set(request, url);
+      return url;
     } catch {
       return undefined;
     }
@@ -220,6 +257,7 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
         for (const request of await cache.keys()) {
           if (!retained.has(request.url)) {
             await cache.delete(request);
+            forget(request.url);
           }
         }
       } catch {
@@ -227,6 +265,12 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
       }
     },
 
+    release(): void {
+      for (const request of [...objectUrls.keys()]) {
+        forget(request);
+      }
+    },
+
     async store(key: string, url: string): Promise<string | undefined> {
       const cache = await open();
       if (!cache) {
@@ -242,6 +286,8 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
         // Stored under the *stable* key, so the next refresh's freshly signed URL finds these
         // bytes instead of downloading them again.
         await cache.put(cacheRequest(key), response.clone());
+        // New bytes under this key: the URL for the old ones is given back before one is made.
+        forget(cacheRequest(key));
         return localUrl(cache, cacheRequest(key));
       } catch {
         return undefined;

src/display/controller.ts

@@ -1,4 +1,5 @@
 import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
+import { displayRetryDelayMs } from "../browser/backoff.js";
 import {
   type OfflineSnapshot,
   resolveOffline,
@@ -18,6 +19,13 @@ import {
   type SignageMediaCache,
   signageMediaKey,
 } from "../browser/storage.js";
+import {
+  type DisplayChannelState,
+  type DisplayHeartbeat,
+  type DisplayRealtimeGroup,
+  parseViewerSessionResponse,
+  type ViewerSessionResponse,
+} from "../shared/display-protocol.js";
 
 /**
  * The display: what it fetches, what it shows, and what it reports.
@@ -38,36 +46,11 @@ const SNAPSHOT_STORAGE = "last-known-good";
  * must not sit on a stale frame until the next; and a delivery URL has a finite life. */
 const REFRESH_INTERVAL_MS = 4 * 60 * 1000;
 
-export interface DisplayChannelStateView {
+/** The channel state a display renders, exactly as the server sends it (`src/shared`). */
-  readonly serverNowMs: number;
+export type DisplayChannelStateView = DisplayChannelState;
-  readonly channel: { readonly id: string; readonly key: string; readonly groupId: string };
-  readonly crossfadeMs: number;
-  readonly playback: {
-    readonly revision: number;
-    readonly transport: string;
-    readonly blackout: boolean;
-    readonly remainingMs: number | null;
-    readonly selectionRevision: number | null;
-    readonly currentSelectionId: string | null;
-    readonly currentSlotId: string | null;
-    readonly activeTimelineId: string | null;
-    readonly pendingTimelineId: string | null;
-    readonly startedAtMs: number | null;
-    readonly deadlineAtMs: number | null;
-  };
-  readonly timeline: OfflineSnapshot["timeline"];
-  readonly current: SceneSelection | null;
-  readonly staticHold: SceneSelection | null;
-  readonly selections: readonly SceneSelection[];
-}
 
-export interface DisplaySessionView {
+/** The display's registration, exactly as the server answers it (`src/shared`). */
-  readonly viewerId: string;
+export type DisplaySessionView = ViewerSessionResponse;
-  readonly channelId: string;
-  readonly channelKey: string;
-  readonly groupId: string;
-  readonly heartbeatIntervalMs: number;
-}
 
 /** What an operator can see about this screen, and what a test asserts on. Sanitized by
  * construction: identity, counts, and a code. */
@@ -140,6 +123,13 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
   let snapshot: OfflineSnapshot | undefined;
   let offlineActive = false;
   let offlineHandle: unknown;
+  /** Retries, each on its own backoff. A display has nobody to press Retry, so none of them give up;
+   * each resets once its request works again. */
+  let sessionHandle: unknown;
+  let sessionAttempt = 0;
+  let refreshAttempt = 0;
+  let realtimeHandle: unknown;
+  let realtimeAttempt = 0;
   /** Selections this display has tried and failed to render. A broken item is skipped rather than
    * retried in a tight loop, which is what keeps one bad slide from becoming a flicker. */
   const unusable = new Set<string>();
@@ -515,39 +505,142 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
         `channels/${session.channelId}/display-state`,
       );
       if (!response.ok) {
-        online = false;
+        await refreshFailed();
-        await runOffline();
         return;
       }
-      await apply((await response.json()) as DisplayChannelStateView);
+      const state = (await response.json()) as DisplayChannelStateView;
+      refreshAttempt = 0;
+      await apply(state);
     } catch {
-      // The server is unreachable. The frame stays and local continuation takes over; nothing about
+      await refreshFailed();
-      // a network failure belongs on a lobby wall.
-      online = false;
-      await runOffline();
     }
   }
 
+  /**
+   * The server is unreachable, or answered with an error. The frame stays and local continuation
+   * takes over — nothing about a network failure belongs on a lobby wall — and the refresh is tried
+   * again on its own, because a realtime message that would otherwise prompt it may never come.
+   */
+  async function refreshFailed(): Promise<void> {
+    online = false;
+    await runOffline();
+    if (stopped) {
+      return;
+    }
+    if (refreshHandle !== undefined) {
+      clearTimer(refreshHandle);
+    }
+    refreshHandle = setTimer(() => {
+      refreshHandle = undefined;
+      void refresh();
+    }, displayRetryDelayMs(refreshAttempt));
+    refreshAttempt += 1;
+  }
+
+  /**
+   * Registers this display, and keeps trying until it can.
+   *
+   * Until it has registered, a display continues from its own persisted state, honestly marked as
+   * offline. The first registration that works brings it live — realtime, heartbeats, and fresh
+   * state — exactly as if it had worked the first time.
+   */
+  async function register(): Promise<void> {
+    if (stopped || session) {
+      return;
+    }
+    let registered: DisplaySessionView | undefined;
+    try {
+      const response = await options.context.api.request("viewers/session", {
+        body: JSON.stringify({ viewerKey: await viewerKey() }),
+        headers: { "content-type": "application/json" },
+        method: "POST",
+      });
+      if (response.ok) {
+        // Read, not cast: a registration the display cannot understand is no registration, and is
+        // tried again like any other failure.
+        const parsed = parseViewerSessionResponse(await response.json());
+        registered = parsed.ok ? parsed.value : undefined;
+      }
+    } catch {
+      registered = undefined;
+    }
+    if (stopped) {
+      return;
+    }
+    if (!registered) {
+      online = false;
+      report();
+      sessionHandle = setTimer(() => {
+        sessionHandle = undefined;
+        void register();
+      }, displayRetryDelayMs(sessionAttempt));
+      sessionAttempt += 1;
+      return;
+    }
+    sessionAttempt = 0;
+    session = registered;
+    online = true;
+    subscribe();
+    heartbeatHandle = setInterval(
+      () => void heartbeat(),
+      registered.heartbeatIntervalMs,
+    ) as unknown;
+    await refresh();
+    void heartbeat();
+    report();
+  }
+
+  /**
+   * Subscribes to the display's realtime channel, and again whenever the host reports that a
+   * subscription has ended for good. The host retries ordinary disconnects itself; a stream that
+   * is refused outright ends, and until this resubscribes the display would only learn of changes
+   * at its next slot deadline.
+   */
+  function subscribe(): void {
+    if (stopped || !session) {
+      return;
+    }
+    subscription?.close();
+    subscription = options.context.realtime.subscribe("display-state", {
+      onSnapshot: (state) => onRealtime(state),
+      onStatus: (status) => {
+        online = status === "connected";
+        if (status === "connected") {
+          realtimeAttempt = 0;
+        } else if (status === "closed" && !stopped && realtimeHandle === undefined) {
+          realtimeHandle = setTimer(() => {
+            realtimeHandle = undefined;
+            subscribe();
+          }, displayRetryDelayMs(realtimeAttempt));
+          realtimeAttempt += 1;
+        }
+        report();
+      },
+      onUpdate: (state) => onRealtime(state),
+    });
+  }
+
   async function heartbeat(): Promise<void> {
     if (stopped || !session || !telemetry) {
       return;
     }
     try {
+      // Built as the shared message type, which is the same type the route parses with.
+      const report: DisplayHeartbeat = {
+        cachedAssetCount,
+        error: lastError === undefined ? null : { code: lastError.code, detail: lastError.detail },
+        offlineReady: snapshot !== undefined && snapshot.selections.length > 0,
+        reportedContributionId:
+          lastState?.current?.renderer.kind === "contribution"
+            ? lastState.current.renderer.contributionId
+            : null,
+        reportedPlaybackRevision: appliedRevision >= 0 ? appliedRevision : null,
+        reportedProviderId: lastState?.current?.providerId ?? null,
+        reportedSelectionId: renderedSelectionId ?? null,
+        reportedTimelineId: lastState?.playback.activeTimelineId ?? null,
+      };
       await options.context.api.request(`viewers/${session.viewerId}/heartbeat`, {
-        body: JSON.stringify({
+        body: JSON.stringify(report),
-          cachedAssetCount,
-          error:
-            lastError === undefined ? null : { code: lastError.code, detail: lastError.detail },
-          offlineReady: snapshot !== undefined && snapshot.selections.length > 0,
-          reportedContributionId:
-            lastState?.current?.renderer.kind === "contribution"
-              ? lastState.current.renderer.contributionId
-              : null,
-          reportedPlaybackRevision: appliedRevision >= 0 ? appliedRevision : null,
-          reportedProviderId: lastState?.current?.providerId ?? null,
-          reportedSelectionId: renderedSelectionId ?? null,
-          reportedTimelineId: lastState?.playback.activeTimelineId ?? null,
-        }),
         headers: { "content-type": "application/json" },
         method: "POST",
       });
@@ -595,36 +688,7 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
       }
 
       if (telemetry) {
-        try {
+        await register();
-          const response = await options.context.api.request("viewers/session", {
-            body: JSON.stringify({ viewerKey: await viewerKey() }),
-            headers: { "content-type": "application/json" },
-            method: "POST",
-          });
-          if (response.ok) {
-            session = (await response.json()) as DisplaySessionView;
-            online = true;
-          }
-        } catch {
-          online = false;
-        }
-      }
-
-      if (session) {
-        subscription = options.context.realtime.subscribe("display-state", {
-          onSnapshot: (state) => onRealtime(state),
-          onStatus: (status) => {
-            online = status === "connected";
-            report();
-          },
-          onUpdate: (state) => onRealtime(state),
-        });
-        heartbeatHandle = setInterval(
-          () => void heartbeat(),
-          session.heartbeatIntervalMs,
-        ) as unknown;
-        await refresh();
-        void heartbeat();
       }
       report();
     },
@@ -641,9 +705,18 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
         clearTimer(refreshHandle);
         refreshHandle = undefined;
       }
+      for (const handle of [sessionHandle, realtimeHandle]) {
+        if (handle !== undefined) {
+          clearTimer(handle);
+        }
+      }
+      sessionHandle = undefined;
+      realtimeHandle = undefined;
       exitOffline();
       await stage?.destroy();
       stage = undefined;
+      // After the stage is gone, so nothing on screen still points at a released URL.
+      media.release();
     },
   };
 
@@ -656,7 +729,10 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
     if (stopped || !session) {
       return;
     }
-    const groups = (payload as { groups?: readonly Record<string, unknown>[] } | null)?.groups;
+    // Checked at run time as well as typed: realtime state is the platform's transport, and a frame
+    // this display cannot read is simply not one it acts on.
+    const groups = (payload as { groups?: readonly Partial<DisplayRealtimeGroup>[] } | null)
+      ?.groups;
     if (!Array.isArray(groups)) {
       return;
     }

src/display/index.tsx

@@ -59,7 +59,7 @@ function SignageDisplay({ context }: { readonly context: ModuleUiHostContext }):
  */
 export default defineModuleUi({
   id: "signage",
-  version: "0.1.1",
+  version: "0.1.2",
   styles: displayStyles,
   mount(container, context) {
     const root = createRoot(container);

src/schema/index.ts

@@ -1,4 +1,4 @@
-import { defineModuleSchema } from "@ekklesia/module-sdk";
+import { moduleDrizzleSchemaMetadata } from "@ekklesia/module-database/drizzle";
 import {
   channelGroups,
   channels,
@@ -13,7 +13,16 @@ import {
   viewers,
 } from "./tables.js";
 
-export {
+/**
+ * Signage's compiled schema entrypoint: the plain Module Database ABI v1 metadata Core validates
+ * table ownership from (platform ADR 0050) — each table's physical name and the tables its foreign
+ * keys target, as strings and arrays.
+ *
+ * Derived on this side from the same Drizzle tables `tables.ts` declares, so it cannot drift from
+ * them, and deliberately the **only** export: Core never receives a Drizzle object from Signage.
+ * Side-effect free by contract — importing this connects to nothing and reads nothing.
+ */
+export default moduleDrizzleSchemaMetadata("signage", {
   channelGroups,
   channels,
   imageAssets,
@@ -22,29 +31,7 @@ export {
   providerSources,
   selections,
   selectionVariants,
-  timelineSlots,
   timelines,
+  timelineSlots,
   viewers,
-} from "./tables.js";
-
-/**
- * Signage's compiled schema entrypoint: the same table objects `tables.ts` declares, wrapped with the
- * ownership marker Core validates during discovery. Side-effect free by contract — importing this
- * connects to nothing and reads nothing.
- */
-export default defineModuleSchema({
-  moduleId: "signage",
-  tables: {
-    channelGroups,
-    channels,
-    imageAssets,
-    imageRenditions,
-    playbackStates,
-    providerSources,
-    selections,
-    selectionVariants,
-    timelines,
-    timelineSlots,
-    viewers,
-  },
 });

src/schema/tables.ts

@@ -17,9 +17,10 @@ import {
  * Signage's own PostgreSQL tables.
  *
  * Kept to **pure Drizzle declarations** so the stable Drizzle Kit generator can load this file
- * without executing the ESM Module SDK wrapper; `./index.ts` wraps these same objects with the
+ * without executing any Ekklesia package; `./index.ts` derives the plain schema metadata Core
- * ownership marker Core validates. The required `signage_` namespace is applied once here, and Core
+ * validates from these same objects, and only Signage's own store code ever uses them as Drizzle
- * validates it independently of this helper.
+ * tables. The required `signage_` namespace is applied once here, and Core validates it
+ * independently of this helper.
  *
  * Two rules hold everywhere below, and both are architecture rather than style:
  *

src/server/display/state.ts

@@ -1,4 +1,9 @@
 import type { ModuleStorage } from "@ekklesia/module-sdk";
+import type {
+  DisplayChannelState as DisplayChannelStateWire,
+  DisplaySelection,
+  DisplayTimeline,
+} from "../../shared/display-protocol.js";
 import {
   resolveNativeScene,
   SIGNAGE_NATIVE_PROVIDER_ID,
@@ -35,78 +40,21 @@ import type {
  * and a display refreshes state long before one lapses.
  */
 
-export interface DisplayMedia {
+export type {
-  readonly url: string;
+  DisplayMedia,
-  readonly expiresAtMs: number;
+  DisplaySelection,
-  readonly width: number;
+  DisplayTimeline,
-  readonly height: number;
+  DisplayTimelineSlot,
-}
+} from "../../shared/display-protocol.js";
 
-export interface DisplaySelection {
+/**
-  readonly id: string;
+ * The channel state the server builds: the wire shape a display reads (`src/shared`), plus the
-  readonly revision: number;
+ * channel's name and the group's whole playback snapshot. Declared as an extension so that a field
-  readonly slotId: string | null;
+ * the display relies on cannot be renamed or retyped here without failing to compile.
-  readonly providerId: string;
+ */
-  readonly itemId: string;
+export interface DisplayChannelState extends DisplayChannelStateWire {
-  readonly itemRevision: string;
+  readonly channel: DisplayChannelStateWire["channel"] & { readonly name: string };
-  readonly startedAtMs: number | null;
-  readonly deadlineAtMs: number | null;
-  readonly durationMs: number;
-  readonly availableUntilMs: number | null;
-  readonly withdrawn: boolean;
-  readonly stale: boolean;
-  /** `native-image` is drawn by Signage's own display code; `contribution` is mounted through the
-   * platform's contribution ABI by id. A display never receives a URL for either. */
-  readonly renderer:
-    | { readonly kind: "native-image" }
-    | {
-        readonly kind: "contribution";
-        readonly contributionId: string;
-        readonly contributionVersion: string;
-      }
-    | { readonly kind: "unavailable" };
-  /** The provider's own payload for this channel's audience, or its default. */
-  readonly payload: unknown;
-  readonly presentation: unknown;
-  /** Native images only: fresh delivery URLs, and the already-resolved scene. */
-  readonly media?: { readonly display: DisplayMedia; readonly thumbnail: DisplayMedia };
-  readonly scene?: ReturnType<typeof resolveNativeScene>;
-}
-
-export interface DisplayTimelineSlot {
-  readonly id: string;
-  readonly position: number;
-  readonly enabled: boolean;
-  readonly eligibleFromMs: number | null;
-  readonly eligibleUntilMs: number | null;
-  readonly estimatedDurationMs: number;
-}
-
-export interface DisplayTimeline {
-  readonly id: string;
-  readonly revision: number;
-  readonly eligibleFromMs: number | null;
-  readonly eligibleUntilMs: number | null;
-  readonly slots: readonly DisplayTimelineSlot[];
-}
-
-export interface DisplayChannelState {
-  readonly serverNowMs: number;
-  readonly channel: {
-    readonly id: string;
-    readonly key: string;
-    readonly name: string;
-    readonly groupId: string;
-  };
-  readonly crossfadeMs: number;
   readonly playback: PlaybackSnapshot;
-  readonly timeline: DisplayTimeline | null;
-  readonly current: DisplaySelection | null;
-  /** The held image, already resolved as a scene. Separate from `current` because a static hold sits
-   * *over* a preserved cursor rather than replacing it. */
-  readonly staticHold: DisplaySelection | null;
-  /** Bounded, newest first. Material for offline continuation, never a substitute for authority. */
-  readonly selections: readonly DisplaySelection[];
 }
 
 /** How many resolved selections travel to a display. Enough to cover a pattern and then some, small

src/server/routes/viewers.ts

@@ -1,13 +1,14 @@
 import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
+import {
+  type DisplayHeartbeatResponse,
+  type ProtocolResult,
+  parseDisplayHeartbeat,
+  parseViewerSessionRequest,
+  type ViewerSessionResponse,
+} from "../../shared/display-protocol.js";
 import { buildDisplayChannelState } from "../display/state.js";
 import { SignageError, signageBoundary } from "../errors.js";
-import {
+import { optionalString, readJsonObject, requireUuidParam } from "../http.js";
-  optionalBoolean,
-  optionalInteger,
-  optionalString,
-  readJsonObject,
-  requireUuidParam,
-} from "../http.js";
 import type { SignagePlaybackService } from "../playback/service.js";
 import type { SignageProviderRegistry } from "../providers/registry.js";
 import { readSignageSettings } from "../settings.js";
@@ -21,12 +22,24 @@ import {
   updateViewerAssignment,
 } from "../viewers/service.js";
 
-const OPAQUE_ID = /^[\w][\w.:-]{0,199}$/u;
+/** How a route reaches Signage's tables. Production uses the module database; the display contract
+ * test supplies the in-memory store so the real handlers can answer the real display controller. */
+/** How often a display checks in. Sent to the display rather than built into it, so the server can
+ * change its own expectations without a display deployment. */
+export const SIGNAGE_HEARTBEAT_INTERVAL_MS = 12_000;
 
-function store(context: ModuleRouteHandlerContext): SignageStore {
+/** A display message the shared protocol refused, as Signage's own sanitized code naming the field. */
-  return createSignageStore(context.services.database);
+function accepted<Value>(result: ProtocolResult<Value>): Value {
+  if (!result.ok) {
+    throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: result.field });
+  }
+  return result.value;
 }
 
+export type ViewerRouteStore = (context: ModuleRouteHandlerContext) => SignageStore;
+
+const databaseStore: ViewerRouteStore = (context) => createSignageStore(context.services.database);
+
 /**
  * The safe Core device identifier, when the caller is a paired display.
  *
@@ -57,6 +70,7 @@ export function registerViewerRoutes(
   http: ModuleHttpRouteRegistrar,
   playback: () => SignagePlaybackService,
   registry: () => SignageProviderRegistry,
+  store: ViewerRouteStore = databaseStore,
 ): void {
   http.route({
     method: "POST",
@@ -65,11 +79,7 @@ export function registerViewerRoutes(
     maxBodyBytes: 2048,
     handler(request, context) {
       return signageBoundary(async () => {
-        const body = await readJsonObject(request);
+        const { viewerKey } = accepted(parseViewerSessionRequest(await readJsonObject(request)));
-        const viewerKey = body.viewerKey;
-        if (typeof viewerKey !== "string") {
-          throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "viewerKey" });
-        }
         // A display registers with the identity it keeps in its own IndexedDB and lands on the
         // default channel. It never chooses one: a public screen that could would let anyone who
         // reaches the page decide what a wall shows (ADR 0004).
@@ -79,14 +89,15 @@ export function registerViewerRoutes(
           store: store(context),
           viewerKey,
         });
-        return Response.json({
+        const response: ViewerSessionResponse = {
           channelId: session.channel.id,
           channelKey: session.channel.key,
           groupId: session.groupId,
-          heartbeatIntervalMs: 12_000,
+          heartbeatIntervalMs: SIGNAGE_HEARTBEAT_INTERVAL_MS,
           viewerId: session.viewer.id,
           viewerName: session.viewer.name,
-        });
+        };
+        return Response.json(response);
       });
     },
   });
@@ -99,52 +110,21 @@ export function registerViewerRoutes(
     handler(request, context) {
       return signageBoundary(async () => {
         const viewerId = requireUuidParam(context, "viewerId");
-        const body = await readJsonObject(request);
+        const heartbeat = accepted(parseDisplayHeartbeat(await readJsonObject(request)));
         const settings = readSignageSettings(context.config);
-        const rawError = body.error;
         // Telemetry only. Nothing a display reports here changes authoritative playback, and a
         // local cursor is never accepted as truth.
         const result = await recordViewerHeartbeat({
           at: new Date(),
-          heartbeat: {
+          heartbeat,
-            cachedAssetCount:
-              optionalInteger(body, "cachedAssetCount", {
-                maximum: 100_000,
-                minimum: 0,
-              }) ?? undefined,
-            offlineReady: optionalBoolean(body, "offlineReady") ?? undefined,
-            reportedContributionId:
-              optionalString(body, "reportedContributionId", { maxLength: 200 }) ?? null,
-            reportedPlaybackRevision:
-              optionalInteger(body, "reportedPlaybackRevision", {
-                maximum: Number.MAX_SAFE_INTEGER,
-                minimum: 0,
-              }) ?? null,
-            reportedProviderId:
-              optionalString(body, "reportedProviderId", { maxLength: 200 }) ?? null,
-            reportedSelectionId:
-              optionalString(body, "reportedSelectionId", { maxLength: 64 }) ?? null,
-            reportedTimelineId:
-              optionalString(body, "reportedTimelineId", { maxLength: 64 }) ?? null,
-            ...(rawError === undefined
-              ? {}
-              : {
-                  error:
-                    rawError === null
-                      ? null
-                      : {
-                          code: readErrorCode(rawError),
-                          detail: readErrorDetail(rawError),
-                        },
-                }),
-          },
           minimumWriteIntervalMs: settings.viewerHeartbeatWriteMs,
           store: store(context),
           viewerId,
         });
         // The response says what a display needs to keep itself honest, and nothing about other
         // displays or the installation.
-        return Response.json({ acknowledged: true, recorded: result.written });
+        const response: DisplayHeartbeatResponse = { acknowledged: true, recorded: result.written };
+        return Response.json(response);
       });
     },
   });
@@ -235,25 +215,3 @@ export function registerViewerRoutes(
     },
   });
 }
-
-function readErrorCode(value: unknown): string {
-  if (typeof value !== "object" || value === null) {
-    throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error" });
-  }
-  const code = (value as { code?: unknown }).code;
-  if (typeof code !== "string" || !OPAQUE_ID.test(code)) {
-    throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.code" });
-  }
-  return code;
-}
-
-function readErrorDetail(value: unknown): string | null {
-  const detail = (value as { detail?: unknown }).detail;
-  if (detail === undefined || detail === null) {
-    return null;
-  }
-  if (typeof detail !== "string") {
-    throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.detail" });
-  }
-  return detail;
-}

src/server/runtime.ts

@@ -3,6 +3,7 @@ import {
   type ModuleRuntimeContext,
   type ModuleRuntimeDefinition,
 } from "@ekklesia/module-sdk";
+import type { DisplayRealtimePayload } from "../shared/display-protocol.js";
 import { SIGNAGE_SLIDE_RENDERER_INPUT_VERSION } from "../shared/renderer-input.js";
 import {
   SIGNAGE_IMAGE_MAX_BYTES,
@@ -88,7 +89,7 @@ export function createSignageModuleRuntime(
 
   function requireStore(): ReturnType<typeof createSignageStore> {
     if (!store) {
-      throw new Error("Signage's database facade is only available after start.");
+      throw new Error("Signage's store is only available after start.");
     }
     return store;
   }
@@ -98,10 +99,10 @@ export function createSignageModuleRuntime(
       left.groupId.localeCompare(right.groupId),
     );
     try {
-      context.realtime.publish(SIGNAGE_DISPLAY_CHANNEL, {
+      // The shape the display reads (`src/shared/display-protocol.ts`): each group's whole snapshot
-        groups,
+      // carries the revisions it compares.
-        serverNowMs: now().getTime(),
+      const display: DisplayRealtimePayload = { groups, serverNowMs: now().getTime() };
-      });
+      context.realtime.publish(SIGNAGE_DISPLAY_CHANNEL, display);
       context.realtime.publish(SIGNAGE_MANAGEMENT_CHANNEL, {
         // Revisions only. The dashboard refetches what changed over authorized HTTP.
         groups: groups.map((snapshot) => ({
@@ -125,8 +126,11 @@ export function createSignageModuleRuntime(
   }
 
   const definition = defineModuleRuntime({
+    // Matches `database.abi` in the manifest: `context.services.database` is this module's Module
+    // Database ABI v1 executor, which `createSignageStore` binds Signage's own Drizzle adapter to.
+    database: { abi: 1 },
     id: "signage",
-    version: "0.1.1",
+    version: "0.1.2",
 
     register({ capabilities, config, http, realtime }) {
       const settings = readSignageSettings(config);
@@ -188,7 +192,7 @@ export function createSignageModuleRuntime(
           // server enforces — a UI believing a stale limit would offer an upload the server refuses.
           return Response.json({
             crossfadeMs: current.crossfadeMs,
-            moduleVersion: "0.1.1",
+            moduleVersion: "0.1.2",
             nativeImageDurationMs: current.nativeImageDurationMs,
             nativePresentation: current.nativePresentation,
             rendererInputVersion: SIGNAGE_SLIDE_RENDERER_INPUT_VERSION,

src/server/store/drizzle-playback.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import type { ModuleDatabase } from "@ekklesia/module-sdk";
+import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
 import { and, asc, desc, eq, inArray, lt, sql } from "drizzle-orm";
 import {
   channelGroups,
@@ -94,7 +94,7 @@ function toSelection(
   };
 }
 
-export function createPlaybackStore(database: ModuleDatabase): SignagePlaybackStore {
+export function createPlaybackStore(database: ModuleDrizzleDatabase): SignagePlaybackStore {
   async function variantsFor(
     selectionIds: readonly string[],
   ): Promise<Map<string, StoredSelectionVariant[]>> {

src/server/store/drizzle-timelines.ts

@@ -1,4 +1,7 @@
-import type { ModuleDatabase } from "@ekklesia/module-sdk";
+import type {
+  ModuleDrizzleDatabase,
+  ModuleDrizzleTransaction,
+} from "@ekklesia/module-database/drizzle";
 import { asc, eq, or, sql } from "drizzle-orm";
 import { playbackStates, providerSources, timelineSlots, timelines } from "../../schema/tables.js";
 import {
@@ -108,7 +111,7 @@ function slotValues(slot: NewStoredSlot, position: number) {
   };
 }
 
-export function createTimelineStore(database: ModuleDatabase): SignageTimelineStore {
+export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTimelineStore {
   /**
    * Rewrites `position` for one timeline from an explicit order.
    *
@@ -118,7 +121,7 @@ export function createTimelineStore(database: ModuleDatabase): SignageTimelineSt
    * remaining inside the database's non-negative constraint.
    */
   async function renumber(
-    transaction: ModuleDatabase,
+    transaction: ModuleDrizzleTransaction,
     timelineId: string,
     orderedSlotIds: readonly string[],
   ): Promise<void> {
@@ -138,7 +141,10 @@ export function createTimelineStore(database: ModuleDatabase): SignageTimelineSt
     await bumpRevision(transaction, timelineId);
   }
 
-  async function bumpRevision(transaction: ModuleDatabase, timelineId: string): Promise<void> {
+  async function bumpRevision(
+    transaction: ModuleDrizzleTransaction,
+    timelineId: string,
+  ): Promise<void> {
     await transaction
       .update(timelines)
       .set({ revision: sql`${timelines.revision} + 1`, updatedAt: new Date() })
@@ -146,7 +152,7 @@ export function createTimelineStore(database: ModuleDatabase): SignageTimelineSt
   }
 
   async function orderedSlotIdsFor(
-    transaction: ModuleDatabase,
+    transaction: ModuleDrizzleTransaction,
     timelineId: string,
   ): Promise<string[]> {
     const rows = await transaction
@@ -158,7 +164,7 @@ export function createTimelineStore(database: ModuleDatabase): SignageTimelineSt
   }
 
   async function timelineIdForSlot(
-    transaction: ModuleDatabase,
+    transaction: ModuleDrizzleTransaction,
     slotId: string,
   ): Promise<string | undefined> {
     const rows = await transaction

src/server/store/drizzle-viewers.ts

@@ -1,4 +1,4 @@
-import type { ModuleDatabase } from "@ekklesia/module-sdk";
+import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
 import { asc, eq } from "drizzle-orm";
 import { viewers } from "../../schema/tables.js";
 import type { NewStoredViewer, SignageViewerStore, StoredViewer, ViewerChanges } from "./types.js";
@@ -29,7 +29,7 @@ function toViewer(row: typeof viewers.$inferSelect): StoredViewer {
   };
 }
 
-export function createViewerStore(database: ModuleDatabase): SignageViewerStore {
+export function createViewerStore(database: ModuleDrizzleDatabase): SignageViewerStore {
   return {
     async deleteViewer(viewerId: string): Promise<void> {
       await database.delete(viewers).where(eq(viewers.id, viewerId));

src/server/store/drizzle.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import type { ModuleDatabase } from "@ekklesia/module-sdk";
+import { findEkklesiaDatabaseError, type ModuleDatabaseExecutor } from "@ekklesia/module-database";
+import { type ModuleDrizzleDatabase, moduleDrizzle } from "@ekklesia/module-database/drizzle";
 import { and, desc, eq, inArray } from "drizzle-orm";
 import {
   imageAssets,
@@ -22,14 +23,16 @@ import {
 } from "./types.js";
 
 /**
- * The production implementation of Signage's data port, over the platform's `ModuleDatabase`.
+ * The production implementation of Signage's data port, over the platform's Module Database ABI v1
+ * executor (platform ADR 0050) through the module-side Drizzle adapter.
  *
  * This file is deliberately dull: it maps rows and nothing else. Every decision — what to write,
  * when a revision changes, what a no-op is — lives in the services above it, so that behaviour can
  * be proven without PostgreSQL and this mapping can be proven against a live one.
  *
- * The facade is the only way Signage reaches PostgreSQL. Nothing here constructs a client, reads a
+ * The executor is the only way Signage reaches PostgreSQL. Drizzle compiles every query here, on
- * connection string, or touches another module's table.
+ * Signage's side; Core receives SQL text and bound values and nothing else. Nothing here constructs a
+ * client, reads a connection string, or touches another module's table.
  */
 
 const assetColumns = {
@@ -66,12 +69,11 @@ const renditionColumns = {
   width: imageRenditions.width,
 };
 
-/** PostgreSQL reports a uniqueness violation as SQLSTATE `23505`. The code is all that is read; the
+/** PostgreSQL reports a uniqueness violation as SQLSTATE `23505`. Drizzle wraps whatever the
- * driver's message, detail, and constraint text are never surfaced. */
+ * executor throws, so the stable Ekklesia database error is found through that wrapping; its SQLSTATE
+ * is all that is read, and no driver error shape is ever relied on. */
 function isUniqueViolation(error: unknown): boolean {
-  return (
+  return findEkklesiaDatabaseError(error)?.sqlState === "23505";
-    typeof error === "object" && error !== null && (error as { code?: unknown }).code === "23505"
-  );
 }
 
 function toRendition(row: {
@@ -116,7 +118,7 @@ function toImage(row: AssetRow, renditions: readonly StoredImageRendition[]): St
   };
 }
 
-export function createImageStore(database: ModuleDatabase): SignageImageStore {
+export function createImageStore(database: ModuleDrizzleDatabase): SignageImageStore {
   async function renditionsFor(
     assetIds: readonly string[],
   ): Promise<Map<string, StoredImageRendition[]>> {
@@ -258,8 +260,12 @@ export function createImageStore(database: ModuleDatabase): SignageImageStore {
  *
  * Composed rather than written as one object because the two halves share nothing but the database
  * handle, and keeping them separate is what lets each be read on its own.
+ *
+ * Takes the ABI executor the platform hands a route handler or lifecycle hook, and binds Signage's
+ * own Drizzle adapter to it here, once, so every caller reaches its tables the same way.
  */
-export function createSignageStore(database: ModuleDatabase): SignageStore {
+export function createSignageStore(executor: ModuleDatabaseExecutor): SignageStore {
+  const database = moduleDrizzle(executor);
   return {
     ...createImageStore(database),
     ...createTimelineStore(database),

src/server/store/types.ts

@@ -3,7 +3,7 @@
  *
  * Every piece of Signage's behaviour — ingest, timeline editing, provider resolution, authoritative
  * playback, viewer health — is written against this interface rather than against Drizzle directly.
- * There are two implementations: the production one over the platform's `ModuleDatabase`
+ * There are two implementations: the production one over the platform's database ABI executor
  * (`./drizzle.ts`), and an in-memory one used by tests.
  *
  * This is the same discipline Core's own migration runner follows, and it exists for the same

src/shared/display-protocol.ts

@@ -0,0 +1,318 @@
+/**
+ * What a display and Signage's server say to each other, defined once.
+ *
+ * The display controller builds these messages and the viewer routes read them, from this one file.
+ * They used to be described twice — once in the controller's own interfaces and once in each
+ * route's field-by-field parsing — and the two descriptions disagreed about one thing: the display
+ * sent `null` for "nothing to report" and the heartbeat route accepted only a *missing* field. Every
+ * heartbeat from a screen showing a native image was refused with a 400, silently, for as long as it
+ * ran. Nothing here can drift that way again, because there is nothing to drift between.
+ *
+ * Three rules hold for every message:
+ *
+ * - **A nullable field accepts `null` explicitly.** `null` means "I have nothing", and is a value.
+ * - **An absent field means "not reported".** A receiver keeps whatever it already had.
+ * - **An unknown field is ignored, never refused.** A newer display reporting something an older
+ *   server does not know yet must still be heard; refusing it would be this same bug in reverse.
+ *
+ * Like the rest of `src/shared`, it imports nothing from outside `src/shared`: it is compiled into the browser
+ * artifact as well as the server, and must pull neither the module SDK nor Node into a display.
+ */
+
+import type { SignageNativeScene } from "./native-images.js";
+
+// --- Parsing ---------------------------------------------------------------------------------------
+
+/** The outcome of reading one message: the value, or the one field that was wrong. Never a parser's
+ * own message, which is not something a client or an operator should see. */
+export type ProtocolResult<Value> =
+  | { readonly ok: true; readonly value: Value }
+  | { readonly ok: false; readonly field: string };
+
+type Reader<Value> = (raw: unknown) => { readonly ok: true; readonly value: Value } | undefined;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function text(options: { readonly maxLength: number; readonly pattern?: RegExp }): Reader<string> {
+  return (raw) => {
+    if (typeof raw !== "string") {
+      return undefined;
+    }
+    const value = raw.trim();
+    if (value.length === 0 || value.length > options.maxLength) {
+      return undefined;
+    }
+    if (options.pattern && !options.pattern.test(value)) {
+      return undefined;
+    }
+    return { ok: true, value };
+  };
+}
+
+function integer(options: { readonly minimum: number; readonly maximum: number }): Reader<number> {
+  return (raw) =>
+    typeof raw === "number" &&
+    Number.isSafeInteger(raw) &&
+    raw >= options.minimum &&
+    raw <= options.maximum
+      ? { ok: true, value: raw }
+      : undefined;
+}
+
+const flag: Reader<boolean> = (raw) =>
+  typeof raw === "boolean" ? { ok: true, value: raw } : undefined;
+
+function nullable<Value>(read: Reader<Value>): Reader<Value | null> {
+  return (raw) => (raw === null ? { ok: true, value: null } : read(raw));
+}
+
+/** Reads the named fields of a message. Absent fields are left out of the result; any other field
+ * of the object is ignored. */
+function readFields<Shape extends object>(
+  raw: unknown,
+  readers: { readonly [Key in keyof Shape]-?: Reader<Exclude<Shape[Key], undefined>> },
+): ProtocolResult<Shape> {
+  if (!isRecord(raw)) {
+    return { field: "body", ok: false };
+  }
+  const value: Record<string, unknown> = {};
+  for (const key of Object.keys(readers) as (keyof Shape & string)[]) {
+    if (raw[key] === undefined) {
+      continue;
+    }
+    const read = readers[key](raw[key]);
+    if (!read) {
+      return { field: key, ok: false };
+    }
+    value[key] = read.value;
+  }
+  return { ok: true, value: value as Shape };
+}
+
+function requireFields<Shape>(
+  result: ProtocolResult<Partial<Shape>>,
+  required: readonly (keyof Shape & string)[],
+): ProtocolResult<Shape> {
+  if (!result.ok) {
+    return result;
+  }
+  for (const key of required) {
+    if (result.value[key] === undefined) {
+      return { field: key, ok: false };
+    }
+  }
+  return result as ProtocolResult<Shape>;
+}
+
+// --- Limits ----------------------------------------------------------------------------------------
+
+/** A display's own identity, kept in its IndexedDB. */
+export const DISPLAY_VIEWER_KEY = /^[\w-]{8,128}$/u;
+/** The longest error detail a display may report. Operator-facing text a browser supplied, so it is
+ * bounded, and because an unbounded one is a way to fill a table. */
+export const DISPLAY_ERROR_DETAIL_MAX = 200;
+export const DISPLAY_ERROR_CODE = /^[\w][\w.:-]{0,63}$/u;
+export const DISPLAY_CACHED_ASSET_MAX = 100_000;
+
+// --- Viewer session: POST viewers/session ----------------------------------------------------------
+
+export interface ViewerSessionRequest {
+  readonly viewerKey: string;
+}
+
+export interface ViewerSessionResponse {
+  readonly viewerId: string;
+  readonly viewerName: string;
+  readonly channelId: string;
+  readonly channelKey: string;
+  readonly groupId: string;
+  readonly heartbeatIntervalMs: number;
+}
+
+const identifier = text({ maxLength: 200 });
+
+export function parseViewerSessionRequest(raw: unknown): ProtocolResult<ViewerSessionRequest> {
+  return requireFields<ViewerSessionRequest>(
+    readFields<Partial<ViewerSessionRequest>>(raw, {
+      viewerKey: text({ maxLength: 128, pattern: DISPLAY_VIEWER_KEY }),
+    }),
+    ["viewerKey"],
+  );
+}
+
+export function parseViewerSessionResponse(raw: unknown): ProtocolResult<ViewerSessionResponse> {
+  return requireFields<ViewerSessionResponse>(
+    readFields<Partial<ViewerSessionResponse>>(raw, {
+      channelId: identifier,
+      channelKey: identifier,
+      groupId: identifier,
+      heartbeatIntervalMs: integer({ maximum: 600_000, minimum: 1_000 }),
+      viewerId: identifier,
+      viewerName: text({ maxLength: 200 }),
+    }),
+    ["viewerId", "viewerName", "channelId", "channelKey", "groupId", "heartbeatIntervalMs"],
+  );
+}
+
+// --- Heartbeat: POST viewers/:viewerId/heartbeat ---------------------------------------------------
+
+export interface DisplayReportedError {
+  readonly code: string;
+  readonly detail: string | null;
+}
+
+/**
+ * What a display reports about itself. Telemetry, never authority: nothing here changes playback.
+ *
+ * Every field is optional on the wire (absent = not reported). The display sends all of them.
+ */
+export interface DisplayHeartbeat {
+  readonly cachedAssetCount?: number;
+  readonly offlineReady?: boolean;
+  readonly reportedTimelineId?: string | null;
+  readonly reportedSelectionId?: string | null;
+  readonly reportedProviderId?: string | null;
+  readonly reportedContributionId?: string | null;
+  readonly reportedPlaybackRevision?: number | null;
+  readonly error?: DisplayReportedError | null;
+}
+
+const reportedError: Reader<DisplayReportedError> = (raw) => {
+  const read = readFields<{ code?: string; detail?: string | null }>(raw, {
+    code: text({ maxLength: 64, pattern: DISPLAY_ERROR_CODE }),
+    detail: nullable(text({ maxLength: DISPLAY_ERROR_DETAIL_MAX })),
+  });
+  if (!read.ok || read.value.code === undefined) {
+    return undefined;
+  }
+  return { ok: true, value: { code: read.value.code, detail: read.value.detail ?? null } };
+};
+
+export function parseDisplayHeartbeat(raw: unknown): ProtocolResult<DisplayHeartbeat> {
+  return readFields<DisplayHeartbeat>(raw, {
+    cachedAssetCount: integer({ maximum: DISPLAY_CACHED_ASSET_MAX, minimum: 0 }),
+    error: nullable(reportedError),
+    offlineReady: flag,
+    reportedContributionId: nullable(text({ maxLength: 200 })),
+    reportedPlaybackRevision: nullable(integer({ maximum: Number.MAX_SAFE_INTEGER, minimum: 0 })),
+    reportedProviderId: nullable(text({ maxLength: 200 })),
+    reportedSelectionId: nullable(text({ maxLength: 64 })),
+    reportedTimelineId: nullable(text({ maxLength: 64 })),
+  });
+}
+
+export interface DisplayHeartbeatResponse {
+  readonly acknowledged: true;
+  readonly recorded: boolean;
+}
+
+// --- Channel state: GET channels/:channelId/display-state -----------------------------------------
+
+/** A fresh, signed delivery URL. A bearer capability with an expiry: never persisted by a display. */
+export interface DisplayMedia {
+  readonly url: string;
+  readonly expiresAtMs: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export type DisplayRenderer =
+  | { readonly kind: "native-image" }
+  | {
+      readonly kind: "contribution";
+      readonly contributionId: string;
+      readonly contributionVersion: string;
+    }
+  | { readonly kind: "unavailable" };
+
+export interface DisplaySelection {
+  readonly id: string;
+  readonly revision: number;
+  readonly slotId: string | null;
+  readonly providerId: string;
+  readonly itemId: string;
+  readonly itemRevision: string;
+  readonly startedAtMs: number | null;
+  readonly deadlineAtMs: number | null;
+  readonly durationMs: number;
+  readonly availableUntilMs: number | null;
+  readonly withdrawn: boolean;
+  readonly stale: boolean;
+  /** `native-image` is drawn by Signage's own display code; `contribution` is mounted through the
+   * platform's contribution ABI by id. A display never receives a URL for either. */
+  readonly renderer: DisplayRenderer;
+  /** The provider's own payload for this channel's audience, or its default. */
+  readonly payload: unknown;
+  readonly presentation: unknown;
+  /** Native images only: fresh delivery URLs, and the already-resolved scene. */
+  readonly media?: { readonly display: DisplayMedia; readonly thumbnail: DisplayMedia };
+  readonly scene?: SignageNativeScene;
+}
+
+export interface DisplayTimelineSlot {
+  readonly id: string;
+  readonly position: number;
+  readonly enabled: boolean;
+  readonly eligibleFromMs: number | null;
+  readonly eligibleUntilMs: number | null;
+  readonly estimatedDurationMs: number;
+}
+
+export interface DisplayTimeline {
+  readonly id: string;
+  readonly revision: number;
+  readonly eligibleFromMs: number | null;
+  readonly eligibleUntilMs: number | null;
+  readonly slots: readonly DisplayTimelineSlot[];
+}
+
+/** The part of the group's playback a display acts on. The server sends its whole snapshot; this is
+ * what a display may rely on being there. */
+export interface DisplayPlayback {
+  readonly revision: number;
+  readonly transport: string;
+  readonly blackout: boolean;
+  readonly remainingMs: number | null;
+  readonly selectionRevision: number | null;
+  readonly currentSelectionId: string | null;
+  readonly currentSlotId: string | null;
+  readonly activeTimelineId: string | null;
+  readonly pendingTimelineId: string | null;
+  readonly startedAtMs: number | null;
+  readonly deadlineAtMs: number | null;
+}
+
+export interface DisplayChannelState {
+  readonly serverNowMs: number;
+  readonly channel: {
+    readonly id: string;
+    readonly key: string;
+    readonly groupId: string;
+  };
+  readonly crossfadeMs: number;
+  readonly playback: DisplayPlayback;
+  readonly timeline: DisplayTimeline | null;
+  readonly current: DisplaySelection | null;
+  /** The held image, already resolved as a scene. Separate from `current` because a static hold sits
+   * *over* a preserved cursor rather than replacing it. */
+  readonly staticHold: DisplaySelection | null;
+  /** Bounded, newest first. Material for offline continuation, never a substitute for authority. */
+  readonly selections: readonly DisplaySelection[];
+}
+
+// --- Realtime: the display-state channel ----------------------------------------------------------
+
+/** One group's revisions on the realtime channel. Compact on purpose: a revision this display has
+ * not applied means "fetch the state you are authorized for", never content. */
+export interface DisplayRealtimeGroup {
+  readonly groupId: string;
+  readonly revision: number;
+  readonly selectionRevision: number | null;
+}
+
+export interface DisplayRealtimePayload {
+  readonly groups: readonly DisplayRealtimeGroup[];
+  readonly serverNowMs: number;
+}

src/ui/index.tsx

@@ -15,7 +15,7 @@ import ownStyles from "./styles.css";
  */
 export default defineModuleUi({
 	id: "signage",
-	version: "0.1.1",
+	version: "0.1.2",
 	styles: `${EKKLESIA_UI_STYLESHEET}\n${ownStyles}`,
 	mount(container, context) {
 		const root = createRoot(container);

tests/acceptance.test.ts

@@ -263,7 +263,9 @@ describe("what this release deliberately does not contain", () => {
     ]) {
       expect(names).not.toContain(forbidden);
     }
-    // The database is reached only through the platform's facade; there is no client of Signage's own.
+    // The database is reached only through the platform's ABI executor, with Signage's own Drizzle
+    // adapter compiling the queries; there is no client of Signage's own.
     expect(names).toContain("drizzle-orm");
+    expect(names).toContain("@ekklesia/module-database");
   });
 });

tests/browser/backoff.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import {
+  DISPLAY_RETRY_BASE_MS,
+  DISPLAY_RETRY_MAX_MS,
+  displayRetryDelayMs,
+} from "../../src/browser/backoff.js";
+
+describe("display retry backoff", () => {
+  it("doubles from one second and stops at one minute", () => {
+    const longest = (attempt: number) => displayRetryDelayMs(attempt, () => 1);
+    expect([0, 1, 2, 3, 4, 5, 6, 7, 50].map(longest)).toEqual([
+      1_000, 2_000, 4_000, 8_000, 16_000, 32_000, 60_000, 60_000, 60_000,
+    ]);
+  });
+
+  it("jitters between half and all of each step, and never waits zero", () => {
+    for (const attempt of [0, 3, 6, 40]) {
+      const step = Math.min(DISPLAY_RETRY_MAX_MS, DISPLAY_RETRY_BASE_MS * 2 ** attempt);
+      expect(displayRetryDelayMs(attempt, () => 0)).toBe(step / 2);
+      expect(displayRetryDelayMs(attempt, () => 1)).toBe(step);
+      for (let index = 0; index < 50; index += 1) {
+        const delay = displayRetryDelayMs(attempt);
+        expect(delay).toBeGreaterThanOrEqual(step / 2);
+        expect(delay).toBeLessThanOrEqual(step);
+      }
+    }
+  });
+
+  it("treats a nonsensical attempt or random value as the nearest sensible one", () => {
+    expect(displayRetryDelayMs(-3, () => 1)).toBe(1_000);
+    expect(displayRetryDelayMs(2, () => 7)).toBe(4_000);
+    expect(displayRetryDelayMs(2, () => -1)).toBe(2_000);
+  });
+});

tests/browser/contributed-renderer.test.tsx

@@ -43,6 +43,7 @@ const SELECTION = {
   },
   revision: 1,
   slotId: "slot-trivia",
+  stale: false,
   startedAtMs: 0,
   withdrawn: false,
 };

tests/browser/display-contract.test.ts

@@ -0,0 +1,223 @@
+// @vitest-environment happy-dom
+import type { ModuleRouteDefinitionInput, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
+import { beforeEach, describe, expect, it } from "vitest";
+import { createMemoryMediaCache, createMemoryStore } from "../../src/browser/storage.js";
+import { createDisplayController } from "../../src/display/controller.js";
+import { ingestNativeImage } from "../../src/server/images/service.js";
+import {
+  createPlaybackService,
+  type SignagePlaybackService,
+} from "../../src/server/playback/service.js";
+import { createNativeImageProvider } from "../../src/server/providers/native-provider.js";
+import {
+  createProviderRegistry,
+  type SignageProviderRegistry,
+} from "../../src/server/providers/registry.js";
+import { registerViewerRoutes } from "../../src/server/routes/viewers.js";
+import { addSlot, createTimeline } from "../../src/server/timelines/service.js";
+import { SIGNAGE_NATIVE_PROVIDER_ID } from "../../src/shared/native-images.js";
+import { SIGNAGE_DEFAULT_SETTINGS } from "../../src/shared/settings.js";
+import { createFakeStorage, type FakeStorage } from "../support/fake-storage.js";
+import { makeImage } from "../support/images.js";
+import { createMemorySignageStore, type MemorySignageStore } from "../support/memory-store.js";
+import { fakeConfiguration, fakeHandlerContext } from "../support/module-harness.js";
+import { createFakeHost, type FakeHost } from "./support/fake-host.js";
+
+/**
+ * The display and the server, speaking to each other for real.
+ *
+ * Every other display test answers the controller with a hand-written stub, and every server test
+ * calls the service with a hand-written object. Each side was therefore only ever tested against its
+ * own idea of the other, and in production every heartbeat a display sent was refused with a 400:
+ * the display sent `null` for an absent value and the route accepted only a missing field.
+ *
+ * Here the **real** display controller's requests are answered by the **real** viewer routes, over
+ * Signage's in-memory store. A request one side builds and the other refuses fails this suite.
+ */
+
+const START = Date.parse("2026-10-05T15:00:00.000Z");
+const DEVICE_ID = "6f1c2d3e-4b5a-4c6d-8e7f-901a2b3c4d5e";
+
+interface RouteCall {
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+  readonly code: string | undefined;
+}
+
+/** Matches a relative module path against the routes the module registered, and runs the handler
+ * exactly as the platform would: one Request, one handler context. */
+function routeTable(routes: readonly ModuleRouteDefinitionInput[]) {
+  return routes.map((route) => {
+    const names: string[] = [];
+    const pattern = new RegExp(
+      `^${route.path.replace(/:(\w+)/gu, (_match, name: string) => {
+        names.push(name);
+        return "([^/]+)";
+      })}$`,
+      "u",
+    );
+    return { names, pattern, route };
+  });
+}
+
+describe("display ↔ server contract", () => {
+  let clock: number;
+  let counter: number;
+  let store: MemorySignageStore;
+  let storage: FakeStorage;
+  let registry: SignageProviderRegistry;
+  let playback: SignagePlaybackService;
+  let calls: RouteCall[];
+  let host: FakeHost;
+  let root: HTMLElement;
+
+  const newId = () => {
+    counter += 1;
+    return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
+  };
+
+  beforeEach(async () => {
+    clock = START;
+    counter = 0;
+    calls = [];
+    store = createMemorySignageStore({ now: () => new Date(clock) });
+    storage = createFakeStorage({ now: () => new Date(clock) });
+    registry = createProviderRegistry({ now: () => new Date(clock), timeoutMs: 1000 });
+    registry.capability.register(
+      createNativeImageProvider({ defaultDurationMs: 7000, now: () => new Date(clock), store })
+        .registration,
+    );
+    playback = createPlaybackService({
+      newId,
+      now: () => clock,
+      registry,
+      setTimer: () => undefined,
+      settings: SIGNAGE_DEFAULT_SETTINGS,
+      store,
+    });
+    await playback.ensureDefaultGroup();
+
+    // One native image on a pinned slot: the most ordinary thing a wall shows, and exactly the case
+    // whose heartbeat carries no contribution id.
+    const image = await ingestNativeImage({
+      bytes: await makeImage({ format: "png", height: 1080, width: 1920 }),
+      displayName: "Welcome",
+      expiresAt: null,
+      filename: "welcome.png",
+      storage,
+      store,
+    });
+    const timeline = await createTimeline({ name: "Lobby", newId, store });
+    await addSlot({
+      newId,
+      pinned: { itemId: image.image.id, providerId: SIGNAGE_NATIVE_PROVIDER_ID },
+      store,
+      timelineId: timeline.timeline.id,
+    });
+    const groups = await store.listChannelGroups();
+    await playback.activate(groups[0]?.group.id as string, timeline.timeline.id, "now");
+
+    const registered: ModuleRouteDefinitionInput[] = [];
+    registerViewerRoutes(
+      { route: (definition) => registered.push(definition) },
+      () => playback,
+      () => registry,
+      () => store,
+    );
+    const table = routeTable(registered);
+
+    host = createFakeHost({
+      permissions: ["signage.display.view"],
+      principal: { deviceId: DEVICE_ID, kind: "device" } as never,
+      routes: [],
+    });
+    Object.assign(host.context.api, {
+      async request(path: string, init?: RequestInit): Promise<Response> {
+        const method = (init?.method ?? "GET").toUpperCase();
+        const relative = `/${path.replace(/^\//u, "").split("?")[0]}`;
+        for (const { names, pattern, route } of table) {
+          const match = pattern.exec(relative);
+          if (route.method !== method || !match) {
+            continue;
+          }
+          const params = Object.fromEntries(names.map((name, index) => [name, match[index + 1]]));
+          const context: ModuleRouteHandlerContext = fakeHandlerContext({
+            config: fakeConfiguration({}),
+            params: Object.freeze(params) as never,
+            principal: { deviceId: DEVICE_ID, kind: "device" } as never,
+            storage,
+          });
+          const request = new Request(
+            `https://api.example.test/api/v1/modules/signage${relative}`,
+            {
+              ...(init?.body === undefined ? {} : { body: init.body }),
+              headers: init?.headers ?? {},
+              method,
+            },
+          );
+          const response = await route.handler(request, context);
+          const body = (await response
+            .clone()
+            .json()
+            .catch(() => null)) as { code?: string } | null;
+          calls.push({ code: body?.code, method, path: route.path, status: response.status });
+          return response;
+        }
+        throw new Error(
+          `The display asked for ${method} ${relative}, which Signage does not serve.`,
+        );
+      },
+    });
+
+    root = document.createElement("div");
+    document.body.append(root);
+  });
+
+  async function settle(): Promise<void> {
+    for (let index = 0; index < 20; index += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  function controller() {
+    return createDisplayController({
+      context: host.context,
+      decodeImage: () => Promise.resolve(),
+      media: createMemoryMediaCache(),
+      newViewerKey: () => "kiosk-contract-0001",
+      now: () => clock,
+      root,
+      store: createMemoryStore(),
+    });
+  }
+
+  it("the server accepts every request the display sends", async () => {
+    const display = controller();
+    await display.start();
+    await settle();
+    await display.stop();
+
+    const sent = calls.map((call) => `${call.method} ${call.path}`);
+    expect(sent).toContain("POST /viewers/session");
+    expect(sent).toContain("GET /channels/:channelId/display-state");
+    expect(sent).toContain("POST /viewers/:viewerId/heartbeat");
+    // Not one refusal, of any kind, for anything the display built itself.
+    expect(calls.filter((call) => call.status >= 400)).toEqual([]);
+  });
+
+  it("a heartbeat from a screen showing a native image is recorded", async () => {
+    const display = controller();
+    await display.start();
+    await settle();
+    await display.stop();
+
+    const [viewer] = await store.listViewers();
+    expect(viewer).toBeDefined();
+    // What the display reported is what the roster now holds — which is only true if the server
+    // took the heartbeat, rather than refusing it and leaving the session's values in place.
+    expect(viewer?.reportedSelectionId).not.toBeNull();
+    expect(viewer?.reportedProviderId).toBe(SIGNAGE_NATIVE_PROVIDER_ID);
+    expect(viewer?.reportedContributionId).toBeNull();
+  });
+});

tests/browser/display-recovery.test.ts

@@ -0,0 +1,307 @@
+// @vitest-environment happy-dom
+import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  createMemoryMediaCache,
+  createMemoryStore,
+  type SignageLocalStore,
+} from "../../src/browser/storage.js";
+import {
+  createDisplayController,
+  type DisplayChannelStateView,
+} from "../../src/display/controller.js";
+import { createFakeHost, type FakeHost, jsonResponse } from "./support/fake-host.js";
+
+/**
+ * A display never reaches a dead end.
+ *
+ * Every network path a display depends on — registering, fetching state, realtime — can fail once,
+ * as a kiosk that boots before its network settles or an API that restarts will make it. Each must
+ * be tried again, with backoff, until it works, and the display must then be exactly as live as if
+ * nothing had happened. None of it may need a person to reload a television.
+ *
+ * Time is virtual: every timer the controller schedules goes through the queue below.
+ */
+
+const SESSION = {
+  channelId: "chan-1",
+  channelKey: "default",
+  groupId: "group-1",
+  heartbeatIntervalMs: 12_000,
+  viewerId: "11111111-1111-4111-8111-111111111111",
+  viewerName: "Foyer",
+};
+
+function selection(id: string) {
+  return {
+    availableUntilMs: null,
+    deadlineAtMs: 5000,
+    durationMs: 5000,
+    id,
+    itemId: `image-${id}`,
+    itemRevision: "rev-1",
+    media: {
+      display: {
+        expiresAtMs: 900_000,
+        height: 1080,
+        url: `https://cdn.invalid/${id}`,
+        width: 1920,
+      },
+      thumbnail: {
+        expiresAtMs: 900_000,
+        height: 270,
+        url: `https://cdn.invalid/${id}-t`,
+        width: 480,
+      },
+    },
+    payload: { kind: "native-image" },
+    presentation: null,
+    providerId: "signage.native-images",
+    renderer: { kind: "native-image" as const },
+    revision: 1,
+    scene: {
+      backgroundColor: "#000000",
+      backgroundImage: false,
+      backgroundMode: "none" as const,
+      blurPixels: 0,
+      darkenOpacity: 0,
+      fit: "fill" as const,
+      shadow: false,
+    },
+    slotId: "slot-1",
+    stale: false,
+    startedAtMs: 0,
+    withdrawn: false,
+  };
+}
+
+function channelState(revision = 3): DisplayChannelStateView {
+  const current = selection("sel-1");
+  return {
+    channel: { groupId: "group-1", id: "chan-1", key: "default" },
+    crossfadeMs: 0,
+    current,
+    playback: {
+      activeTimelineId: "timeline-1",
+      blackout: false,
+      currentSelectionId: current.id,
+      currentSlotId: current.slotId,
+      deadlineAtMs: 5000,
+      pendingTimelineId: null,
+      remainingMs: 5000,
+      revision,
+      selectionRevision: 1,
+      startedAtMs: 0,
+      transport: "playing",
+    },
+    selections: [current],
+    serverNowMs: 0,
+    staticHold: null,
+    timeline: null,
+  };
+}
+
+/** Server behaviour that a test can change mid-run. */
+interface Server {
+  sessionFailures: number;
+  stateFailing: boolean;
+  sessionRequests: number;
+  stateRequests: number;
+}
+
+describe("a display recovers from every failed request without a reload", () => {
+  let clock: number;
+  let timers: Map<number, { at: number; run: () => void }>;
+  let nextTimer: number;
+  let root: HTMLElement;
+  let local: SignageLocalStore;
+  let server: Server;
+  let host: FakeHost;
+  let subscriptions: { onStatus?: (status: string) => void }[];
+
+  beforeEach(() => {
+    clock = 0;
+    timers = new Map();
+    nextTimer = 1;
+    root = document.createElement("div");
+    document.body.append(root);
+    local = createMemoryStore();
+    server = { sessionFailures: 0, sessionRequests: 0, stateFailing: false, stateRequests: 0 };
+    subscriptions = [];
+    host = createFakeHost({
+      permissions: ["signage.display.view"],
+      routes: [
+        {
+          method: "POST",
+          path: "viewers/session",
+          respond: () => {
+            server.sessionRequests += 1;
+            if (server.sessionFailures > 0) {
+              server.sessionFailures -= 1;
+              throw new TypeError("Failed to fetch");
+            }
+            return jsonResponse(SESSION);
+          },
+        },
+        {
+          method: "GET",
+          path: "channels/chan-1/display-state",
+          respond: () => {
+            server.stateRequests += 1;
+            if (server.stateFailing) {
+              throw new TypeError("Failed to fetch");
+            }
+            return jsonResponse(channelState());
+          },
+        },
+        { method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
+      ],
+    });
+    Object.assign(host.context, {
+      realtime: {
+        subscribe: (_channel: string, handlers: { onStatus?: (status: string) => void }) => {
+          subscriptions.push(handlers);
+          return { close: () => undefined };
+        },
+      } satisfies Pick<ModuleUiHostContext["realtime"], "subscribe"> as never,
+    });
+  });
+
+  async function settle(): Promise<void> {
+    for (let index = 0; index < 20; index += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  /** Moves virtual time forward, firing every timer that falls due, in order. */
+  async function advance(ms: number): Promise<void> {
+    const end = clock + ms;
+    for (;;) {
+      const due = [...timers]
+        .filter(([, timer]) => timer.at <= end)
+        .sort((left, right) => left[1].at - right[1].at)[0];
+      if (!due) {
+        break;
+      }
+      timers.delete(due[0]);
+      clock = due[1].at;
+      due[1].run();
+      await settle();
+    }
+    clock = end;
+  }
+
+  function build() {
+    return createDisplayController({
+      clearTimer: (handle) => timers.delete(handle as number),
+      context: host.context,
+      decodeImage: () => Promise.resolve(),
+      media: createMemoryMediaCache(),
+      newViewerKey: () => "viewer-fixed-key-0001",
+      now: () => clock,
+      root,
+      setTimer: (run, delayMs) => {
+        const id = nextTimer;
+        nextTimer += 1;
+        timers.set(id, { at: clock + delayMs, run });
+        return id;
+      },
+      store: local,
+    });
+  }
+
+  /** One ordinary live run, so the display has a persisted snapshot to continue from, exactly as a
+   * screen that has been on the wall for a while does. */
+  async function runOnceLive(): Promise<void> {
+    const display = build();
+    await display.start();
+    await settle();
+    expect(root.dataset.offline).toBe("false");
+    await display.stop();
+    timers.clear();
+  }
+
+  it("registers once the server answers, after its first registration failed", async () => {
+    await runOnceLive();
+    server.sessionFailures = 1;
+    const sessionsBefore = server.sessionRequests;
+
+    const display = build();
+    await display.start();
+    await settle();
+    // Continuing from its own state while it cannot register: the honest banner.
+    expect(root.dataset.offline).toBe("true");
+
+    await advance(60_000);
+
+    expect(server.sessionRequests - sessionsBefore).toBeGreaterThanOrEqual(2);
+    expect(root.dataset.offline).toBe("false");
+    expect(subscriptions.length).toBeGreaterThanOrEqual(2);
+    await display.stop();
+  });
+
+  it("keeps retrying registration with backoff, and never gives up", async () => {
+    await runOnceLive();
+    server.sessionFailures = 8;
+    const sessionsBefore = server.sessionRequests;
+
+    const display = build();
+    await display.start();
+    await settle();
+    // Eight failures back off for at most 1 + 2 + 4 + 8 + 16 + 32 + 60 + 60 seconds, the last two at
+    // the one-minute ceiling. Five virtual minutes is enough for all of them and the success after.
+    await advance(5 * 60_000);
+
+    expect(server.sessionRequests - sessionsBefore).toBe(9);
+    expect(root.dataset.offline).toBe("false");
+    await display.stop();
+  });
+
+  it("retries a failed state refresh until the server answers, with no realtime nudge", async () => {
+    const display = build();
+    await display.start();
+    await settle();
+    expect(root.dataset.offline).toBe("false");
+
+    // The slot's deadline refresh fails, as it would mid-restart. Realtime says nothing.
+    server.stateFailing = true;
+    await advance(6_000);
+    expect(root.dataset.offline).toBe("true");
+    const failedRequests = server.stateRequests;
+
+    server.stateFailing = false;
+    await advance(120_000);
+
+    expect(server.stateRequests).toBeGreaterThan(failedRequests);
+    expect(root.dataset.offline).toBe("false");
+    await display.stop();
+  });
+
+  it("subscribes again when the host reports its realtime stream closed for good", async () => {
+    const display = build();
+    await display.start();
+    await settle();
+    expect(subscriptions).toHaveLength(1);
+
+    subscriptions[0]?.onStatus?.("closed");
+    await settle();
+    await advance(60_000);
+
+    expect(subscriptions.length).toBeGreaterThanOrEqual(2);
+    await display.stop();
+  });
+
+  it("schedules nothing after it is stopped", async () => {
+    await runOnceLive();
+    server.sessionFailures = 3;
+    const display = build();
+    await display.start();
+    await settle();
+    await display.stop();
+    const sessionsAtStop = server.sessionRequests;
+
+    await advance(5 * 60_000);
+
+    expect(server.sessionRequests).toBe(sessionsAtStop);
+  });
+});

tests/browser/display.test.ts

@@ -6,6 +6,7 @@ import {
   type DisplayChannelStateView,
   type DisplayController,
 } from "../../src/display/controller.js";
+import type { ViewerSessionResponse } from "../../src/shared/display-protocol.js";
 import { createFakeHost, jsonResponse } from "./support/fake-host.js";
 
 /**
@@ -114,12 +115,14 @@ function state(overrides: Partial<DisplayChannelStateView> = {}): DisplayChannel
   };
 }
 
-const SESSION = {
+/** Typed as the shared protocol message, so a stub cannot drift from what the server sends. */
+const SESSION: ViewerSessionResponse = {
   channelId: "chan-1",
   channelKey: "default",
   groupId: "group-1",
   heartbeatIntervalMs: 12_000,
   viewerId: "11111111-1111-4111-8111-111111111111",
+  viewerName: "Foyer",
 };
 
 describe("display controller", () => {

tests/browser/media-cache.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createBrowserMediaCache, type SignageMediaCache } from "../../src/browser/storage.js";
+
+/**
+ * The Cache Storage media cache hands out object URLs, and every live one pins its blob in the
+ * browser until it is revoked.
+ *
+ * Every state refresh looks up every cached slide, so a cache that minted a fresh URL per lookup
+ * leaked one blob per slide per refresh. In a real browser that exhausted blob storage within
+ * minutes: the display's own state requests then failed with `net::ERR_INSUFFICIENT_RESOURCES` and
+ * it fell back to its offline banner on a perfectly good network.
+ */
+
+/** Just enough Cache Storage: one named cache, keyed by request URL. */
+function fakeCacheStorage() {
+  const entries = new Map<string, { body: ArrayBuffer; type: string }>();
+  const cache = {
+    async delete(request: Request | string): Promise<boolean> {
+      return entries.delete(typeof request === "string" ? request : request.url);
+    },
+    async keys(): Promise<Request[]> {
+      return [...entries.keys()].map((url) => new Request(url));
+    },
+    async match(request: Request | string): Promise<Response | undefined> {
+      const entry = entries.get(typeof request === "string" ? request : request.url);
+      return entry
+        ? new Response(entry.body, { headers: { "content-type": entry.type } })
+        : undefined;
+    },
+    async put(request: Request | string, response: Response): Promise<void> {
+      entries.set(typeof request === "string" ? request : request.url, {
+        body: await response.arrayBuffer(),
+        type: response.headers.get("content-type") ?? "application/octet-stream",
+      });
+    },
+  };
+  return { open: async () => cache } as unknown as CacheStorage;
+}
+
+describe("Signage's media cache and object URLs", () => {
+  const realCreate = URL.createObjectURL;
+  const realRevoke = URL.revokeObjectURL;
+  let live: Set<string>;
+  let media: SignageMediaCache;
+
+  beforeEach(() => {
+    live = new Set();
+    let next = 0;
+    URL.createObjectURL = () => {
+      next += 1;
+      const url = `blob:test/${next}`;
+      live.add(url);
+      return url;
+    };
+    URL.revokeObjectURL = (url: string) => {
+      live.delete(url);
+    };
+    media = createBrowserMediaCache({
+      caches: fakeCacheStorage(),
+      fetch: async () =>
+        new Response(new Uint8Array([1, 2, 3]), { headers: { "content-type": "image/webp" } }),
+      location: { origin: "https://api.example.test" },
+    } as unknown as typeof globalThis);
+  });
+
+  afterEach(() => {
+    URL.createObjectURL = realCreate;
+    URL.revokeObjectURL = realRevoke;
+  });
+
+  const keys = ["slide/a", "slide/b", "slide/c"];
+
+  it("keeps one live object URL per cached slide, however often it is looked up", async () => {
+    for (const key of keys) {
+      await media.store(key, `https://files.example.test/${key}?sig=1`);
+    }
+    // A state refresh looks every slide up again; a long-running display does this for months.
+    for (let refresh = 0; refresh < 100; refresh += 1) {
+      for (const key of keys) {
+        await media.find(key);
+      }
+    }
+    expect(live.size).toBe(keys.length);
+  });
+
+  it("hands out the same URL for the same bytes", async () => {
+    await media.store("slide/a", "https://files.example.test/a?sig=1");
+    const first = await media.find("slide/a");
+    const second = await media.find("slide/a");
+    expect(first).toBeDefined();
+    expect(second).toBe(first);
+  });
+
+  it("revokes a pruned slide's URL", async () => {
+    for (const key of keys) {
+      await media.store(key, `https://files.example.test/${key}?sig=1`);
+      await media.find(key);
+    }
+    await media.prune(["slide/a"]);
+    expect(live.size).toBe(1);
+    expect(await media.find("slide/b")).toBeUndefined();
+  });
+
+  it("revokes the URL it replaces when a slide is stored again", async () => {
+    await media.store("slide/a", "https://files.example.test/a?sig=1");
+    await media.store("slide/a", "https://files.example.test/a?sig=2");
+    await media.find("slide/a");
+    expect(live.size).toBe(1);
+  });
+
+  it("releases every URL it handed out when the display stops", async () => {
+    for (const key of keys) {
+      await media.store(key, `https://files.example.test/${key}?sig=1`);
+      await media.find(key);
+    }
+    media.release();
+    expect(live.size).toBe(0);
+  });
+});

tests/browser/offline.test.ts

@@ -16,6 +16,7 @@ import {
   createDisplayController,
   type DisplayChannelStateView,
 } from "../../src/display/controller.js";
+import type { DisplaySelection, ViewerSessionResponse } from "../../src/shared/display-protocol.js";
 import { createFakeHost, jsonResponse } from "./support/fake-host.js";
 
 /**
@@ -309,14 +310,26 @@ describe("a display that loses its network", () => {
     }
   }
 
-  function nativeSelection(id: string, slotId: string): SceneSelection {
+  /** A native selection exactly as the server sends one in channel state. */
+  function nativeSelection(id: string, slotId: string): DisplaySelection {
     return {
       ...selection({ id, slotId }),
       media: {
-        display: { url: `https://cdn.invalid/${id}?sig=a` },
+        display: {
-        thumbnail: { url: `https://cdn.invalid/${id}-t?sig=a` },
+          expiresAtMs: 900_000,
+          height: 1080,
+          url: `https://cdn.invalid/${id}?sig=a`,
+          width: 1920,
+        },
+        thumbnail: {
+          expiresAtMs: 900_000,
+          height: 270,
+          url: `https://cdn.invalid/${id}-t?sig=a`,
+          width: 480,
+        },
       },
-    } as SceneSelection;
+      stale: false,
+    };
   }
 
   function state(currentId: string): DisplayChannelStateView {
@@ -373,7 +386,8 @@ describe("a display that loses its network", () => {
               groupId: "group-1",
               heartbeatIntervalMs: 12_000,
               viewerId: "11111111-1111-4111-8111-111111111111",
-            }),
+              viewerName: "Foyer",
+            } satisfies ViewerSessionResponse),
         },
         {
           method: "GET",

tests/browser/support/fake-host.ts

@@ -127,7 +127,7 @@ export function createFakeHost(options: FakeHostOptions): FakeHost {
 /** The settings payload every screen loads first. */
 export const FAKE_SETTINGS = Object.freeze({
 	crossfadeMs: 1000,
-	moduleVersion: "0.1.1",
+	moduleVersion: "0.1.2",
 	nativeImageDurationMs: 7000,
 	nativePresentation: {
 		backgroundColor: "#000000",

tests/display-protocol.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import {
+  DISPLAY_ERROR_DETAIL_MAX,
+  parseDisplayHeartbeat,
+  parseViewerSessionRequest,
+  parseViewerSessionResponse,
+} from "../src/shared/display-protocol.js";
+
+/**
+ * The rules every display message follows, pinned one by one, because the production failure was
+ * exactly a disagreement about one of them.
+ */
+
+const FULL_HEARTBEAT = {
+  cachedAssetCount: 3,
+  error: null,
+  offlineReady: true,
+  reportedContributionId: null,
+  reportedPlaybackRevision: 4,
+  reportedProviderId: "signage.native-images",
+  reportedSelectionId: "sel-1",
+  reportedTimelineId: "timeline-1",
+};
+
+describe("display heartbeat", () => {
+  it("accepts null for every nullable field: null is a value, not an omission", () => {
+    const result = parseDisplayHeartbeat({
+      ...FULL_HEARTBEAT,
+      reportedContributionId: null,
+      reportedPlaybackRevision: null,
+      reportedProviderId: null,
+      reportedSelectionId: null,
+      reportedTimelineId: null,
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        ...FULL_HEARTBEAT,
+        reportedContributionId: null,
+        reportedPlaybackRevision: null,
+        reportedProviderId: null,
+        reportedSelectionId: null,
+        reportedTimelineId: null,
+      },
+    });
+  });
+
+  it("treats an absent field as not reported, so the receiver keeps what it had", () => {
+    const result = parseDisplayHeartbeat({ offlineReady: false });
+    expect(result).toEqual({ ok: true, value: { offlineReady: false } });
+  });
+
+  it("ignores a field it does not know, so a newer display is never refused by an older server", () => {
+    const result = parseDisplayHeartbeat({ ...FULL_HEARTBEAT, reportedSomethingNew: { a: 1 } });
+    expect(result).toEqual({ ok: true, value: FULL_HEARTBEAT });
+  });
+
+  it.each([
+    ["cachedAssetCount", null],
+    ["cachedAssetCount", -1],
+    ["cachedAssetCount", 1.5],
+    ["offlineReady", null],
+    ["offlineReady", "yes"],
+    ["reportedSelectionId", ""],
+    ["reportedSelectionId", "x".repeat(65)],
+    ["reportedProviderId", 7],
+    ["reportedPlaybackRevision", -1],
+    ["error", { code: "" }],
+    ["error", { code: "BAD CODE" }],
+    ["error", { code: "OK", detail: "y".repeat(DISPLAY_ERROR_DETAIL_MAX + 1) }],
+    ["error", "SLIDE_UNRENDERABLE"],
+  ])("refuses %s = %j, naming that field and nothing else", (field, value) => {
+    expect(parseDisplayHeartbeat({ ...FULL_HEARTBEAT, [field]: value })).toEqual({
+      field,
+      ok: false,
+    });
+  });
+
+  it("accepts a reported error with or without detail", () => {
+    expect(parseDisplayHeartbeat({ error: { code: "SLIDE_UNRENDERABLE", detail: null } })).toEqual({
+      ok: true,
+      value: { error: { code: "SLIDE_UNRENDERABLE", detail: null } },
+    });
+    expect(parseDisplayHeartbeat({ error: { code: "SLIDE_UNRENDERABLE" } })).toEqual({
+      ok: true,
+      value: { error: { code: "SLIDE_UNRENDERABLE", detail: null } },
+    });
+  });
+
+  it("refuses something that is not an object at all", () => {
+    for (const body of [null, [], "heartbeat", 3]) {
+      expect(parseDisplayHeartbeat(body)).toEqual({ field: "body", ok: false });
+    }
+  });
+});
+
+describe("viewer session", () => {
+  it("requires a well-formed viewer key", () => {
+    expect(parseViewerSessionRequest({ viewerKey: "kiosk-lobby-0001" })).toEqual({
+      ok: true,
+      value: { viewerKey: "kiosk-lobby-0001" },
+    });
+    for (const viewerKey of [undefined, null, "short", "has spaces in it", "x".repeat(129)]) {
+      expect(parseViewerSessionRequest({ viewerKey })).toEqual({ field: "viewerKey", ok: false });
+    }
+  });
+
+  it("a display accepts only a complete registration", () => {
+    const complete = {
+      channelId: "chan-1",
+      channelKey: "default",
+      groupId: "group-1",
+      heartbeatIntervalMs: 12_000,
+      viewerId: "11111111-1111-4111-8111-111111111111",
+      viewerName: "New display",
+    };
+    expect(parseViewerSessionResponse(complete)).toEqual({ ok: true, value: complete });
+    const { viewerId: _omitted, ...missing } = complete;
+    expect(parseViewerSessionResponse(missing)).toEqual({ field: "viewerId", ok: false });
+    expect(parseViewerSessionResponse({ ...complete, heartbeatIntervalMs: 0 })).toEqual({
+      field: "heartbeatIntervalMs",
+      ok: false,
+    });
+  });
+});

tests/drizzle-store.test.ts

@@ -0,0 +1,635 @@
+import { isModuleDatabaseError, ModuleDatabaseError } from "@ekklesia/module-database";
+import { moduleDrizzle } from "@ekklesia/module-database/drizzle";
+import { describe, expect, it } from "vitest";
+import { imageAssets } from "../src/schema/tables.js";
+import { createSignageStore } from "../src/server/store/drizzle.js";
+import {
+  type NewStoredImage,
+  type NewStoredSelection,
+  type NewStoredSlot,
+  type SignageStore,
+  SignageStoreConflict,
+} from "../src/server/store/types.js";
+import { type AbiResponder, createFakeAbiExecutor } from "./support/abi-executor.js";
+
+/**
+ * Signage's production store over the platform's Module Database ABI v1 (platform ADR 0050).
+ *
+ * The executor double holds the store to the ABI's own rules (`./support/abi-executor.ts`), so what
+ * these prove is what Signage hands Core and how it reads Core's answers: SQL text, ABI parameters,
+ * positional rows of raw text forms, and callback-scoped transactions. The decisions above the store
+ * are proven against the in-memory store elsewhere.
+ */
+
+const GROUP = "00000000-0000-4000-8000-0000000000a1";
+const CHANNEL = "00000000-0000-4000-8000-0000000000b1";
+const FALLBACK_CHANNEL = "00000000-0000-4000-8000-0000000000b2";
+const SELECTION = "00000000-0000-4000-8000-0000000000c1";
+const TIMELINE = "00000000-0000-4000-8000-0000000000d1";
+const SOURCE = "00000000-0000-4000-8000-0000000000e1";
+const SLOT_1 = "00000000-0000-4000-8000-0000000000f1";
+const SLOT_2 = "00000000-0000-4000-8000-0000000000f2";
+const IMAGE = "00000000-0000-4000-8000-000000000101";
+
+const INSTANT = new Date("2026-10-08T12:34:56.789Z");
+/** How Core sends that instant: PostgreSQL's ISO output in UTC (ADR 0050's decoding table). */
+const INSTANT_TEXT = "2026-10-08 12:34:56.789+00";
+
+function image(): NewStoredImage {
+  return {
+    contentSha256: "a".repeat(64),
+    displayName: "Welcome",
+    encodedHeight: 1080,
+    encodedWidth: 1920,
+    expiresAt: INSTANT,
+    hasAlpha: false,
+    height: 1080,
+    id: IMAGE,
+    orientation: null,
+    originalByteSize: 5_000_000_000,
+    originalContentType: "image/png",
+    originalFilename: "welcome.png",
+    originalObjectKey: `originals/${IMAGE}`,
+    renditions: [
+      {
+        byteSize: 1234,
+        contentSha256: "b".repeat(64),
+        contentType: "image/webp",
+        height: 1080,
+        kind: "display",
+        objectKey: `renditions/${IMAGE}/display`,
+        width: 1920,
+      },
+    ],
+    status: "ready",
+    width: 1920,
+  };
+}
+
+function selection(): NewStoredSelection {
+  return {
+    availableUntil: null,
+    deadlineAt: new Date(INSTANT.getTime() + 7_000),
+    durationMs: 7_000,
+    groupId: GROUP,
+    id: SELECTION,
+    itemId: IMAGE,
+    itemRevision: "1",
+    presentation: { tone: "warm" },
+    providerId: "signage.native-images",
+    rendererContributionId: null,
+    rendererContributionVersion: null,
+    selectionScope: null,
+    sequence: 9_007_199_254_740_000,
+    slotId: SLOT_1,
+    stale: false,
+    startedAt: INSTANT,
+    timelineId: TIMELINE,
+    variants: [
+      { audienceKey: "default", isDefault: true, payload: { title: "Hello" } },
+      { audienceKey: "online", isDefault: false, payload: "just text" },
+    ],
+    withdrawn: false,
+  };
+}
+
+function slot(id: string): NewStoredSlot {
+  return {
+    durationOverrideMs: null,
+    eligibleFrom: null,
+    eligibleUntil: INSTANT,
+    enabled: true,
+    id,
+    itemId: IMAGE,
+    kind: "pinned-item",
+    presentation: {
+      backgroundColor: null,
+      backgroundDarkened: null,
+      backgroundMode: null,
+      blurPixels: null,
+      foregroundShadow: null,
+    },
+    providerId: "signage.native-images",
+    sourceId: null,
+    timelineId: TIMELINE,
+  };
+}
+
+/** Answers a select from a table with the given rows, and every other statement with none. */
+function rowsFrom(tables: Readonly<Record<string, AbiResponder>>): AbiResponder {
+  return (statement) => tables[statement.summary]?.(statement);
+}
+
+function times(count: number, summary: string): string[] {
+  return Array.from({ length: count }, () => summary);
+}
+
+describe("Signage's production store over the Module Database ABI v1", () => {
+  it("reaches PostgreSQL only as SQL text, ABI parameters, and positional rows", async () => {
+    const fake = createFakeAbiExecutor();
+
+    await createSignageStore(fake.executor).listTimelines();
+    await createSignageStore(fake.executor).findViewerByKey("kiosk-1");
+
+    expect(fake.events).toEqual(["select signage_timelines", "select signage_viewers"]);
+    for (const statement of fake.statements) {
+      expect(statement.depth).toBe(0);
+      expect(statement.rowMode).toBe("array");
+      expect(statement.text).not.toContain("kiosk-1");
+    }
+    expect(fake.statements[1]?.values).toEqual(["kiosk-1"]);
+  });
+
+  it("encodes instants as ISO text and JSON as text, never as objects Core would refuse", async () => {
+    const fake = createFakeAbiExecutor();
+
+    await createSignageStore(fake.executor).insertSelection(selection());
+
+    const [selectionInsert, variantsInsert] = fake.statements;
+    expect(selectionInsert?.values).toContain("2026-10-08T12:34:56.789Z");
+    expect(selectionInsert?.values).toContain("2026-10-08T12:35:03.789Z");
+    expect(selectionInsert?.values).toContain('{"tone":"warm"}');
+    expect(selectionInsert?.values).toContain(9_007_199_254_740_000);
+    expect(variantsInsert?.values).toContain('{"title":"Hello"}');
+    expect(variantsInsert?.values).toContain('"just text"');
+  });
+
+  it("decodes the ABI's raw int8, timestamptz, and jsonb text into the values Signage reads", async () => {
+    const fake = createFakeAbiExecutor(
+      rowsFrom({
+        "select signage_channel_groups": () => [
+          {
+            created_at: INSTANT_TEXT,
+            id: GROUP,
+            name: "Sanctuary",
+            revision: 3,
+            updated_at: INSTANT_TEXT,
+          },
+        ],
+        "select signage_channels": () => [
+          { group_id: GROUP, id: CHANNEL, is_default: true, key: "default", name: "Default" },
+        ],
+        "select signage_image_assets": () => [
+          {
+            content_sha256: "a".repeat(64),
+            created_at: "2026-10-08 12:00:00.123456+00",
+            display_name: "Welcome",
+            encoded_height: 1080,
+            encoded_width: 1920,
+            expires_at: null,
+            has_alpha: false,
+            height: 1080,
+            id: IMAGE,
+            orientation: 6,
+            original_byte_size: "5000000000",
+            original_content_type: "image/png",
+            original_filename: "welcome.png",
+            original_object_key: `originals/${IMAGE}`,
+            status: "ready",
+            width: 1920,
+          },
+        ],
+        "select signage_image_renditions": () => [
+          {
+            asset_id: IMAGE,
+            byte_size: "1234",
+            content_sha256: "b".repeat(64),
+            content_type: "image/webp",
+            height: 1080,
+            kind: "display",
+            object_key: `renditions/${IMAGE}/display`,
+            width: 1920,
+          },
+        ],
+        "select signage_playback_states": () => [
+          {
+            active_timeline_id: TIMELINE,
+            blackout: false,
+            current_selection_id: SELECTION,
+            current_slot_id: SLOT_1,
+            group_id: GROUP,
+            next_sequence: "42",
+            paused: false,
+            paused_remaining_ms: null,
+            pending_requested_at: null,
+            pending_timeline_id: null,
+            revision: 17,
+            scheduled_activation_at: "2026-10-09 07:30:00-05",
+            scheduled_timeline_id: TIMELINE,
+            slot_deadline_at: "2026-10-08 12:35:03.789+00",
+            slot_started_at: INSTANT_TEXT,
+            static_asset_id: null,
+            updated_at: INSTANT_TEXT,
+          },
+        ],
+        "select signage_selection_variants": () => [
+          {
+            audience_key: "default",
+            id: "00000000-0000-4000-8000-000000000201",
+            is_default: true,
+            payload: '{"title":"Hello","lines":[1,2]}',
+            selection_id: SELECTION,
+          },
+          {
+            audience_key: "online",
+            id: "00000000-0000-4000-8000-000000000202",
+            is_default: false,
+            payload: '"123"',
+            selection_id: SELECTION,
+          },
+        ],
+        "select signage_selections": () => [
+          {
+            available_until: null,
+            deadline_at: null,
+            duration_ms: 7000,
+            group_id: GROUP,
+            id: SELECTION,
+            item_id: IMAGE,
+            item_revision: "1",
+            presentation: '{"tone":"warm"}',
+            provider_id: "signage.native-images",
+            renderer_contribution_id: null,
+            renderer_contribution_version: null,
+            resolved_at: INSTANT_TEXT,
+            revision: 2,
+            selection_scope: null,
+            sequence: "9007199254740000",
+            slot_id: SLOT_1,
+            stale: false,
+            started_at: INSTANT_TEXT,
+            timeline_id: TIMELINE,
+            withdrawn: false,
+          },
+        ],
+        "update signage_playback_states": () => [{ next_sequence: "43" }],
+      }),
+    );
+    const store = createSignageStore(fake.executor);
+
+    const group = await store.findChannelGroup(GROUP);
+    expect(group?.playback).toMatchObject({
+      nextSequence: 42,
+      revision: 17,
+      scheduledActivationAt: new Date("2026-10-09T12:30:00.000Z"),
+      slotDeadlineAt: new Date("2026-10-08T12:35:03.789Z"),
+      slotStartedAt: INSTANT,
+      updatedAt: INSTANT,
+    });
+    expect(group?.playback.slotStartedAt).toBeInstanceOf(Date);
+    expect(group?.channels).toEqual([
+      { groupId: GROUP, id: CHANNEL, isDefault: true, key: "default", name: "Default" },
+    ]);
+
+    const found = await store.findSelection(SELECTION);
+    expect(found).toMatchObject({
+      presentation: { tone: "warm" },
+      resolvedAt: INSTANT,
+      sequence: 9_007_199_254_740_000,
+      startedAt: INSTANT,
+    });
+    expect(found?.variants).toEqual([
+      { audienceKey: "default", isDefault: true, payload: { lines: [1, 2], title: "Hello" } },
+      // A JSON string stays a string, even one that looks like a number.
+      { audienceKey: "online", isDefault: false, payload: "123" },
+    ]);
+
+    // `returning` rows decode the same way: the sequence this call owns is one below the new value.
+    await expect(store.takeSelectionSequence(GROUP)).resolves.toBe(42);
+
+    const [listed] = await store.listImages();
+    expect(listed).toMatchObject({
+      createdAt: new Date("2026-10-08T12:00:00.123Z"),
+      expiresAt: null,
+      orientation: 6,
+      originalByteSize: 5_000_000_000,
+    });
+    expect(listed?.renditions).toEqual([expect.objectContaining({ byteSize: 1234 })]);
+  });
+});
+
+describe("Signage's transactions over the ABI", () => {
+  const existingSlots = () => [
+    { id: SLOT_1, position: 0 },
+    { id: SLOT_2, position: 1 },
+  ];
+  const flows: readonly {
+    readonly name: string;
+    readonly respond?: AbiResponder;
+    readonly run: (store: SignageStore) => Promise<unknown>;
+    readonly expected: readonly string[];
+  }[] = [
+    {
+      expected: ["insert signage_image_assets", "insert signage_image_renditions"],
+      name: "insertImage",
+      run: (store) => store.insertImage(image()),
+    },
+    {
+      expected: ["insert signage_channels", "update signage_channel_groups"],
+      name: "addChannel",
+      run: (store) =>
+        store.addChannel({
+          groupId: GROUP,
+          id: CHANNEL,
+          isDefault: false,
+          key: "online",
+          name: "Online",
+        }),
+    },
+    {
+      expected: [
+        "insert signage_channel_groups",
+        "insert signage_channels",
+        "insert signage_playback_states",
+      ],
+      name: "createChannelGroup",
+      run: (store) =>
+        store.createChannelGroup({
+          channelId: CHANNEL,
+          channelName: "Default",
+          groupId: GROUP,
+          name: "Sanctuary",
+        }),
+    },
+    {
+      expected: [
+        "select signage_channels",
+        "update signage_viewers",
+        "delete signage_channel_groups",
+      ],
+      name: "deleteChannelGroup",
+      respond: rowsFrom({ "select signage_channels": () => [{ id: CHANNEL }] }),
+      run: (store) => store.deleteChannelGroup(GROUP, FALLBACK_CHANNEL),
+    },
+    {
+      expected: ["insert signage_selections", "insert signage_selection_variants"],
+      name: "insertSelection",
+      run: (store) => store.insertSelection(selection()),
+    },
+    {
+      expected: [
+        "select signage_channels",
+        "delete signage_channels",
+        "update signage_channel_groups",
+      ],
+      name: "removeChannel",
+      respond: rowsFrom({
+        "select signage_channels": () => [
+          { group_id: GROUP, id: CHANNEL, is_default: false, key: "online", name: "Online" },
+        ],
+      }),
+      run: (store) => store.removeChannel(CHANNEL),
+    },
+    {
+      expected: [
+        "update signage_selections",
+        "delete signage_selection_variants",
+        "insert signage_selection_variants",
+      ],
+      name: "updateSelection",
+      run: (store) =>
+        store.updateSelection(SELECTION, {
+          bumpRevision: true,
+          stale: true,
+          variants: [{ audienceKey: "default", isDefault: true, payload: { title: "Again" } }],
+        }),
+    },
+    {
+      expected: [
+        "select signage_timeline_slots",
+        "insert signage_timeline_slots",
+        ...times(6, "update signage_timeline_slots"),
+        "update signage_timelines",
+      ],
+      name: "addSlot",
+      respond: rowsFrom({ "select signage_timeline_slots": existingSlots }),
+      run: (store) => store.addSlot({ ...slot("00000000-0000-4000-8000-0000000000f3") }, 1),
+    },
+    {
+      expected: [
+        "insert signage_timelines",
+        "insert signage_provider_sources",
+        "insert signage_timeline_slots",
+      ],
+      name: "createTimeline",
+      run: (store) =>
+        store.createTimeline({
+          slots: [slot(SLOT_1)],
+          sources: [
+            {
+              id: SOURCE,
+              label: "Announcements",
+              providerId: "announcements",
+              selectionScope: "scope-1",
+              sourceId: "all",
+              timelineId: TIMELINE,
+            },
+          ],
+          timeline: {
+            description: null,
+            eligibleFrom: INSTANT,
+            eligibleUntil: null,
+            id: TIMELINE,
+            name: "Sunday",
+          },
+        }),
+    },
+    {
+      expected: [
+        "select signage_timeline_slots",
+        "delete signage_timeline_slots",
+        "select signage_timeline_slots",
+        ...times(2, "update signage_timeline_slots"),
+        "update signage_timelines",
+      ],
+      name: "removeSlot",
+      respond: rowsFrom({
+        "select signage_timeline_slots": (statement) =>
+          statement.text.includes('"position"')
+            ? [{ id: SLOT_2, position: 1 }]
+            : [{ timeline_id: TIMELINE }],
+      }),
+      run: (store) => store.removeSlot(SLOT_1),
+    },
+    {
+      expected: [
+        "select signage_provider_sources",
+        "delete signage_provider_sources",
+        "select signage_timeline_slots",
+        ...times(4, "update signage_timeline_slots"),
+        "update signage_timelines",
+      ],
+      name: "removeSource",
+      respond: rowsFrom({
+        "select signage_provider_sources": () => [{ timeline_id: TIMELINE }],
+        "select signage_timeline_slots": existingSlots,
+      }),
+      run: (store) => store.removeSource(SOURCE),
+    },
+    {
+      expected: [
+        "select signage_timeline_slots",
+        ...times(4, "update signage_timeline_slots"),
+        "update signage_timelines",
+      ],
+      name: "reorderSlots",
+      respond: rowsFrom({ "select signage_timeline_slots": existingSlots }),
+      run: (store) => store.reorderSlots(TIMELINE, [SLOT_2, SLOT_1]),
+    },
+    {
+      expected: [
+        "select signage_timeline_slots",
+        "update signage_timeline_slots",
+        "update signage_timelines",
+      ],
+      name: "updateSlot",
+      respond: rowsFrom({ "select signage_timeline_slots": () => [{ timeline_id: TIMELINE }] }),
+      run: (store) => store.updateSlot(SLOT_1, { enabled: false, eligibleUntil: INSTANT }),
+    },
+  ];
+
+  it("covers every transaction the store opens", () => {
+    // Thirteen `database.transaction` calls in src/server/store, none of them nested.
+    expect(flows.map((flow) => flow.name)).toHaveLength(13);
+  });
+
+  for (const flow of flows) {
+    it(`${flow.name} runs as one ABI transaction and commits`, async () => {
+      const fake = createFakeAbiExecutor(flow.respond);
+
+      await flow.run(createSignageStore(fake.executor));
+
+      expect(fake.events).toEqual(["BEGIN", ...flow.expected, "COMMIT"]);
+      // Every statement ran inside the transaction's own scope, and none opened a savepoint.
+      expect(fake.statements.every((statement) => statement.depth === 1)).toBe(true);
+    });
+  }
+
+  it("rolls back a refused default-channel removal and reports the conflict", async () => {
+    const fake = createFakeAbiExecutor(
+      rowsFrom({
+        "select signage_channels": () => [
+          { group_id: GROUP, id: CHANNEL, is_default: true, key: "default", name: "Default" },
+        ],
+      }),
+    );
+
+    await expect(createSignageStore(fake.executor).removeChannel(CHANNEL)).rejects.toMatchObject({
+      guarantee: "channel.default",
+      name: "SignageStoreConflict",
+    });
+    expect(fake.events).toEqual(["BEGIN", "select signage_channels", "ROLLBACK"]);
+  });
+
+  it("rolls back a slot order that is not exactly the timeline's slots", async () => {
+    const fake = createFakeAbiExecutor(
+      rowsFrom({ "select signage_timeline_slots": existingSlots }),
+    );
+
+    await expect(
+      createSignageStore(fake.executor).reorderSlots(TIMELINE, [SLOT_2]),
+    ).rejects.toMatchObject({ guarantee: "timeline.slotOrder" });
+    expect(fake.events).toEqual(["BEGIN", "select signage_timeline_slots", "ROLLBACK"]);
+  });
+
+  it("rolls back the whole transaction when a later statement fails, and keeps that error", async () => {
+    const fake = createFakeAbiExecutor((statement) => {
+      if (statement.summary === "insert signage_selection_variants") {
+        throw new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23503" });
+      }
+      return [];
+    });
+
+    const failure = await createSignageStore(fake.executor)
+      .insertSelection(selection())
+      .then(
+        () => undefined,
+        (error: unknown) => error,
+      );
+
+    expect(fake.events).toEqual([
+      "BEGIN",
+      "insert signage_selections",
+      "insert signage_selection_variants",
+      "ROLLBACK",
+    ]);
+    expect(failure).not.toBeInstanceOf(SignageStoreConflict);
+    expect((failure as Error).cause).toSatisfy(isModuleDatabaseError);
+  });
+});
+
+describe("a duplicate native image (SQLSTATE 23505)", () => {
+  function failingAssetInsert(error: Error) {
+    return createFakeAbiExecutor((statement) => {
+      if (statement.summary === "insert signage_image_assets") {
+        throw error;
+      }
+      return [];
+    });
+  }
+
+  it("reaches Signage wrapped by Drizzle, with the Ekklesia error as its cause", async () => {
+    // Why the old `error.code === "23505"` check never matched: Drizzle wraps whatever the driver,
+    // here the ABI executor, throws.
+    const fake = failingAssetInsert(
+      new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23505" }),
+    );
+    const failure = await moduleDrizzle(fake.executor)
+      .insert(imageAssets)
+      .values({ ...image(), renditions: undefined } as never)
+      .then(
+        () => undefined,
+        (error: unknown) => error as Error & { code?: unknown },
+      );
+
+    expect(failure?.name).not.toBe("ModuleDatabaseError");
+    expect(failure?.code).toBeUndefined();
+    expect(failure?.cause).toMatchObject({
+      code: "MODULE_DATABASE_QUERY_FAILED",
+      name: "ModuleDatabaseError",
+      sqlState: "23505",
+    });
+  });
+
+  it("is recognized through that wrapping and reported as Signage's content-hash conflict", async () => {
+    const fake = failingAssetInsert(
+      new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23505" }),
+    );
+
+    const failure = await createSignageStore(fake.executor)
+      .insertImage(image())
+      .then(
+        () => undefined,
+        (error: unknown) => error,
+      );
+
+    expect(failure).toBeInstanceOf(SignageStoreConflict);
+    expect((failure as SignageStoreConflict).guarantee).toBe("image.contentSha256");
+    expect(fake.events).toEqual(["BEGIN", "insert signage_image_assets", "ROLLBACK"]);
+  });
+
+  it.each([
+    [
+      "a foreign-key violation",
+      new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23503" }),
+    ],
+    ["a failure with no SQLSTATE", new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED")],
+    ["a refused parameter", new ModuleDatabaseError("MODULE_DATABASE_PARAMETER_INVALID")],
+    // A driver-shaped error is never what the ABI throws, and Signage no longer reads one.
+    ["a raw pg-shaped error", Object.assign(new Error("duplicate key"), { code: "23505" })],
+  ])("does not mistake %s for a duplicate", async (_name, error) => {
+    const fake = failingAssetInsert(error);
+
+    const failure = await createSignageStore(fake.executor)
+      .insertImage(image())
+      .then(
+        () => undefined,
+        (caught: unknown) => caught,
+      );
+
+    expect(failure).toBeInstanceOf(Error);
+    expect(failure).not.toBeInstanceOf(SignageStoreConflict);
+    expect((failure as Error).cause).toBe(error);
+    expect(fake.events.at(-1)).toBe("ROLLBACK");
+  });
+});

tests/drizzle-timelines.test.ts

@@ -1,4 +1,4 @@
-import type { ModuleDatabase } from "@ekklesia/module-sdk";
+import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
 import { describe, expect, it } from "vitest";
 import { createTimelineStore } from "../src/server/store/drizzle-timelines.js";
 import type { NewStoredSlot } from "../src/server/store/types.js";
@@ -36,7 +36,7 @@ function slot(id: string): NewStoredSlot {
  * actual database rejected a native-image slot before playback ever had content to resolve.
  */
 function constraintDatabase(existing: readonly { id: string; position: number }[]): {
-  readonly database: ModuleDatabase;
+  readonly database: ModuleDrizzleDatabase;
   readonly positions: number[];
 } {
   const positions: number[] = [];
@@ -66,7 +66,7 @@ function constraintDatabase(existing: readonly { id: string; position: number }[
   return {
     database: {
       transaction: async (operation: (value: typeof transaction) => Promise<unknown>) => operation(transaction),
-    } as unknown as ModuleDatabase,
+    } as unknown as ModuleDrizzleDatabase,
     positions,
   };
 }

tests/manifest.test.ts

@@ -63,11 +63,19 @@ describe("Signage module manifest", () => {
   it("declares the module's product identity at the current manifest version", async () => {
     const manifest = await readManifest();
 
-    expect(manifest.manifestVersion).toBe(7);
+    expect(manifest.manifestVersion).toBe(8);
     expect(manifest.id).toBe("signage");
     expect(manifest.name).toBe("Signage");
-    expect(manifest.version).toBe("0.1.1");
+    expect(manifest.version).toBe("0.1.2");
-    expect(manifest.compatibility).toEqual({ moduleSdk: "^0.1.0", platform: "^0.1.0" });
+    expect(manifest.compatibility).toEqual({ moduleSdk: "^0.2.0", platform: "^0.2.0" });
+  });
+
+  it("declares the Module Database ABI v1, so the platform hands it an executor and no ORM object", async () => {
+    const manifest = await readManifest();
+
+    // Platform ADR 0050: with `database.abi: 1`, `services.database` is the ABI v1 executor. Without
+    // it, a version 8 manifest would get the legacy Drizzle facade Signage no longer compiles against.
+    expect(manifest.database).toEqual({ abi: 1 });
   });
 
   it("declares every Signage permission, and none of them publicly", async () => {
@@ -142,7 +150,8 @@ describe("Signage module manifest", () => {
 
 describe("Signage server runtime", () => {
   it("exports the typed runtime definition the compiled server entrypoint publishes", async () => {
-    expect(moduleRuntime).toMatchObject({ id: "signage", version: "0.1.1" });
+    // The runtime's database declaration must match the manifest's, or Core refuses to start it.
+    expect(moduleRuntime).toMatchObject({ database: { abi: 1 }, id: "signage", version: "0.1.2" });
   });
 
   it("registers its routes declaratively, with no database, storage, or realtime work", async () => {
@@ -241,7 +250,7 @@ describe("Signage server runtime", () => {
     expect(response.status).toBe(200);
     expect(await response.json()).toEqual({
       crossfadeMs: 400,
-      moduleVersion: "0.1.1",
+      moduleVersion: "0.1.2",
       nativeImageDurationMs: 12_000,
       nativePresentation: SIGNAGE_DEFAULT_SETTINGS.nativePresentation,
       rendererInputVersion: "1.0.0",

tests/schema.test.ts

@@ -7,9 +7,12 @@ import {
 } from "@ekklesia/module-sdk";
 import { getTableConfig, type PgTable } from "drizzle-orm/pg-core";
 import { describe, expect, it } from "vitest";
-import moduleSchema from "../src/schema/index.js";
+import * as schemaEntrypoint from "../src/schema/index.js";
+import * as schemaTables from "../src/schema/tables.js";
 
-const tables = moduleSchema.tables as Readonly<Record<string, PgTable>>;
+const moduleSchema = schemaEntrypoint.default;
+/** Signage's own Drizzle tables, which only its store code uses. Core sees the metadata above. */
+const tables: Readonly<Record<string, PgTable>> = schemaTables;
 
 async function readSql(): Promise<string> {
   return readFile(new URL("../drizzle/0000_initial.sql", import.meta.url), "utf8");
@@ -43,6 +46,50 @@ describe("Signage schema", () => {
     expect(moduleSchema.moduleId).toBe("signage");
   });
 
+  it("hands Core plain ABI v1 schema metadata: names and foreign-key targets, and no Drizzle object", () => {
+    // Platform ADR 0050: Core validates table ownership from plain data and never inspects an ORM
+    // object. The entrypoint's only export is that data.
+    expect(Object.keys(schemaEntrypoint)).toEqual(["default"]);
+    expect(JSON.parse(JSON.stringify(moduleSchema))).toEqual(moduleSchema);
+    const byName = [...moduleSchema.tables].sort((left, right) =>
+      left.name < right.name ? -1 : left.name > right.name ? 1 : 0,
+    );
+    expect(byName).toEqual([
+      { name: "signage_channel_groups", foreignKeys: [] },
+      { name: "signage_channels", foreignKeys: [{ table: "signage_channel_groups" }] },
+      { name: "signage_image_assets", foreignKeys: [] },
+      { name: "signage_image_renditions", foreignKeys: [{ table: "signage_image_assets" }] },
+      {
+        name: "signage_playback_states",
+        foreignKeys: [
+          { table: "signage_channel_groups" },
+          { table: "signage_timelines" },
+          { table: "signage_timelines" },
+          { table: "signage_image_assets" },
+          { table: "signage_timelines" },
+        ],
+      },
+      { name: "signage_provider_sources", foreignKeys: [{ table: "signage_timelines" }] },
+      { name: "signage_selection_variants", foreignKeys: [{ table: "signage_selections" }] },
+      {
+        name: "signage_selections",
+        foreignKeys: [{ table: "signage_channel_groups" }, { table: "signage_timeline_slots" }],
+      },
+      {
+        name: "signage_timeline_slots",
+        foreignKeys: [{ table: "signage_timelines" }, { table: "signage_provider_sources" }],
+      },
+      { name: "signage_timelines", foreignKeys: [] },
+      { name: "signage_viewers", foreignKeys: [{ table: "signage_channels" }] },
+    ]);
+    // The same tables the store queries, derived rather than restated, so the two cannot drift.
+    expect(byName.map((table) => table.name)).toEqual(
+      Object.values(tables)
+        .map((table) => getTableConfig(table).name)
+        .sort(),
+    );
+  });
+
   it("never points a foreign key outside this module", () => {
     const owned = new Set(Object.values(tables).map((table) => getTableConfig(table).name));
 

tests/support/abi-executor.ts

@@ -0,0 +1,228 @@
+import {
+  ModuleDatabaseError,
+  type ModuleDatabaseExecutor,
+  type ModuleDatabaseParameter,
+  type ModuleDatabaseQuery,
+  type ModuleDatabaseTransaction,
+  type ModuleDatabaseValue,
+} from "@ekklesia/module-database";
+
+/**
+ * A Module Database ABI v1 executor double (platform ADR 0050), for proving Signage's production
+ * store without PostgreSQL.
+ *
+ * It holds Signage to the rules the platform's real executor enforces, so a store change that would
+ * break against Core breaks here first:
+ *
+ * - parameters must be ABI values — a `Date` or a plain object is refused, exactly as Core refuses
+ *   one, so an instant or a JSON payload the adapter failed to encode cannot slip through;
+ * - transactions and savepoints are callback scopes: committed only when the callback resolves with
+ *   no work outstanding, rolled back when it rejects, and revoked once it settles;
+ * - only the innermost open scope may run statements;
+ * - after a failed statement the transaction is aborted, as in PostgreSQL, and cannot commit.
+ *
+ * Results are what Core sends: positional rows of the ABI's raw forms (`int8`, timestamps, and JSON
+ * as text). A responder answers each statement with rows keyed by column name; the double orders
+ * them by the statement's own select or returning list.
+ */
+
+export interface RecordedStatement {
+  readonly text: string;
+  readonly values: readonly ModuleDatabaseParameter[];
+  readonly rowMode: string;
+  /** 0 for an autocommit statement, 1 inside a transaction, 2 or more inside savepoints. */
+  readonly depth: number;
+  /** `select signage_timelines`, `insert signage_channels`, and so on. */
+  readonly summary: string;
+}
+
+export type AbiRow = Readonly<Record<string, ModuleDatabaseValue>>;
+export type AbiResponder = (statement: RecordedStatement) => readonly AbiRow[] | undefined;
+
+export interface FakeAbiExecutor {
+  readonly executor: ModuleDatabaseExecutor;
+  /** Every statement, in order, plus `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`, and
+   * `ROLLBACK TO SAVEPOINT` markers. */
+  readonly events: string[];
+  readonly statements: RecordedStatement[];
+}
+
+function isAbiParameter(value: unknown): value is ModuleDatabaseParameter {
+  if (value === null) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every(isAbiParameter);
+  }
+  return (
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "bigint" ||
+    typeof value === "string" ||
+    value instanceof Uint8Array
+  );
+}
+
+function summarize(text: string): string {
+  const verb = text.trimStart().split(/\s/u, 1)[0]?.toLowerCase() ?? "";
+  const target =
+    verb === "select"
+      ? /\bfrom\s+"([^"]+)"/iu.exec(text)
+      : verb === "insert"
+        ? /^\s*insert\s+into\s+"([^"]+)"/iu.exec(text)
+        : verb === "update"
+          ? /^\s*update\s+"([^"]+)"/iu.exec(text)
+          : /^\s*delete\s+from\s+"([^"]+)"/iu.exec(text);
+  return `${verb} ${target?.[1] ?? "?"}`;
+}
+
+/** The column names a statement returns, in order: its select list, or its `returning` list. */
+function resultColumns(text: string): string[] {
+  const list =
+    /^\s*select\s+(.*?)\s+from\s/isu.exec(text)?.[1] ?? /\sreturning\s+(.*)$/isu.exec(text)?.[1];
+  if (list === undefined) {
+    return [];
+  }
+  return list.split(",").map((column) => {
+    const names = [...column.matchAll(/"([^"]+)"/gu)].map((match) => match[1] ?? "");
+    return names.at(-1) ?? column.trim();
+  });
+}
+
+interface Scope {
+  closed: boolean;
+  active: boolean;
+  pending: number;
+  aborted: boolean;
+}
+
+export function createFakeAbiExecutor(respond: AbiResponder = () => []): FakeAbiExecutor {
+  const events: string[] = [];
+  const statements: RecordedStatement[] = [];
+
+  async function run(
+    scope: Scope,
+    transaction: Scope | undefined,
+    depth: number,
+    request: ModuleDatabaseQuery,
+  ) {
+    if (scope.closed) {
+      throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_CLOSED");
+    }
+    if (!scope.active) {
+      throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_INACTIVE");
+    }
+    const values = request.values ?? [];
+    if (!values.every(isAbiParameter)) {
+      throw new ModuleDatabaseError("MODULE_DATABASE_PARAMETER_INVALID");
+    }
+    if (transaction?.aborted) {
+      // PostgreSQL's in_failed_sql_transaction.
+      throw new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "25P02" });
+    }
+    const statement: RecordedStatement = {
+      depth,
+      rowMode: request.rowMode ?? "object",
+      summary: summarize(request.text),
+      text: request.text,
+      values,
+    };
+    statements.push(statement);
+    events.push(statement.summary);
+    scope.pending += 1;
+    try {
+      // Settle on a later event-loop turn, as a real round trip does, so a statement a callback
+      // forgot to await is still outstanding when that callback returns.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      let rows: readonly AbiRow[];
+      try {
+        rows = respond(statement) ?? [];
+      } catch (error) {
+        if (transaction) {
+          transaction.aborted = true;
+        }
+        throw error;
+      }
+      const columns = resultColumns(request.text);
+      return {
+        command: statement.summary.split(" ")[0]?.toUpperCase() ?? "",
+        fields: columns.map((name) => ({ name, typeOid: 25 })),
+        rowCount: rows.length,
+        rows:
+          statement.rowMode === "array"
+            ? rows.map((row) => columns.map((column) => row[column] ?? null))
+            : rows,
+      };
+    } finally {
+      scope.pending -= 1;
+    }
+  }
+
+  async function runScope<T>(
+    parent: Scope,
+    transaction: Scope | undefined,
+    depth: number,
+    callback: (scope: ModuleDatabaseTransaction) => Promise<T> | T,
+  ): Promise<T> {
+    const isTransaction = transaction === undefined;
+    const scope: Scope = { aborted: false, active: true, closed: false, pending: 0 };
+    const owner = transaction ?? scope;
+    const executor = Object.freeze({
+      abiVersion: 1 as const,
+      query: (request: ModuleDatabaseQuery) => run(scope, owner, depth, request),
+      savepoint: <S>(inner: (savepoint: ModuleDatabaseTransaction) => Promise<S> | S) => {
+        if (scope.closed) {
+          return Promise.reject(new ModuleDatabaseError("MODULE_DATABASE_SCOPE_CLOSED"));
+        }
+        if (!scope.active) {
+          return Promise.reject(new ModuleDatabaseError("MODULE_DATABASE_SCOPE_INACTIVE"));
+        }
+        return runScope(scope, owner, depth + 1, inner);
+      },
+    }) as unknown as ModuleDatabaseTransaction;
+
+    parent.active = false;
+    events.push(isTransaction ? "BEGIN" : "SAVEPOINT");
+    const abort = isTransaction ? "ROLLBACK" : "ROLLBACK TO SAVEPOINT";
+    try {
+      let value: T;
+      try {
+        value = await callback(executor);
+      } catch (error) {
+        events.push(abort);
+        throw error;
+      }
+      if (scope.pending > 0) {
+        events.push(abort);
+        throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_WORK_OUTSTANDING");
+      }
+      if (isTransaction && owner.aborted) {
+        events.push(abort);
+        throw new ModuleDatabaseError("MODULE_DATABASE_TRANSACTION_FAILED", { sqlState: "25P02" });
+      }
+      events.push(isTransaction ? "COMMIT" : "RELEASE");
+      return value;
+    } finally {
+      if (!isTransaction && events.at(-1) === abort) {
+        // A savepoint that rolled back leaves its transaction usable, as in PostgreSQL.
+        owner.aborted = false;
+      }
+      scope.closed = true;
+      parent.active = true;
+    }
+  }
+
+  const root: Scope = { aborted: false, active: true, closed: false, pending: 0 };
+  const executor = Object.freeze({
+    abiVersion: 1 as const,
+    query: (request: ModuleDatabaseQuery) => run(root, undefined, 0, request),
+    transaction: <T>(callback: (transaction: ModuleDatabaseTransaction) => Promise<T> | T) => {
+      // Top-level statements are autocommit and may run on other pooled connections, so the root
+      // executor stays usable while a transaction is open.
+      const detached: Scope = { aborted: false, active: true, closed: false, pending: 0 };
+      return runScope(detached, undefined, 1, callback);
+    },
+  }) as unknown as ModuleDatabaseExecutor;
+
+  return { events, executor, statements };
+}

vitest.config.ts

@@ -3,9 +3,9 @@ import { defineConfig } from "vitest/config";
 /**
  * Signage's own test configuration.
  *
- * It exists because this module's browser tests are `.tsx` — they mount real React — and the
+ * It names both `.test.ts` and `.test.tsx` explicitly, because this module's browser tests are `.tsx`
- * repository root's configuration includes only `.test.ts`. Without this file those tests are
+ * — they mount real React — and a test that is silently not run is the worst possible failure mode
- * silently not run, which is the worst possible failure mode for a test suite.
+ * for a test suite. An empty run fails rather than passes.
  */
 export default defineConfig({
   test: {