Repository navigation
M2-11: Create Web/API baseline and strict request contracts #32
Description
Type: App Skeleton/API Contract
Priority: P0
Initial status: Blocked
Owner: App/API
Depends on: accepted M2-01
Blocks: M2-12, M3-01
Writable: approved app/server skeleton, app metadata and contract tests
唯一目标
建立 Node 22 可 production build/start 的应用、strict request/health contracts 和 Fake service boundary；不接真实 orchestration。
验收
[ ] framework exact versions locked
[ ] production build 和 start 成功
[ ] POST /api/preflight strict schema
[ ] mode 仅 LIVE/FIXTURE；scenario allowlist
[ ] body/response size limits
[ ] runId contract
[ ] GET /api/health 不泄露 secret/RPC URL
[ ] server-only Moss code 不进 browser bundle
[ ] Fake service 支持 UI 并与正式 contract 相同
[ ] 无 Clear402 behavior
[ ] 最小 preview/production start smoke 可重复，降低最后部署风险
验证
pnpm --filter @moss-mini-demo/web build
pnpm vitest run apps/web/test
pnpm check
pnpm start另开 Terminal：
curl -fsS http://127.0.0.1:3000/api/health | jqCodex 指令
只建框架、strict request/health contracts、fake boundary 和 production smoke。
不要接 Moss、Decision 或 Clear402，不把 server-only package 引入 client graph。
Activity
pillowtalk-Qy commentedon Jul 31, 2026
Dependency gate cleared - 2026-07-31
M2-01 / #22 is Maintainer Accepted and closed. Its compatibility spike established:
22.23.1and pnpm11.10.0;16.2.12with React/React DOM19.2.3;next start;CLEAR402_ENABLEDabsent/false returning an independent disabled path.#32 is released from Blocked to Ready.
Implementation boundaries:
sharp@0.34.5; any build-script allowlist entry must be explicit, reviewed, pinned, and documented. Do not bypass pnpm supply-chain policy.This record authorizes Ready status only; it does not approve a skeleton diff or production Gate.
pillowtalk-Qy commentedon Aug 5, 2026
M2_EXECUTION_SLOT_ASSIGNED
Builder:
pillowtalk-QyPlanning baseline:
origin/main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0Upstream execution-slot evidence:
Issue #32 is now the single active Builder slot and is moved to Project In Progress for planning.
Planned branch name after scope confirmation:
codex/issue-32-web-api-baselinePlanned isolated worktree after scope confirmation:
/Users/qy/Documents/moss-mini-demo-issue-32The first required evidence is a closed, path-specific Work Plan that freezes exact framework versions, writable paths, public/server boundaries, strict request and health contracts, Fake service contract, production build/start smoke, tests, and dependency changes.
In Progress starts planning only. It is not SCOPE_CONFIRMED, implementation authorization, QA PASS, Review, Merge Gate, or merge authorization. No branch, worktree, file modification, dependency update, commit, push, or PR may begin before Maintainer scope confirmation.
Issue #23 and newly released #25 remain Ready and unassigned. Other M2 Issues retain their existing blocked dependency gates.
pillowtalk-Qy commentedon Aug 5, 2026
Final Implementation Work Plan - Web/API Baseline and Strict Contracts - Awaiting Maintainer Scope Confirmation
1. Planning control
main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0.PLANNING_ONLY / AWAITING_MAINTAINER_SCOPE_CONFIRMATION.codex/issue-32-web-api-baseline./Users/qy/Documents/moss-mini-demo-issue-32.SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED.2. Goal and delivery boundary
Build a production-buildable and production-startable Next.js App Router skeleton on the accepted Node runtime, with:
POST /api/preflightrequest/response contracts;GET /api/healthresponse fields;This issue creates an application/API baseline, not an integrated demo. It does not implement Moss orchestration, Quote collection, Capability construction, simulation, Alignment, Decision Engine orchestration, report assembly, Monad/RPC access, Clear402 behavior, wallet behavior, signing, or transaction submission.
3. Frozen runtime and dependency set
Runtime and package manager:
The new
apps/web/package.jsondependency set is exact:{ "dependencies": { "@moss-mini-demo/report-schema": "workspace:*", "next": "16.2.12", "react": "19.2.3", "react-dom": "19.2.3", "server-only": "0.0.1", "sharp": "0.34.5", "zod": "4.4.3" }, "devDependencies": { "@types/node": "22.20.0", "@types/react": "19.2.18", "@types/react-dom": "19.2.4" } }No caret, tilde, tag, floating version, or additional dependency is authorized. The existing root TypeScript
7.0.2, Vitest4.1.10, and Biome2.5.5remain the only compiler/test/format toolchain.sharp@0.34.5is a reviewed direct runtime dependency because Next production image handling resolves it and its install script must not be silently blocked or broadly enabled.pnpm-workspace.yamlwill contain exactly:No
dangerouslyAllowAllBuilds, wildcard build permission, ignored-build bypass, or second build-script allowlist entry is authorized. The lockfile must resolve Sharp exactly to0.34.5and retain package integrity metadata. A clean-store install must prove the reviewed Sharp script succeeds, and a Node import must report Sharp0.34.5.4. Closed writable path list
Exactly these 30 repository paths are writable:
.gitignore- ignore Next build output only.package.json- add exact root web scripts/order; do not change existing dependency versions.pnpm-lock.yaml- generated frozen dependency graph and oneapps/webimporter only.pnpm-workspace.yaml- registerapps/*and allow only the pinned Sharp build script.tsconfig.json- keep root strict checking but delegateapps/webto its own Next config.README.md- minimal stable current-state correction for the Web/API baseline.SECURITY.md- minimal stable boundary correction; no weakening of exclusions.docs/real-vs-mock.md- identify the Fake service and Fixtures as synthetic/non-evidence.apps/web/package.jsonapps/web/tsconfig.jsonapps/web/next-env.d.tsapps/web/next.config.tsapps/web/app/globals.cssapps/web/app/layout.tsxapps/web/app/page.tsxapps/web/app/api/health/route.tsapps/web/app/api/preflight/route.tsapps/web/src/contracts/health.tsapps/web/src/contracts/preflight.tsapps/web/src/server/moss-build-info.tsapps/web/src/server/run-id.tsapps/web/src/server/http-json.tsapps/web/src/server/preflight-service.tsapps/web/src/server/fake-preflight-service.tsapps/web/src/server/preflight-handler.tsapps/web/test/contracts.test.tsapps/web/test/fake-preflight-service.test.tsapps/web/test/routes.test.tsapps/web/test/browser-bundle-leak.smoke.mjsapps/web/test/production-start.smoke.mjsThere is no wildcard writable path. No generated asset, snapshot, public directory, fixture, application package, or 31st path may be added. In particular, this issue must not modify
.github/workflows/quality-gate.yml,.gitmodules,vendor/moss, anypackages/report-schemaorpackages/decision-enginefile, any ADR,docs/architecture.md,docs/security-boundary.md, or STOP presentation rules.5. Workspace, build, and script contract
.gitignoreadds.next/. No source path is ignored.The root
tsconfig.jsoncontinues strict no-emit validation for existing root/package code and excludesapps/**;apps/web/tsconfig.jsonowns DOM, JSX, Next plugin, JSON-module, incremental, and generated Next type settings. The committednext-env.d.tsuses only stable Next type references and does not import a missing.nextartifact, so zero-artifact typecheck remains valid. Roottypecheckmust explicitly invoke the Web package typecheck so exclusion cannot become a coverage gap.Root scripts retain the existing gate and use these exact semantics:
The Web package scripts are fixed as:
The public report package is built first so
pnpm --filter @moss-mini-demo/web buildand Web typecheck work in a clean checkout with no pre-existingdist. No TypeScript path alias to package-private source, committeddist, hidden lifecycle script, or postinstall hook is permitted. Test code cannot invoke a build; the existing roottestscript keeps its explicit build prerequisite visible.pnpm-lock.yamlchanges are limited to:apps/webimporter;The root importer and the two existing package importers must not gain unrelated dependencies. The lockfile is generated by pnpm
11.16.0, never manually edited.6. Strict POST /api/preflight request contract
The route is a Next Route Handler with
runtime = "nodejs", no Edge runtime, no Server Action, and no caching.Constants:
The request is a strict discriminated union. Every object uses Zod
strictObject; unknown keys are rejected.LIVE request:
{ "contractVersion": "0.1", "mode": "LIVE", "intent": "<value accepted by public IntentSchema>" }FIXTURE request:
{ "contractVersion": "0.1", "mode": "FIXTURE", "scenario": "manual-review-success" }The exact fixture scenario allowlist is:
Rules:
intentparsed only through public@moss-mini-demo/report-schemaIntentSchema; it forbidsscenario.scenario; it forbids caller-suppliedintentbecause each reviewed Fixture owns its synthetic intent.runId, RPC URL, chain endpoint, credential, arbitrary fixture path, protocol-module name, or extra property.LIVE | FIXTURE.Content-Lengthabove 65,536 bytes is rejected before reading. Missing or false-smallContent-Lengthdoes not bypass the streaming byte counter.request.json()first.7. runId ownership and format
The server route generates one run identifier immediately on entry, before media-type/body/schema validation, so every success and structured error can be correlated.
The format is:
apps/web/src/server/run-id.tsis the only generator and uses Nodecrypto.randomUUID(). The route creates it once, passes it read-only to the service, and returns the same value. A client cannot choose or overwrite it. A runId is transport correlation metadata, notreportId, provenance, evidence, authorization, or a replay/security token.8. Strict POST response and HTTP contract
All response objects are strict, versioned, schema-validated before serialization, measured as UTF-8 bytes, and emitted with:
Success is a strict mode-correlated union.
LIVE success:
{ "contractVersion": "0.1", "ok": true, "runId": "run_<uuid-v4>", "mode": "LIVE", "report": "<public PreflightReportSchema value>" }LIVE success permits only report provenance
LIVE_SOURCE | LOCAL_FORK.FIXTURE success:
{ "contractVersion": "0.1", "ok": true, "runId": "run_<uuid-v4>", "mode": "FIXTURE", "scenario": "manual-review-success", "report": "<public PreflightReportSchema value with provenance FIXTURE>" }The returned scenario must equal the requested allowlisted scenario. The Fake service maps the three scenario identifiers only to the three existing read-only Fixture files:
Every Fixture is parsed through the public
PreflightReportSchemabefore return. The Fake service does not copy, modify, repair, strengthen, or re-decide a Fixture.Structured error:
{ "contractVersion": "0.1", "ok": false, "runId": "run_<uuid-v4>", "error": { "code": "INVALID_REQUEST", "message": "Request does not match the preflight contract." } }The error code/status mapping is frozen:
INVALID_JSONINVALID_REQUESTREQUEST_TOO_LARGEUNSUPPORTED_MEDIA_TYPELIVE_UNAVAILABLERESPONSE_TOO_LARGEINTERNAL_ERRORError messages are fixed, non-sensitive strings of at most 256 characters. They do not include payloads, Zod issues, stack traces, filesystem paths, RPC data, environment values, or secrets. An HTTP error never includes a report or Decision and never masquerades as
STOP. An oversized success is not truncated and is not returned as partial evidence.9. Fake service public contract
apps/web/src/server/preflight-service.tsis the stable server-only interface owned by Web/API:The file imports
server-only. Future #25-#31 packages do not modify this interface; Issue #33 (M2-12) later replaces/injects the orchestration implementation under its own Scope Gate.The baseline
FakePreflightService:LIVE_UNAVAILABLEfor LIVE and never falls back to FIXTURE;apps/web/src/server/preflight-handler.tsowns HTTP parsing, limits, service invocation, response validation/size checking, and error mapping. The route file is a thin Node-runtime composition root. Tests may inject a contract-compatible service and runId generator into the handler factory; production uses the Fake service and real runId generator.10. GET /api/health contract
GET /api/healthreturns HTTP 200,application/json; charset=utf-8,cache-control: no-store, and exactly:{ "contractVersion": "0.1", "status": "ok", "app": { "name": "moss-mini-demo", "version": "0.0.0", "runtime": "nodejs", "nodeVersion": "22.23.1" }, "moss": { "sourceMode": "INTEGRATION_FORK", "upstreamCommit": "1ae6b6322d51fae9104f047efb94e601050b967f", "integrationCommit": "1ae6b6322d51fae9104f047efb94e601050b967f", "officialRelease": false, "packages": { "@themoss/core": "0.1.0", "@themoss/simulator": "0.1.0", "@themoss/protocol-kuru": "0.1.0", "@themoss/protocol-pancakeswap": "0.1.0" } }, "network": { "configured": false, "id": null }, "clear402": { "enabled": false } }The health route validates this value through the strict public
HealthResponseSchema. It returns no timestamp, hostname, IP, RPC URL/host, environment-variable name/value, credential, token, key, wallet, address, filesystem path, error detail, request data, or live network probe.configured: falseis status metadata, not evidence that a network check ran.11. Server-only and browser boundary
The accepted dependency direction remains:
All files under
apps/web/src/serverbegin withimport "server-only". Both Route Handlers explicitly use Node runtime. No Client Component imports a server file,vendor/moss, Moss package, futuremoss-adapter, futurepreflight-core, server environment, or Clear402 module.The minimal page is a static, non-interactive application placeholder only. It does not present Fixture output as live evidence and does not claim that a runnable integrated demo exists.
After production build,
browser-bundle-leak.smoke.mjsrecursively scansapps/web/.next/static. It fails on these case-insensitive markers:The smoke also requires at least one static JS artifact and separately proves the server output contains the exact integration commit and
@themoss/coremarker. This makes the negative browser scan meaningful rather than passing because the server metadata was omitted.No
clear402-profiledependency or import is added. The health response's server-sideclear402.enabled=falseis status only and cannot alter Core behavior or evidence.12. Tests and required coverage
apps/web/test/contracts.test.tscovers:IntentSchemavalidation;apps/web/test/fake-preflight-service.test.tscovers:PreflightReportSchemaacceptance;provenance: FIXTUREand exact Fixture Decision;LIVE_UNAVAILABLEwith no Fixture fallback;apps/web/test/routes.test.tscovers:apps/web/test/browser-bundle-leak.smoke.mjsruns only after production build and applies the server/static assertions above.apps/web/test/production-start.smoke.mjs:.nextbuild;pnpm startpath withNEXT_TELEMETRY_DISABLED=1;GET /api/health;The smoke binds only
127.0.0.1; it performs no external HTTP, RPC, protocol, wallet, or chain call.13. Documentation corrections
The three authorized current-state documents receive minimal, stable facts:
provenance: FIXTURE;LIVE_UNAVAILABLEin this baseline and never silently fall back;MANUAL_REVIEWandSTOPmeanings are unchanged;docs/architecture.md,docs/security-boundary.md, ADRs, M1 evidence, and #23 Scope Cut documentation are not changed.14. Implementation sequence after authorization
origin/main. If it differs from93235e5c3ef531075c860beadc6ad2ce6b3dc8a0, stop, scan the new main, and request a refreshed Scope Gate before branching.22.23.1and pnpm11.16.0; audit the importer, exact versions, integrities, peer links, Sharp build permission, and unexpected package scripts.feat: add Web API baseline and strict contractswithCloses #32only.quality-gatesuccess, update the Implementation Report, add a Pre-PR QA handoff, freeze the head, and stop. Do not execute Review, Ready, Merge Gate, Merge, Issue/Project, permission, or protection operations.15. Verification commands
Run from an isolated checkout with no
node_modules,dist,.next, or untracked generated file. Keep the pinned Moss submodule unmodified; deinitialize it before the root Mini-Demo gate as established by #24.Manual production confirmation after build:
In a second terminal:
The response must match the frozen health object exactly and contain no RPC URL, host, secret, or credential.
Before handoff, run a pushed-branch fresh-clone proof with a new local pnpm store, repeat frozen install/Web build/tests/smokes/
pnpm check, and confirm the resulting worktree is clean apart from the reviewed 30-path commit diff.16. Acceptance and exit conditions
Implementation is acceptable only when all are true:
0.34.5;dist;next build, one-processnext start, loopback health smoke, browser leakage scan, and fullpnpm checkpass;tsconfig.json,apps/web/tsconfig.json,next-env.d.ts, package manifests, or lockfile during build;apps/web/.next/staticcontains no forbidden Moss/Clear402/server marker while server output contains the expected pinned metadata;quality-gatejob and succeeds;Stop without opening or updating a PR if:
22.23.1;A stop returns
SCOPE_CHANGES_REQUESTED; it does not authorize a workaround.17. Non-goals and trust boundaries
No implementation of:
moss-adapter,preflight-core, Quote/selection, Capability, simulation, Alignment, Decision orchestration, report generation, or presentation model;The Fake service and existing Fixtures are synthetic development tools. Production build/start, a health response, a strict API envelope, and green CI do not prove application correctness, protocol behavior, chain evidence, transaction safety, approval, authorization, execution, or permission to sign.
18. Risks and rollback
0.34.5is allowed to run a build script. Failure or extra build permission stops the task.FIXTURE; LIVE is explicitly unavailable and never downgraded.pnpm checkentry.apps/web, its workspace importer, scripts, Sharp allowlist, dependency graph, ignored build output, and the three current-state corrections together. No database, deployment, external service, secret, or user data exists to migrate or delete.19. Requested Maintainer Scope Gate
Please record one of:
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZEDfor the exact 30 paths, dependency set, package policy, request/response/health fields, sizes, runId, Fake service, server-only boundary, tests, and verification contract above; orSCOPE_CHANGES_REQUESTEDwith the exact path, field, value, or ownership change required.Until that record exists:
pillowtalk-Qy commentedon Aug 5, 2026
SCOPE_CHANGES_REQUESTED
Reviewed Work Plan: #32 (comment)
Planning baseline:
main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0Reviewed Work Plan body SHA-256:
6e2a8e412f3d889ec58acfd719be474f06cafb8365872c43c02d7e304a31cab6The 30-path boundary, strict/fail-closed API contracts, server-only ownership, production build/start smoke, browser-bundle leakage gate, and prohibition on real Moss, Decision orchestration, Clear402 behavior, RPC, wallet, signing, and chain evidence are otherwise coherent with #22 and #32.
One supply-chain scope blocker prevents implementation authorization:
allowBuilds: { sharp: true }while claiming that build permission is limited to exactsharp@0.34.5. Under pnpm 11, an unversionedsharp: truematcher approves build scripts for the registry package name without fixing the version. It therefore does not implement the stated minimum, version-pinned permission boundary. pnpm supports version-qualified package matchers: https://pnpm.io/settings/build#allowbuildsRequired Work Plan correction:
'sharp@0.34.5': true; do not authorize the unversionedsharpmatcher.allowBuilds.sharpso the version-qualified matcher is the normative value.sharp: "0.34.5", the frozen lockfile resolution and integrity metadata, and the prohibition on any second build-script permission.22.23.1/ pnpm11.16.0install and Sharp import proof, and verify that no unreviewed build is reported or auto-added topnpm-workspace.yaml.No implementation is authorized from the current Work Plan. Submit a revised, closed Work Plan for a new Maintainer Scope Gate. Until
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZEDis recorded, do not create the branch, worktree, commit, push, or PR.#32 remains Open, assigned to Qy, and Project In Progress for planning only. This is not QA, Review, READY_TO_MERGE, or merge authorization.
pillowtalk-Qy commentedon Aug 5, 2026
Revised Final Implementation Work Plan v2 - Version-Pinned Sharp Build Permission - Awaiting Maintainer Scope Confirmation
This complete revised plan supersedes, but does not edit or delete, the original Work Plan. It responds only to the Maintainer's SCOPE_CHANGES_REQUESTED; both earlier comments remain immutable audit records.
Unique revision delta
allowBuildskey is now the version-qualified matcher'sharp@0.34.5': true, replacing the unversionedsharp: trueproposal.pnpm-workspace.yaml.1. Planning control
main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0.PLANNING_ONLY / AWAITING_MAINTAINER_SCOPE_CONFIRMATION.codex/issue-32-web-api-baseline./Users/qy/Documents/moss-mini-demo-issue-32.SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED.2. Goal and delivery boundary
Build a production-buildable and production-startable Next.js App Router skeleton on the accepted Node runtime, with:
POST /api/preflightrequest/response contracts;GET /api/healthresponse fields;This issue creates an application/API baseline, not an integrated demo. It does not implement Moss orchestration, Quote collection, Capability construction, simulation, Alignment, Decision Engine orchestration, report assembly, Monad/RPC access, Clear402 behavior, wallet behavior, signing, or transaction submission.
3. Frozen runtime and dependency set
Runtime and package manager:
The new
apps/web/package.jsondependency set is exact:{ "dependencies": { "@moss-mini-demo/report-schema": "workspace:*", "next": "16.2.12", "react": "19.2.3", "react-dom": "19.2.3", "server-only": "0.0.1", "sharp": "0.34.5", "zod": "4.4.3" }, "devDependencies": { "@types/node": "22.20.0", "@types/react": "19.2.18", "@types/react-dom": "19.2.4" } }No caret, tilde, tag, floating version, or additional dependency is authorized. The existing root TypeScript
7.0.2, Vitest4.1.10, and Biome2.5.5remain the only compiler/test/format toolchain.sharp@0.34.5is a reviewed direct runtime dependency because Next production image handling resolves it and its install script must not be silently blocked or broadly enabled.pnpm-workspace.yamlwill contain exactly:The version-qualified matcher
'sharp@0.34.5'is the normative build-script permission and the only key permitted underallowBuilds. The unversioned matchersharp: true,dangerouslyAllowAllBuilds, wildcard build permission, ignored-build bypass, and any second build-script permission are forbidden. pnpm must not automatically add an unreviewed placeholder, package matcher, or approval entry topnpm-workspace.yaml; any such mutation stops implementation. The lockfile must resolve Sharp exactly to0.34.5and retain package integrity metadata. A clean-store install must prove the reviewed Sharp script succeeds,pnpm ignored-buildsmust report no unreviewed build requiring a new permission, and a Node import must report Sharp0.34.5.4. Closed writable path list
Exactly these 30 repository paths are writable:
.gitignore- ignore Next build output only.package.json- add exact root web scripts/order; do not change existing dependency versions.pnpm-lock.yaml- generated frozen dependency graph and oneapps/webimporter only.pnpm-workspace.yaml- registerapps/*and contain exactly one build-script permission: the version-qualified matcher'sharp@0.34.5': true; no unversioned matcher, second permission, or pnpm-added placeholder.tsconfig.json- keep root strict checking but delegateapps/webto its own Next config.README.md- minimal stable current-state correction for the Web/API baseline.SECURITY.md- minimal stable boundary correction; no weakening of exclusions.docs/real-vs-mock.md- identify the Fake service and Fixtures as synthetic/non-evidence.apps/web/package.jsonapps/web/tsconfig.jsonapps/web/next-env.d.tsapps/web/next.config.tsapps/web/app/globals.cssapps/web/app/layout.tsxapps/web/app/page.tsxapps/web/app/api/health/route.tsapps/web/app/api/preflight/route.tsapps/web/src/contracts/health.tsapps/web/src/contracts/preflight.tsapps/web/src/server/moss-build-info.tsapps/web/src/server/run-id.tsapps/web/src/server/http-json.tsapps/web/src/server/preflight-service.tsapps/web/src/server/fake-preflight-service.tsapps/web/src/server/preflight-handler.tsapps/web/test/contracts.test.tsapps/web/test/fake-preflight-service.test.tsapps/web/test/routes.test.tsapps/web/test/browser-bundle-leak.smoke.mjsapps/web/test/production-start.smoke.mjsThere is no wildcard writable path. No generated asset, snapshot, public directory, fixture, application package, or 31st path may be added. In particular, this issue must not modify
.github/workflows/quality-gate.yml,.gitmodules,vendor/moss, anypackages/report-schemaorpackages/decision-enginefile, any ADR,docs/architecture.md,docs/security-boundary.md, or STOP presentation rules.5. Workspace, build, and script contract
.gitignoreadds.next/. No source path is ignored.The root
tsconfig.jsoncontinues strict no-emit validation for existing root/package code and excludesapps/**;apps/web/tsconfig.jsonowns DOM, JSX, Next plugin, JSON-module, incremental, and generated Next type settings. The committednext-env.d.tsuses only stable Next type references and does not import a missing.nextartifact, so zero-artifact typecheck remains valid. Roottypecheckmust explicitly invoke the Web package typecheck so exclusion cannot become a coverage gap.Root scripts retain the existing gate and use these exact semantics:
The Web package scripts are fixed as:
The public report package is built first so
pnpm --filter @moss-mini-demo/web buildand Web typecheck work in a clean checkout with no pre-existingdist. No TypeScript path alias to package-private source, committeddist, hidden lifecycle script, or postinstall hook is permitted. Test code cannot invoke a build; the existing roottestscript keeps its explicit build prerequisite visible.pnpm-lock.yamlchanges are limited to:apps/webimporter;The root importer and the two existing package importers must not gain unrelated dependencies. The lockfile is generated by pnpm
11.16.0, never manually edited. Build-script permission remains solely inpnpm-workspace.yamlas'sharp@0.34.5': true; it must not be duplicated, generalized, or represented by a generated placeholder.6. Strict POST /api/preflight request contract
The route is a Next Route Handler with
runtime = "nodejs", no Edge runtime, no Server Action, and no caching.Constants:
The request is a strict discriminated union. Every object uses Zod
strictObject; unknown keys are rejected.LIVE request:
{ "contractVersion": "0.1", "mode": "LIVE", "intent": "<value accepted by public IntentSchema>" }FIXTURE request:
{ "contractVersion": "0.1", "mode": "FIXTURE", "scenario": "manual-review-success" }The exact fixture scenario allowlist is:
Rules:
intentparsed only through public@moss-mini-demo/report-schemaIntentSchema; it forbidsscenario.scenario; it forbids caller-suppliedintentbecause each reviewed Fixture owns its synthetic intent.runId, RPC URL, chain endpoint, credential, arbitrary fixture path, protocol-module name, or extra property.LIVE | FIXTURE.Content-Lengthabove 65,536 bytes is rejected before reading. Missing or false-smallContent-Lengthdoes not bypass the streaming byte counter.request.json()first.7. runId ownership and format
The server route generates one run identifier immediately on entry, before media-type/body/schema validation, so every success and structured error can be correlated.
The format is:
apps/web/src/server/run-id.tsis the only generator and uses Nodecrypto.randomUUID(). The route creates it once, passes it read-only to the service, and returns the same value. A client cannot choose or overwrite it. A runId is transport correlation metadata, notreportId, provenance, evidence, authorization, or a replay/security token.8. Strict POST response and HTTP contract
All response objects are strict, versioned, schema-validated before serialization, measured as UTF-8 bytes, and emitted with:
Success is a strict mode-correlated union.
LIVE success:
{ "contractVersion": "0.1", "ok": true, "runId": "run_<uuid-v4>", "mode": "LIVE", "report": "<public PreflightReportSchema value>" }LIVE success permits only report provenance
LIVE_SOURCE | LOCAL_FORK.FIXTURE success:
{ "contractVersion": "0.1", "ok": true, "runId": "run_<uuid-v4>", "mode": "FIXTURE", "scenario": "manual-review-success", "report": "<public PreflightReportSchema value with provenance FIXTURE>" }The returned scenario must equal the requested allowlisted scenario. The Fake service maps the three scenario identifiers only to the three existing read-only Fixture files:
Every Fixture is parsed through the public
PreflightReportSchemabefore return. The Fake service does not copy, modify, repair, strengthen, or re-decide a Fixture.Structured error:
{ "contractVersion": "0.1", "ok": false, "runId": "run_<uuid-v4>", "error": { "code": "INVALID_REQUEST", "message": "Request does not match the preflight contract." } }The error code/status mapping is frozen:
INVALID_JSONINVALID_REQUESTREQUEST_TOO_LARGEUNSUPPORTED_MEDIA_TYPELIVE_UNAVAILABLERESPONSE_TOO_LARGEINTERNAL_ERRORError messages are fixed, non-sensitive strings of at most 256 characters. They do not include payloads, Zod issues, stack traces, filesystem paths, RPC data, environment values, or secrets. An HTTP error never includes a report or Decision and never masquerades as
STOP. An oversized success is not truncated and is not returned as partial evidence.9. Fake service public contract
apps/web/src/server/preflight-service.tsis the stable server-only interface owned by Web/API:The file imports
server-only. Future #25-#31 packages do not modify this interface; Issue #33 (M2-12) later replaces/injects the orchestration implementation under its own Scope Gate.The baseline
FakePreflightService:LIVE_UNAVAILABLEfor LIVE and never falls back to FIXTURE;apps/web/src/server/preflight-handler.tsowns HTTP parsing, limits, service invocation, response validation/size checking, and error mapping. The route file is a thin Node-runtime composition root. Tests may inject a contract-compatible service and runId generator into the handler factory; production uses the Fake service and real runId generator.10. GET /api/health contract
GET /api/healthreturns HTTP 200,application/json; charset=utf-8,cache-control: no-store, and exactly:{ "contractVersion": "0.1", "status": "ok", "app": { "name": "moss-mini-demo", "version": "0.0.0", "runtime": "nodejs", "nodeVersion": "22.23.1" }, "moss": { "sourceMode": "INTEGRATION_FORK", "upstreamCommit": "1ae6b6322d51fae9104f047efb94e601050b967f", "integrationCommit": "1ae6b6322d51fae9104f047efb94e601050b967f", "officialRelease": false, "packages": { "@themoss/core": "0.1.0", "@themoss/simulator": "0.1.0", "@themoss/protocol-kuru": "0.1.0", "@themoss/protocol-pancakeswap": "0.1.0" } }, "network": { "configured": false, "id": null }, "clear402": { "enabled": false } }The health route validates this value through the strict public
HealthResponseSchema. It returns no timestamp, hostname, IP, RPC URL/host, environment-variable name/value, credential, token, key, wallet, address, filesystem path, error detail, request data, or live network probe.configured: falseis status metadata, not evidence that a network check ran.11. Server-only and browser boundary
The accepted dependency direction remains:
All files under
apps/web/src/serverbegin withimport "server-only". Both Route Handlers explicitly use Node runtime. No Client Component imports a server file,vendor/moss, Moss package, futuremoss-adapter, futurepreflight-core, server environment, or Clear402 module.The minimal page is a static, non-interactive application placeholder only. It does not present Fixture output as live evidence and does not claim that a runnable integrated demo exists.
After production build,
browser-bundle-leak.smoke.mjsrecursively scansapps/web/.next/static. It fails on these case-insensitive markers:The smoke also requires at least one static JS artifact and separately proves the server output contains the exact integration commit and
@themoss/coremarker. This makes the negative browser scan meaningful rather than passing because the server metadata was omitted.No
clear402-profiledependency or import is added. The health response's server-sideclear402.enabled=falseis status only and cannot alter Core behavior or evidence.12. Tests and required coverage
apps/web/test/contracts.test.tscovers:IntentSchemavalidation;apps/web/test/fake-preflight-service.test.tscovers:PreflightReportSchemaacceptance;provenance: FIXTUREand exact Fixture Decision;LIVE_UNAVAILABLEwith no Fixture fallback;apps/web/test/routes.test.tscovers:apps/web/test/browser-bundle-leak.smoke.mjsruns only after production build and applies the server/static assertions above.apps/web/test/production-start.smoke.mjs:.nextbuild;pnpm startpath withNEXT_TELEMETRY_DISABLED=1;GET /api/health;The smoke binds only
127.0.0.1; it performs no external HTTP, RPC, protocol, wallet, or chain call.13. Documentation corrections
The three authorized current-state documents receive minimal, stable facts:
provenance: FIXTURE;LIVE_UNAVAILABLEin this baseline and never silently fall back;MANUAL_REVIEWandSTOPmeanings are unchanged;docs/architecture.md,docs/security-boundary.md, ADRs, M1 evidence, and #23 Scope Cut documentation are not changed.14. Implementation sequence after authorization
origin/main. If it differs from93235e5c3ef531075c860beadc6ad2ce6b3dc8a0, stop, scan the new main, and request a refreshed Scope Gate before branching.allowBuildsentry to the exact matcher'sharp@0.34.5': true, then generate the lockfile only with Node22.23.1and pnpm11.16.0; audit the importer, exact versions, integrities, peer links, unexpected package scripts, andpnpm ignored-builds. Confirm pnpm did not add an unreviewed placeholder or second permission topnpm-workspace.yaml.feat: add Web API baseline and strict contractswithCloses #32only.quality-gatesuccess, update the Implementation Report, add a Pre-PR QA handoff, freeze the head, and stop. Do not execute Review, Ready, Merge Gate, Merge, Issue/Project, permission, or protection operations.15. Verification commands
Run from an isolated checkout with no
node_modules,dist,.next, or untracked generated file. Keep the pinned Moss submodule unmodified; deinitialize it before the root Mini-Demo gate as established by #24.Manual production confirmation after build:
In a second terminal:
The response must match the frozen health object exactly and contain no RPC URL, host, secret, or credential.
Before handoff, run a pushed-branch fresh-clone proof with a new local pnpm store, repeat frozen install/Web build/tests/smokes/
pnpm check, and confirm the resulting worktree is clean apart from the reviewed 30-path commit diff. In both isolated installs,pnpm config get allowBuilds --jsonmust resolve semantically to exactly{"sharp@0.34.5":true},pnpm ignored-buildsmust identify no unreviewed build requiring another permission, and the pre/post-install workspace-policy hashes must match so pnpm cannot silently add a placeholder.16. Acceptance and exit conditions
Implementation is acceptable only when all are true:
'sharp@0.34.5': true;0.34.5;dist;next build, one-processnext start, loopback health smoke, browser leakage scan, and fullpnpm checkpass;pnpm-workspace.yaml,tsconfig.json,apps/web/tsconfig.json,next-env.d.ts, package manifests, or lockfile during install/build;apps/web/.next/staticcontains no forbidden Moss/Clear402/server marker while server output contains the expected pinned metadata;quality-gatejob and succeeds;Stop without opening or updating a PR if:
22.23.1;A stop returns
SCOPE_CHANGES_REQUESTED; it does not authorize a workaround.17. Non-goals and trust boundaries
No implementation of:
moss-adapter,preflight-core, Quote/selection, Capability, simulation, Alignment, Decision orchestration, report generation, or presentation model;The Fake service and existing Fixtures are synthetic development tools. Production build/start, a health response, a strict API envelope, and green CI do not prove application correctness, protocol behavior, chain evidence, transaction safety, approval, authorization, execution, or permission to sign.
18. Risks and rollback
'sharp@0.34.5': truemay authorize a build script. An unversioned matcher, install/import failure, ignored unreviewed build, or extra permission stops the task.FIXTURE; LIVE is explicitly unavailable and never downgraded.pnpm checkentry.pnpm-workspace.yamlhash, structured config output, ignored-build report, and exact diff make any mutation a hard stop.apps/web, its workspace importer, scripts, the exact'sharp@0.34.5': truepermission, dependency graph, ignored build output, and the three current-state corrections together. No database, deployment, external service, secret, or user data exists to migrate or delete.19. Requested Maintainer Scope Gate
Please record one of:
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZEDfor the exact 30 paths, dependency set, sole version-qualified'sharp@0.34.5': truebuild permission, prohibition on any second permission or pnpm-added placeholder, request/response/health fields, sizes, runId, Fake service, server-only boundary, tests, and verification contract above; orSCOPE_CHANGES_REQUESTEDwith the exact path, field, value, or ownership change required.Until that record exists:
pillowtalk-Qy commentedon Aug 5, 2026
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED
Authorized Work Plan: #32 (comment)
Implementation baseline:
main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0Authorized Work Plan body SHA-256:
9b950740ed7008f89c4801a02c80624892ea38c7ae34e4aa58283c1d97b14561Maintainer Scope Gate result: PASS.
The revised Work Plan is authorized with these frozen boundaries:
allowBuildsentry:'sharp@0.34.5': true; the unversioned Sharp matcher, any second matcher, any pnpm-added placeholder, and any broader build-script permission are forbidden;The original Work Plan remains an unchanged audit record. The revised plan is a separate comment and the only authorized implementation source.
Builder Qy may now re-fetch and confirm the exact baseline, then create only the planned
codex/issue-32-web-api-baselinebranch and isolated worktree, implement the authorized scope, and open one Draft PR withCloses #32only. Ifmainchanges before branching, or implementation needs another path, dependency, build permission, public contract, workflow, or scope, stop and request a new Maintainer Scope Gate.This record authorizes implementation only. It is not Pre-PR QA, an independent review, READY_TO_MERGE, Merge Gate, or merge authorization. The implementation PR must remain Draft until its exact-head QA handoff and subsequent Maintainer review.
#32 remains Open, assigned to
pillowtalk-Qy, and Project In Progress. No downstream Issue is released by this authorization.feat: add Web API baseline and strict contracts (#71)
pillowtalk-Qy commentedon Aug 5, 2026
POST_MERGE_AUDIT
PR: #71
39ded5f45322d1fe79811c8908b067ad94f71d54main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a01e42babfa457ad20ac1efcecca227aceb4995c2b2026-08-05T10:57:54Z93235e5c3ef531075c860beadc6ad2ce6b3dc8a0(single parent)The merged-main check ran against exact head
1e42babfa457ad20ac1efcecca227aceb4995c2b. Issue #32 is Closed / Completed and its Project status is Done.The merge used head-matched squash merge. No auto-merge or admin bypass was used. No protection, permission, Tag, or Release setting was changed.