Chore: Audit fixes

[jhweir]

Audit remediation: gates, correctness, coverage, conventions

Summary

A full-repo audit (AUDIT_2026-08-11.md) found the codebase in good shape on
discipline — near-zero TODO debt, documented catch blocks, a well-tested
schema-system — with the rot concentrated in three places: CI that gated on
nothing but the build, a test gap shaped exactly like the riskiest code,
and documentation two refactors behind reality. This branch works through
every tier of that audit, then through the bugs that surfaced while testing the
result.

Three things are worth a reviewer's attention up front. CI now actually
gates — lint, stylelint, typecheck, generated-file freshness and the full test
suite all block a merge, where previously only pnpm build could fail. Several
user-facing bugs were already broken on dev and are fixed here (the sign-in
screen had no Login button; the signal-type modal's mode picker was empty; the
create-space modal was unclosable from two routes). One regression was
self-inflicted and caught in manual testing — trimming "unconsumed" editor
exports broke the template toolbar, because the app shell consumes them via
dynamic import, which a static-import grep cannot see; the fix carries a comment
warning the next person.

The branch also closes the routing conventions discussion: view state now lives
in the URL, so a link reproduces what the sender sees — including an optional
template/theme suggestion — under a written four-tier convention.

Changes

CI and tooling gates

• .github/workflows/build.yaml — Lint and Test carried
  continue-on-error: true, justified by a backlog that no longer existed, so
  regressions landed silently on dev. Both now block, joined by stylelint, a
  typecheck step, and a generated-files diff (a PR that changes ai-context
  inputs without committing regenerated output now fails instead of drifting).
  Lockfile drift is caught with --frozen-lockfile before the AD4M override
  rewrite; the dependency cache stores the pnpm store rather than a
  one-level-deep node_modules glob that missed most of a 2–4-level workspace;
  a concurrency group stops duplicate pushes each running a full AD4M source
  build. WE steps run the pinned pnpm 10 developers use.
• eslint.config.js — 1,293 of the repo's 1,295 lint errors came from one
  machine-generated file that was never ignored; **/src/generated/** is now
  ignored in both eslint and prettier, and the two real errors are fixed. The
  prefer-ds-props rule pointed at packages/app-framework, renamed to
  app-shell long ago, so the two packages with the most hand-written DS usage
  were never linted by it.
• Stylelint was fully configured but ran only in editors; it now has a
  script and a CI step (zero findings).
• @we/cli — the build script's A && B || C shape ran the fallback and
  reported success when the real build failed.

Broken public surface (@we/primitives)

Four defects invisible from inside the monorepo because nothing here used the
broken paths: combobox.ts was a stale duplicate registering a second
we-select (hence the duplicate registry entry); the per-element build wrote to
a directory that didn't exist, so import '@we/primitives/button' typechecked
and failed at runtime; the package-local ESLint config scoped eslint-plugin-lit
to that same phantom path; and two packages declared a peer of
@we/primitives ^1.0.0 against a package versioned 0.1.0. The dist layout now
mirrors src/primitives.

Correctness bugs

Fixed on dev before this branch (found while testing):

• The sign-in screen had no Login button. A template-kit refactor collapsed
  the unlock row to a bare field() fragment, dropping the button, the
  Enter-to-submit handler and the error wiring — sessionStore.login had zero
  callers, so unlocking was impossible.
• The signal-type modal's mode list was empty — the same refactor rewrote
  the select without carrying its options across.
• The create-space modal was unclosable from the cards and globe routes:
  they embedded route-local copies gated on a local flag, while every close path
  inside the modal sets the shell flag. The copies are gone (which also
  removed the last template-default → template-shell imports, so that
  backwards dependency is now genuinely gone).
• Spaces list 500s — an unresolved $store reference in a where-clause
  serialized to an empty condition the executor rightly refuses;
  pruneUnresolvedWhere now drops conditions whose operands haven't resolved
  (keeping null, which is a value).
• Posts never loaded on reload — the stores bag exposes data bindings
  reactively, but query sites read $getModel once at setup, so a template
  mounted before the backend connected was stranded until a route change. All
  five query sites now read bindings inside their effect and self-heal.
• Location picker closed mid-drag when a map pan released outside it — a
  click's target is the common ancestor of mousedown and mouseup, so dismissal
  now keys off pointerdown.
• we-code blocks were white in dark mode — scale tokens invert per theme;
  the block now pins lightness and stays parametric on hue/saturation.
• Introduced by this branch and fixed: the template/theme toolbar disappeared
  when unconsumed editor exports were trimmed (the app shell consumes four of
  them by dynamic import).

Type safety and test coverage

The suite runs 1,660 tests, up from a baseline where six packages had no
test script at all.

• SerializedBlockNode was any — every function in the 841-line block
  serialization module flowed through it, while a different interface of the
  same name lived in block-solid. It is now a real type the editor-side
  interface extends, and the pipeline has its first tests, including
  reconcileBlocks' id-claiming, duplicate detection and orphan deletion (where
  a regression silently deletes user content), run against a fake model layer.
• The DS-prop invariant — DesignSystemProps (85 props) and
  designSystemKeys (five hand-maintained arrays) agreed only by luck; a
  drifted prop typechecks everywhere and is silently dropped by every layout
  component. Now a test.
• New coverage for the graph engine (spatial index, camera, pointer behaviours
  including the claim/broadcast rule, expanders), the token CSS generators
  (snapshot), @we/models' registry precedence rules, and the editor's pure
  helpers — extracted so tests import the real code, replacing a test that
  re-implemented the function it tested and could never fail.

Backend contract

createInMemoryBackendPorts stubbed its data plane, so the boot suite that
backendPorts.ts calls "the conformance test" could not exercise a single query
or mutation — and the package held a second, unrelated in-memory backend that
could. The bundle now carries the same binding surface as the AD4M adapter
(shared query adapter, mutations, $identities, a real ephemeral bus), with a
conformance suite pinning the surface key-by-key and a CRUD round-trip.

Theming

Completes the layering work started on feat/graph-engine-improvements:
themeToStyle/applyThemeVars and the ThemeOverrides vocabulary move to
@we/themes (schema-shared re-exports), ThemeParameters becomes a deprecated
alias of the one vocabulary, and semantic role tokens (--we-role-*) arrive
with parametric defaults so every existing and user-authored theme keeps
working. The dark preset makes the first designed use: raised surfaces lighten
rather than casting shadows — a relationship a uniform lightness inversion
cannot express.

Routing and view state (new convention)

docs/architecture/routing-and-view-state.md names four tiers and the question
that picks between them — "if I sent this URL to someone, should they see the
effect?"

• View state → the URL. routeStore gains reactive params and
  setParam(name, value, { push? }); $localState fields opt in with
  syncParam. Reads/writes stay $local/$setLocal; defaults drop their param
  so URLs stay clean; precedence is URL > persisted > initial. The renderer
  reaches the router through a $routeParams host binding, so hosts without one
  degrade to plain local state. Params survive leaving and returning a
  keep-alive route (they didn't, and a reload then believed the bare URL).
• Preferences → persist (device) and explicitly not the URL: a shared
  link must not impose display density on its recipient.
• Links can carry ?template= / ?theme= — applied silently when the
  recipient has them (clicking is the consent; idempotent), degraded with a
  one-time warning toast naming what's missing when they don't.
• Loading is a real state. Query accessors expose <name>Loaded, and
  cardList holds a skeleton until it flips — the empty state now only ever
  asserts "loaded and empty", never "hasn't answered yet".

Deduplication and cleanup

Column/Row/Grid/Card collapse onto one scaffold (which is also what made
disabledProps — accepted, documented, silently dropped — actually work); the
desktop apps' verbatim-duplicated platform plumbing collapses into
createDesktopPlatform + createLocalAd4mConnector; the account registry's two
implementations (504-line JS, 1,052-line Rust) now parse shared fixtures in
both suites, where before nothing proved a file written by one host round-trips
through the other. Removed after verifying zero references: netlify.toml and
its orphaned build script, three empty playground stubs, an incompletely deleted
module directory, 776 KB of unreachable images, the dead --we-depth-* token
category, and seven editor exports with no consumer.

Dependencies

@coasys/ad4m was declared 0.11.0 in eight manifests against a root override
installing 0.13.0-test-9; all now declare the pinned version. vitest collapses
from three majors to one (two packages ran 1.6.1 inside the same pnpm test),
TypeScript to one range, and internal @we/* deps use workspace:* everywhere.
The Apollo stack, router and plugin-opener were removed from the desktop apps
after verifying they are unimported.

Documentation

The app-shell README documented useAdamStore and a PlatformAdapter whose
methods don't exist; codebase-map.md — the "start here" doc — taught
adamStore vocabulary two refactors gone and never mentioned the graph system
or template kit; OPERATORS.md used adamStore in six examples; the seed file
had three mutually inconsistent descriptions. All corrected, with the seed
now sourced from types/seed.ts. New READMEs for backend-system,
module-system, templates, ai-context, models and the two contract
packages the repo's own rules required; app-shell finally has a
CONVENTIONS.md. Guides describing packages that no longer exist are archived
with banners naming their replacements. A PR template with a docs-sync
checklist addresses the root cause: the stale docs rotted because nothing
forced the update.

Known follow-ups

Deliberately out of scope, in rough priority order:

1. App-shell store test suites (SpaceStore 1.8k LOC, TemplateStore,
   ThemeStore, EditorStore — every write path) and backend-ad4m's write
   paths (sdnaModels, lifecycleAdapter, agentHelpers). Each is a
   multi-day effort; the completed in-memory ports now make them writable
   without an executor, which was the blocker.
2. Marvin's executor is out of date — the OR/AND/NOT where-clause
   combinators landed in ad4m on 2026-07-02, so any remote node built before
   that 500s on the spaces query. Local was rebuilt during this work; marvin
   needs cargo build --release --bin ad4m-executor. Worth considering a
   capability handshake so the adapter can compute OR client-side against an old
   node rather than failing.
3. Component adoption of the new role tokens — the vocabulary and the dark
   preset's first use are in; migrating components from scale positions to roles
   is the follow-on that makes designed dark themes possible.
4. "Copy link to this view" — the reading half of ?template=/?theme= is
   done; a share affordance that writes them is a small UI addition.
5. ~26 MB of skybox JPEGs committed under src/ (2k and 4k sets) — LFS or
   CDN changes contributor setup, so it deserves its own decision.
6. 99 already-merged branches are deletion candidates; main hasn't moved
   since 2025-11-29.
7. Preferences at agent scope — persist is device-local; a preference that
   should follow the agent across devices belongs in AgentSettings.

One decision for you: AUDIT_2026-08-11.md is currently tracked and carries
a per-item status section. Keep it as a record, or drop it now that its findings
are either fixed or listed above?

Test plan

Verified on this branch:

• pnpm lint — clean (was 1,295 errors)
• pnpm lint:css — clean (never ran outside editors before)
• pnpm typecheck — clean
• pnpm build — succeeds, and leaves the working tree clean (the seed-config
  generators' missing trailing newlines used to dirty three tauri files on
  every build)
• pnpm test — 1,660 passing, no failures
• pnpm validate:seed and pnpm validate:schemas (22 schemas) — clean
• cargo test for the tauri account registry, including the new shared
  fixtures both hosts parse
• Manual testing in we-electron and we-web against a remote node, which is
  where the sign-in, toolbar, create-space modal, signal-type, location
  picker, dark-mode code block, spaces-query, posts-reload and sort-persistence
  issues were each found and then re-verified after fixing

Not verified: the tauri desktop build end-to-end, and any behaviour requiring a
second peer (sync, neighbourhood join).

[netlify]

✅ Deploy Preview for coasys-we ready!

Name	Link
🔨 Latest commit	c4eda1f
🔍 Latest deploy log	https://app.netlify.com/projects/coasys-we/deploys/6a7c9269166d49000894b8a4
😎 Deploy Preview	https://deploy-preview-114--coasys-we.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.