Repository navigation
M2-12: Implement preflight orchestrator and fail-closed API #33
Description
Type: App/Core Integration
Priority: P0 / trust boundary
Initial status: Blocked
Owner: App/API
Depends on: M2-05, M2-06, M2-07, M2-10, M2-11
Blocks: M2-13, M3 integration
Writable: API orchestrator/service, API integration tests
唯一目标
在一个请求中完成 validate -> quote -> action -> simulate -> map -> align -> decide -> report，返回不依赖 Clear402 的 Mini-Demo 结果。
验收
[ ] total hard timeout 25s；quote timeout 8s
[ ] late work ignored/aborted where supported
[ ] LIVE 绝不静默切换 FIXTURE
[ ] unavailable evidence 尽力形成合法 failed evidence/STOP
[ ] schema/programming invariant error = structured 500，不伪装 STOP
[ ] contract error 不伪装安全判断
[ ] raw response size limited
[ ] logs redact RPC/sensitive request data
[ ] response 包含 report/presentation，无 credential
[ ] 无 clear402-profile import
[ ] FakeMossPort integration tests 离线
验证
pnpm vitest run apps/web/test/api
pnpm vitest run tests/integration
pnpm --filter @moss-mini-demo/web build
pnpm checkCodex 指令
按固定顺序编排 public ports/API。区分 domain STOP、acquisition failure 和 500 invariant；
不得 catch-all 后伪造 STOP，不得引入 Clear402。加入 timeout/cancellation/redaction tests。
Activity
1 remaining item
pillowtalk-Qy commentedon Aug 8, 2026
BUILDER_CLAIM / PLANNING_STARTED
Qy has claimed #33 as the sole active implementation issue.
main@42637ff3e152e44de3c88848e30f1d2c666d0863SINGLE_OPERATOR_SCOPE_REVIEWThis is single-operator execution; it does not claim independent review.
pillowtalk-Qy commentedon Aug 8, 2026
Work Plan - M2-12 preflight orchestrator and fail-closed API
Planning control
main@42637ff3e152e44de3c88848e30f1d2c666d0863.SINGLE_OPERATOR_SCOPE_REVIEW.Unique objective and fixed sequence
Implement one server request path that uses only public package contracts in this order:
validate -> quote/select -> action/capability -> simulate/map -> project -> align -> decide/report -> presentation.The handler remains the validation/HTTP boundary.
PreflightOrchestratoris the mode-aware service: explicit FIXTURE requests delegate only to the reviewed Fixture service; LIVE requests require an explicit server-side session resolver. Missing LIVE configuration returns structuredLIVE_UNAVAILABLE; it never invokes Fixture behavior. A supplied LIVE session contains a publicMossPort, catalog, candidate protocols, policy factory, provenance/network, and limitations. Monad/RPC source construction and live evidence remain #29 scope.Closed writable path list
Exactly these 13 paths are writable:
apps/web/package.json- add public adapter/core workspace dependencies and clean standalone build/typecheck ordering.pnpm-lock.yaml- update only theapps/webimporter for those workspace dependencies.apps/web/src/contracts/preflight.ts- add strict presentation success fields and a fixed timeout error code without weakening request/provenance contracts or byte limits.apps/web/src/server/preflight-service.ts- extend the stable service result only for a structured hard-timeout classification.apps/web/src/server/preflight-handler.ts- derive/validate presentation, reject sensitive response material, preserve byte limiting, and emit only fixed redacted log events.apps/web/src/server/preflight-orchestrator.ts- new mode-aware public-port orchestration, deadlines, cancellation and error classification.apps/web/src/server/preflight-projection.ts- new deterministic projection from public quote/capability/simulation evidence into legal report/alignment inputs.apps/web/app/api/preflight/route.ts- compose the orchestrator, explicit Fixture service and currently unconfigured LIVE resolver.apps/web/test/contracts.test.ts- strict presentation and timeout contract assertions.apps/web/test/routes.test.ts- response presentation, 4xx/5xx distinction, redaction, sensitive-output rejection and no-fallback assertions.apps/web/test/api/fake-moss.ts- offline publiccreateFakeMossPortbindings/configurations only.apps/web/test/api/preflight-orchestrator.test.ts- ordered happy/STOP/acquisition/timeout/cancellation/invariant tests.tests/integration/preflight-api.test.ts- minimal HTTP-to-report/presentation proof using the offline FakeMossPort; no M2-13: Pass non-UI end-to-end integration gate #34 gate report or request-fixture matrix.No wildcard path is authorized. Package-internal source, schemas, Decision Engine, workflows, docs, Clear402, vendor/Moss, secrets, wallets, signing and transaction submission are unchanged.
Trust and error boundaries
NOT_SELECTED, then a legal STOP when sufficient source input can be assembled.capability: FAILEDplussimulation: MISSING, then a legal STOP.simulation: FAILED, then a legal STOP.clear402-profileor any Clear402 runtime package.Evidence projection
RawSimulationEvidence, including block/Moss context, receipts, outcomes, warnings, coverage, ordering, state continuity and retained raw artifacts.FAILED | MISSING | UNPROVABLE; they are never filled with favorable guesses.evaluateAlignmentV0_1,assemblePreflightReportV0_1andderivePreflightPresentationV0_1are called only through@moss-mini-demo/preflight-corepublic exports.LIVE_SOURCE | LOCAL_FORK; Fake integration evidence uses explicit synthetic configuration and is never exposed as LIVE by the production route.Tests and verification
Focused tests must cover:
Required commands under Node 22.23.1 / pnpm 11.16.0:
pnpm vitest run apps/web/test/apipnpm vitest run tests/integrationpnpm vitest run apps/web/test/contracts.test.ts apps/web/test/fake-preflight-service.test.ts apps/web/test/routes.test.tspnpm --filter @moss-mini-demo/web buildpnpm checkThen inspect the exact 13-path diff, run zero-artifact and clean-worktree QA in a separate worktree, freeze the accepted head/tree, require exact-head
quality-gate, publish Implementation Report andSINGLE_OPERATOR_QA_PASS, markREADY_TO_MERGE, protected squash merge, and complete merged-main audit.Stop conditions
Stop for a Scope Amendment before touching any fourteenth path, changing a public package API, adding a non-workspace dependency, changing the request contract, weakening strict schemas/limits/provenance, introducing a live endpoint or credential, importing package-private source, requiring Clear402, or representing a programming/contract failure as STOP.
pillowtalk-Qy commentedon Aug 8, 2026
SINGLE_OPERATOR_SCOPE_REVIEW / PASS
This is Qy's same-controller review, not an independent reviewer claim.
Reviewed immutable planning object:
52247664942026-08-08T05:39:30Z153362a3f244c7b65d26654f31a3cc8cbf0bc54457b74aac9b2571f69e5c902emain@42637ff3e152e44de3c88848e30f1d2c666d0863Review result: PASS.
The objective, 13 writable paths, public package boundaries, service/route composition, no-fallback rule, evidence-gap behavior, domain STOP versus acquisition/timeout HTTP failure versus invariant 500, 25 s/8 s deadlines, cancellation/late-result handling, redacted logging, credential-shaped output rejection, response byte limit, offline FakeMossPort tests, #29/#34 non-goals, exact verification and amendment stop conditions are internally coherent and cover every #33 acceptance item.
Implementation is authorized only against this frozen Work Plan and exact baseline. Any fourteenth path or public package/API change requires a separately published Scope Amendment before editing.
pillowtalk-Qy commentedon Aug 8, 2026
SCOPE_AMENDMENT_1 / REQUESTED
The first exact-head clean CI run exposed one dependency-order path missing from Work Plan v1.
Evidence:
70fe41aa3437de2a6c35fed6564f7e43192f9528pnpm checkcould not resolve@moss-mini-demo/moss-adapterwhile typecheckingtests/integration/preflight-api.test.tsfrom a clean checkout; follow-on callback types became implicitany/unknownCause: root
typecheckbuilds report-schema, decision-engine and preflight-core before roottsc, but #33's new root integration test imports the Web orchestrator and therefore requires the public moss-adapter build output before that roottsc. Local focused/Web checks had already built moss-adapterdist, masking the missing clean dependency order.Requested fourteenth writable path:
14.
package.jsonThe only authorized edit is to insert:
pnpm --filter @moss-mini-demo/moss-adapter buildafter the decision-engine build and before preflight-core/root
tscin the roottypecheckscript. This matches the existing rootbuildandtest:package-importdependency order.No other root script, dependency, source, test, workflow, package, lockfile, API, report shape, Decision rule, presentation behavior, or path changes. The failed head/run are retained as evidence and are invalid for QA/merge. After authorization, implementation returns to IMPLEMENT, creates a new commit/head, removes generated package/Web build artifacts, runs frozen install and the complete local matrix, and requires a new exact-head CI before QA handoff.
SCOPE_AMENDMENT_1_SUBMITTED / AWAITING_SINGLE_OPERATOR_SCOPE_REVIEWpillowtalk-Qy commentedon Aug 8, 2026
SINGLE_OPERATOR_SCOPE_REVIEW / AMENDMENT_1 / PASS
This is a same-controller scope review by Qy, not an independent reviewer claim.
Reviewed amendment: #33 (comment)
774b833952bff59bf04aa3f43bd8c79e684cb09458d69f19c973fb099fcc95bf70fe41aa3437de2a6c35fed6564f7e43192f9528Findings:
@moss-mini-demo/moss-adapteris a new direct public dependency of the Web orchestrator and its package entry requires built declarations.package.jsonis the only additional path required.typecheck; no dependency, workflow, test, API or runtime code changes.No amendment finding remains open.
Qy authorizes the reviewed amendment as sole controller. The closed writable set is now the original 13 paths plus exactly:
14.
package.jsonWithin
package.json, only the roottypecheckdependency-order insertion described above is authorized. Any other edit requires another prior amendment.SINGLE_OPERATOR_SCOPE_REVIEW_PASS / SCOPE_AMENDMENT_1_AUTHORIZED / RETURN_TO_IMPLEMENTpillowtalk-Qy commentedon Aug 8, 2026
IMPLEMENTATION_FROZEN
Draft PR #78 is frozen at accepted head
c3c8d7570cf68c5a49950ff4e6ef5be1b3f0ccbd, tree0ee1852379381bfe35fb460a4ee4f484f9048896.pnpm check: passed, 33 files / 1,108 testsThe initial failing head/run is retained transparently in the report and is not accepted. The current head now leaves IMPLEMENT and enters clean same-operator QA. No independent reviewer is claimed.
IMPLEMENTATION_FROZEN / CLEAN_SINGLE_OPERATOR_QA_PENDINGpillowtalk-Qy commentedon Aug 8, 2026
SINGLE_OPERATOR_QA_HANDOFF
This is same-operator QA, not an independent reviewer claim.
42637ff3e152e44de3c88848e30f1d2c666d0863c3c8d7570cf68c5a49950ff4e6ef5be1b3f0ccbd0ee1852379381bfe35fb460a4ee4f484f9048896/Users/qy/Documents/moss-mini-demo-issue-33-qaQA starts with no dependencies, package dist or Web build artifacts. It will perform frozen install, inspect the exact amended 14-path diff, reproduce timeout/cancellation/late-result, STOP versus invariant 500, redaction/credential, no-fallback/no-Clear402 and offline public-port boundaries, run the exact Issue commands and a full no-dist gate, then recheck PR/protection state. Any head movement invalidates this handoff.
SINGLE_OPERATOR_QA_HANDOFF / CLEAN_QA_STARTpillowtalk-Qy commentedon Aug 8, 2026
SINGLE_OPERATOR_QA_PASS
This is same-operator QA from a separate clean detached worktree; no independent reviewer is claimed.
Accepted/frozen head
c3c8d7570cf68c5a49950ff4e6ef5be1b3f0ccbdpassed:pnpm check: 33 files / 1,108 tests plus all build/import/browser/production gatesThe unchanged 6 pre-existing Web audit advisories are recorded in the QA report and were not introduced by #33. Full QA record: #78 (comment)
PASS. Any head movement invalidates this result.
SINGLE_OPERATOR_QA_PASS / READY_FOR_MERGE_GATE_ASSESSMENTpillowtalk-Qy commentedon Aug 8, 2026
READY_TO_MERGE
PR #78 is ready at immutable head
c3c8d7570cf68c5a49950ff4e6ef5be1b3f0ccbd.Work Plan/Amendment, Implementation Report, separate clean
SINGLE_OPERATOR_QA_PASS, exact-head quality-gate run 31243778070/job 93068915956, 0 unresolved threads, mergeable/CLEAN status, exact 14-path scope, and protected-main/squash-only policy have all been rechecked with no head movement.Authorized next state: leave Draft and use protected squash merge only. No independent reviewer or pre-merge completion claim.
READY_TO_MERGE / PROTECTED_SQUASH_ONLYpillowtalk-Qy commentedon Aug 8, 2026
POST_MERGE_AUDIT - PASS
95c4aac532cdc2231054c431f3a175f9c223e1f5c3c8d7570cf68c5a49950ff4e6ef5be1b3f0ccbd42637ff3e152e44de3c88848e30f1d2c666d0863; single-parent linear history verified0ee1852379381bfe35fb460a4ee4f484f9048896All implementation, clean QA, merge and post-merge gates have passed.
POST_MERGE_AUDIT_PASS / ISSUE_COMPLETE