M2-01: Decide Web runtime and freeze module boundaries #22

Activity

1. pillowtalk-Qy

   added this to the M2 - Moss Integration & Mini-Demo Core milestone on Jul 29, 2026
2. pillowtalk-Qy

   added

   area:architectureArchitecture and module boundariesArchitecture and module boundaries

   type:researchResearch and validationResearch and validation

   status:needs-decisionRequires a maintainer decisionRequires a maintainer decision

   priority:P0Critical priorityCritical priority

   risk:trust-boundaryChanges a trust or evidence boundaryChanges a trust or evidence boundary

   on Jul 29, 2026
3. pillowtalk-Qy

   added a parent issue on Jul 29, 2026

   • M2-00: Hackathon delivery tracker and GitHub setup #21
4. pillowtalk-Qy

   marked this as blocking 4 issues on Jul 29, 2026

   • M2-02: Freeze scope, judge map and Gate contracts #23
   • M2-03: Pin reproducible Moss dependency #24
   • M2-04: Create moss-adapter package and public ports #25
   • M2-11: Create Web/API baseline and strict request contracts #32
5. pillowtalk-Qy commented on Jul 30, 2026

   

   pillowtalk-Qy

   on Jul 30, 2026

   Last edited by pillowtalk-Qy

   ContributorAuthor

   More actions

   Direction selected: Option A

   Maintainer direction date: 2026-07-30

   Selected runtime direction

   Use Next.js App Router + Node runtime + one deployable Node process as the proposed Web runtime.

   The production baseline is a normal Node server or container. Edge runtime is not the baseline. Core Preflight execution uses explicit Route Handlers; Server Actions do not own the core API.

   Frozen boundary direction

   report-schema      contracts only
   decision-engine    pure decision only
   moss-adapter       Moss/Monad I/O and raw mapping only
   preflight-core     alignment, decision input, report assembly only
   clear402-profile   optional report consumer only
   web/server         orchestration and HTTP/presentation boundary only
   

   Allowed internal dependency direction:

   decision-engine  -> report-schema
   moss-adapter     -> report-schema + pinned Moss/Monad dependencies
   preflight-core   -> report-schema + decision-engine
   clear402-profile -> report-schema
   web/server       -> moss-adapter + preflight-core
   web/client       -> report-schema type/schema boundary only
   

   The browser must not import moss-adapter, preflight-core, pinned Moss packages, RPC configuration, or server environment variables. The canonical report contract is owned by report-schema; preflight-core assembles and validates it; the Web route owns only request validation, HTTP status, and transport; UI code owns presentation only and cannot rewrite raw evidence.

   CLEAR402_ENABLED=false must keep the core report path independent. clear402-profile may consume a completed report only when enabled and cannot alter Core evidence or Decision semantics.

   Acceptance remains pending

   This comment selects the direction but does not mark M2-01 Accepted. Option A must first pass the required Node 22, pnpm 11, ESM, production build/start, server-only bundle, Moss import, disabled-Clear402, clean-start, and deployment compatibility spike.

   The spike may use the documented exact Moss upstream candidate as temporary compatibility evidence while M2-03 remains blocked. That candidate is not the final pinned integration dependency.

   If Moss cannot be imported and executed in the Next.js Node production build, server-only code enters the browser bundle, or the selected Node deployment cannot run the required Moss/RPC path without unsupported workarounds, the recorded fallback is Option B: React/Vite + Fastify, preferably two development processes and one Fastify production process serving the built frontend.

   M2-01 remains status:needs-decision until the spike evidence is linked and the Maintainer posts a separate Accepted or Rejected decision.
6. pillowtalk-Qy commented on Jul 30, 2026

   

   pillowtalk-Qy

   on Jul 30, 2026

   ContributorAuthor

   More actions

   Node 22 compatibility spike: Option A evidence

   Result: the selected Option A is technically supported: Next.js App Router with Node runtime can import the pinned Moss candidate in server-only routes and run as one Node process.

   Reproducible environment

   • Moss candidate: da9b566f9b607c28633b3790a44ae8d49522b269
   • Node: 22.23.1
   • pnpm: 11.10.0
   • Web dependency versions: Next 16.2.12, React/React DOM 19.2.3

   Evidence

   1. pnpm install and pnpm build completed for Moss plus the temporary Next workspace under Node 22.
   2. next build produced a production App Router build.
   3. A Node-runtime, server-only route imported @themoss/core, @themoss/simulator, @themoss/protocol-kuru, and @themoss/protocol-pancakeswap; production HTTP response reported all four imports as true.
   4. next start served the production build in one Node process.
   5. Static browser output contained no @themoss, moss, or clear402 references; Moss references appeared only in .next/server.
   6. With CLEAR402_ENABLED unset/false, the dedicated route returned 404; no Clear402 module was imported.

   Controlled deployment condition

   Next resolved sharp@0.34.5. Moss pnpm supply-chain policy initially blocked Sharp's install script, so the temporary spike only added allowBuilds.sharp: true after explicit review. A real app must either carry the reviewed, pinned allowlist entry or demonstrate that the chosen Next configuration removes the dependency. Do not bypass the policy.

   Boundary and residual risks

   • This is runtime/ESM/bundle evidence, not an implementation skeleton; the temporary workspace is not committed.
   • The final vendor/submodule and dependency-link strategy remains owned by the later integration work; this spike used Moss workspace links only.
   • Options B and C were not implemented as comparable spikes. The positive conclusion is that A meets its required compatibility proof, not that B/C are impossible.

   Decision request: record Maintainer acceptance of Option A, then freeze the stated module ownership in the architecture ADR before app implementation begins.
7. pillowtalk-Qy commented on Jul 31, 2026

   

   pillowtalk-Qy

   on Jul 31, 2026

   ContributorAuthor

   More actions

   Maintainer decision: Accepted

   Option A is accepted for the Mini-Demo architecture based on the Node 22 compatibility evidence above.

   The following is now frozen:

   • Next.js App Router using the Node runtime.
   • One deployable Node process for web and server orchestration.
   • Moss imports remain server-only and must not enter browser bundles.
   • CLEAR402_ENABLED=false remains a complete, independently working path.
   • Module ownership and dependency direction remain exactly as listed in this Issue.
   • API/report ownership stays outside the UI; the UI must not rewrite raw evidence.
   • Local Fork remains a SHOULD and does not block Live + Fixture delivery.

   The reviewed sharp build-script allowlist requirement must be handled explicitly in the implementation. Final Moss vendor/submodule linkage remains owned by the later integration work. Options B and C are not technically invalid, but are rejected for this Mini-Demo because Option A has now passed the required compatibility proof with less operational surface.

   This comment constitutes Maintainer acceptance for #22.
8. pillowtalk-Qy

   removed

   status:needs-decisionRequires a maintainer decisionRequires a maintainer decision

   on Jul 31, 2026
9. pillowtalk-Qy

   closed this as completedon Jul 31, 2026