The problem with "a comic is a product"

Mythos 1.0.0 stored each issue as a WooCommerce product, and the theme declared Requires Plugins: woocommerce. A publisher who just wanted to publish comics was stuck running a store.

In 1.1.0, comics became first-class content:

• a mythos_comic post type at /comics/
• mythos_series (/series/) and mythos_creator (/creator/) taxonomies, where a creator can carry a role such as Writer or Artist
• an Issue details meta box for issue number, kicker, rack blurb, free-chapter link and story panels chosen through the media modal

WooCommerce became optional. A comic can link to one product, picked from a searchable picker on the comic screen, and the same product can't be linked twice. Price and Add to cart only appear when WooCommerce is active and the product is public. When WooCommerce is off, the link shows as "kept" and saving never touches it, and old /product/… URLs redirect to the linked comic instead of falling through to the homepage.

Inkline goes about it differently. Its ink_comic post type, series and creators live in a companion plugin, inkline-comics-core, so the content survives a theme switch. Mythos registers its types in the theme itself, so switching themes hides the comics (the data stays), and the readme says so.

Migrating products to comics without breaking anything

Existing 1.0 sites already had their comics stored as products, so on first load 1.1.0 copies each comic product into a linked comic record. The rules I held myself to:

1. Delete nothing. Products, product meta and the 1.0 theme mods aren't touched, so rolling back to 1.0.0 still works. The old homepage values are also copied into a mythos_legacy_backup option before anything else runs.
2. Never duplicate. If a product already has a comic, the migration links to it instead of copying again, so re-running is safe.
3. Batch it, and lock it. The migration handles 200 products per request behind an option-based lock. A stale lock from a crashed request expires after two minutes:

if ( ! add_option( 'mythos_migrate_lock', time(), '', false ) ) {
    $since = (int) get_option( 'mythos_migrate_lock' );
    if ( $since && time() - $since < 120 ) {
        return;
    }
    update_option( 'mythos_migrate_lock', time(), false );
}

4. Only migrate actual comics. A product counts as a comic if it has Mythos issue fields, creator credits, the sample marker or a homepage selection. Merchandise like a tote bag is left alone, and a "Create comic record" row action covers anything the migration missed.

Product categories become series with the same names and slugs, and galleries become story panels. Homepage links that pointed at a migrated product now point at its comic.

Latest Issues should fill itself

In both themes, "Latest Issues" used to be a list kept up by hand, so a new comic didn't appear until someone edited and saved the homepage.

Now it's a query that runs on every homepage request: published comics only, ordered by post date descending and then ID descending, three by default, with the featured comic optionally left out. In Inkline 1.1.1 it's Homepage::latest_ids(), and the count can be changed with the ink_core_latest_issues_limit filter (clamped to 1–12). Mythos offers the same 1–12 range in its homepage settings. Drafts, pending, private and trashed comics never show, and scheduled comics show up once WordPress publishes them. There's nothing to refresh.

Some people liked curating by hand, so I kept that option. Inkline has a Show newest comics automatically checkbox that's on by default. Upgraded sites keep their old hand-picked list for when the box is unticked. In Mythos, the old hand-numbered rack became a separate, optional Editor's picks shelf.

The bug: saving a subtitle wiped the featured issue

Here's the one that hurt. In Mythos 1.0.0, the homepage picker was a <select> holding the first 100 products. On a test site with 126 products, I changed only the subtitle and saved. featured_id went from 151 to 0, and the hand-picked rack went from four IDs to an empty array.

The cause: the saved featured issue was outside the first 100 products, so it wasn't among the <select> options, and the save wrote the empty result over the stored value. The same happened when WooCommerce was off. An unrelated save destroyed data the user never touched.

The fix in 1.1.0 had three parts:

• The browser's list of options no longer decides what gets saved. Selected IDs live in hidden inputs, and the visible picker is an AJAX search over every comic, 20 per page, by title or ID.
• If a field is missing from the form, the stored value stays. The save handler only changes a selection when its field is actually in the POST data.
• Unchanged IDs are trusted. If the submitted ID equals the stored one, it's kept even if it can't be looked up right now, for example while WooCommerce is off. Only a new selection has to be a valid comic.

Before release, I ran the fix against the scenarios that matter: an in-place upgrade from 1.0.0, WooCommerce deactivated, a fresh install with no store, WooCommerce added later, and a featured comic picked from page 6 of 6 with 110 comics. Each run was followed by an unrelated save to confirm nothing got cleared.

Takeaways

• Don't make content depend on a commerce plugin if you can avoid it. Link to products instead.
• Migrations should copy and link, never move or delete, and be safe to run twice.
• Lists you can compute ("newest issues") shouldn't be stored by hand.
• An empty form field doesn't mean the user cleared it. Treat a missing value as "keep what's stored".

My other WordPress themes and tools are at https://store.mosfetti.com/

— Mosfetti

I built Countback to answer that question on one screen. These are the design decisions behind it and why I made them.

Constraint #1: no server

Countback has no backend, no accounts, no cloud and no telemetry: one device, one IndexedDB store.

It's an installable PWA. The service worker precaches the app shell, so after the first load it opens with the network off. App data never needed the network in the first place. The fetch handler also refuses to touch anything cross-origin:

if (url.origin !== self.location.origin) return;   // never proxy anything off-device

The front end is plain HTML, CSS and ES modules. The only dev dependency is esbuild, for bundling. Nothing extra runs at runtime.

Constraint #2: no mutable status field

I didn't give items a status column. A stored status can drift from what actually happened, and once that happens you can't tell who changed what.

Instead, the on-device document holds kits[], jobs[] and events[]. Item state and the readiness verdict are derived from the events on every render. The event types are deliberately boring:

manifest_frozen, item_out, item_declared_returned, item_verified, item_missing, item_damaged, note, borrower_ack, correction, conflict_raised, resolution.

Each event has the shape {id, type, at, actor, jobId, itemId, payload, supersedes}.

Append-only, enforced in one place

The append-only rule lives in one class that owns the events. append refuses an id that already exists with different content (re-appending identical content is a no-op), and there's no update, delete or splice method. The internal map is a private field, and events() returns deep-frozen copies:

append(input) {
  const event = deepFreeze(normaliseEvent(input));
  const existing = this.#byId.get(event.id);
  if (existing) {
    if (canonical(existing) === canonical(event)) return existing; // idempotent re-append
    throw new AppendOnlyViolation(/* ... */);
  }
  this.#byId.set(event.id, event);
  return event;
}

The IndexedDB adapter follows the same rule: events are keyed by id, and nothing in it ever issues a delete.

Mistakes still happen, so a fix is a new correction event that supersedes the old one. "Superseded" is a read-only view computed from later events, so nothing gets silently overwritten with last-write-wins.

Declared is not verified

This turned out to be the most useful rule in the app. When a borrower says "it's all back", that's a claim, not a check. Each item moves from declared returned to verified, or gets marked missing or damaged with a note. The UI never shows a declared-only return as verified, and a test covers that.

I made that difference visible per item on purpose, because that's where crews argue.

Checkout has the same kind of rule. A checkout isn't complete until a borrower_ack event exists, so acknowledgement is never implied. If the acknowledged hash doesn't match the frozen manifest, that's a blocker too.

Freezing the outgoing manifest

At checkout, Countback freezes the outgoing manifest and shows its SHA-256 content hash. Editing the kit later can't rewrite what actually left the shop.

To make hashes repeatable, every hash is taken over a canonical JSON form. Object keys are sorted, undefined is dropped and there's no whitespace, so two structurally identical values always produce byte-identical text. SHA-256 itself is a small dependency-free implementation, checked against the FIPS 180-4 test vectors. That way the browser, Node and the test suite all produce the same hashes.

Ordering and merging without a server

Without a server clock, ordering needs a rule. Event ids are zero-padded epoch milliseconds plus a suffix, so sorting ids alphabetically also sorts them by time. The hash chain is computed over that sorted order. Two devices that received the same events in a different order end up with the same chain head.

Importing an export merges by event id and never overwrites. If an incoming id matches an existing one but the content differs, it's rejected and reported instead of applied, and contradictory evidence becomes a conflict. An unresolved conflict blocks READY until someone appends an explicit, attributed resolution event. There's no hidden way to edit around it.

The readiness board

Everything above feeds one screen. Items show as OUT, DECLARED, VERIFIED, MISSING or DAMAGED, recomputed from the log on each render, with an overall READY or BLOCKED verdict. Every blocker has one owner and one due time: no frozen manifest, borrower hasn't acknowledged, unresolved conflict, item missing, item damaged, item still out, or a return that's declared but not verified.

Tamper-evident exports

The audit export comes as JSON and as printable HTML. It includes the manifest hash, each event's own content hash, its position in the chain, the chain head and the event count. Because of that, a verifier script can detect both a changed event (tampering) and a dropped event (truncation) offline:

node tools/verify-evidence.mjs docs/evidence/evidence-sample.json

Tests and reproducible builds

The suite has 34 tests on node:test and doesn't need a browser. They cover these acceptance gates:

• two full checkout/return cycles with the network off
• a return killed halfway through loses no events and gives the same verdict after restart
• there's no edit or delete path
• importing the same export twice is idempotent
• tampering and truncation are detected
• the demo path builds an identical chain everywhere

The build honours SOURCE_DATE_EPOCH, and the release script pins it, so rebuilding unchanged sources gives byte-identical dist/ output. The service worker's precache list is generated from the files the build actually emitted, so it can't drift out of sync with the build.

What I'd tell someone building something similar

• If an audit trail matters, derive state from events instead of storing it.
• Put the append-only rule in code, in one class, and test that it holds.
• Canonicalise before you hash, or two devices will disagree.
• Keep "someone said so" and "someone checked" as separate states.

Countback is MIT licensed and ships with full source and the test suite. If you want to look through it, it's here: https://store.mosfetti.com/product/countback/

— Mosfetti