Skip to content

M2-07: Implement simulation and lossless evidence mapping #28

Closed

Description

@pillowtalk-Qy
Type: Moss Adapter Security/Evidence Feature
Priority: P0 / trust boundary
Initial status: Blocked
Owner: Moss Integration
Depends on: M2-06
Blocks: M2-08, M2-09, M2-12
Writable: simulation*, evidence-mapper*, errors*, raw fixtures/tests

唯一目标

把 exact Capability 交给 Moss Simulator,无损保存原始结果,并用可归因的 Mini-Demo 派生验证补齐 block、coverage、ordering 和 state continuity。

记录型 RPC 策略

1. pass-through wrapper 记录 simulator 的 eth_blockNumber 响应
2. 响应交给 simulator 前查询该 block pre-hash
3. 记录每个 debug_traceCall / eth_estimateGas block 参数
4. 要求一次 simulate 全部绑定同一 block
5. simulation 后查询同一 block post-hash
6. 要求 pre-hash === post-hash
7. 任何不可观察/不一致/hash 变化 => UNPROVABLE

证据分层

MossOriginalEvidence:
Capability, raw simulation, transactions, Changes, Receipts,
Outcomes, Warnings, gas

MiniDemoDerivedVerification:
derivedBy, ruleVersion, pinned mossCommit,
capabilityIntegrity, receiptCoverage, ordering, stateContinuity,
sourceReferences

验收

[ ] simulator 收到 exact action-return value
[ ] pre/post Capability digest 相等
[ ] transaction/change 顺序和 stable index 保留
[ ] Receipt tree/leaf、Outcome、Warning exact code/message、gas 保留
[ ] raw unknown fields 不丢失
[ ] positive derived claim 都含 adapter/ruleVersion/mossCommit
[ ] derived 不标成 Moss raw/original
[ ] exact block number/hash 可证明
[ ] RPC wrapper 有 request-equivalence tests
[ ] block 不一致/不可观察 => UNPROVABLE
[ ] 单交易 continuity = NOT_APPLICABLE
[ ] rollback/missing receipt/acquisition failure 显式
[ ] normalized display 不替代 raw
[ ] MCP reduced output 不作为完整证据源

测试矩阵

single success; Approval+Swap order; warning; rollback; missing receipt;
coverage fail; ordering fail; state interruption; inconsistent blocks;
hash lookup failure; unsupported Moss commit; provenance separation;
unknown raw field; determinism; input immutability

验证

pnpm vitest run packages/moss-adapter/test/evidence-mapper.test.ts
pnpm vitest run packages/moss-adapter/test/simulation.test.ts
pnpm --filter @moss-mini-demo/moss-adapter build
pnpm check

Codex 指令

实现 pass-through observation 和 lossless mapper。不得更改 Moss 控制流、RPC 请求、
Capability 或 raw response;无法证明时只能 UNPROVABLE。逐项标记 original/derived 来源。

Activity

  1. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    DEPENDENCY_GATE_CLEARED

    Issue #27 / M2-06 has been squash-merged through PR #74 into main@b3ba1411ce521d0d8526ae5805a162f5167f1e3c.

    The direct M2-06 dependency is satisfied. Issue #28 may move from Blocked to Ready for planning on this exact latest-main baseline.

    Ready means dependency-ready only. It is not SCOPE_CONFIRMED, implementation authorization, QA, READY_TO_MERGE, or merge authorization. A complete closed Work Plan and separate SINGLE_OPERATOR_SCOPE_REVIEW must pass before any implementation branch, worktree, repository change, commit, or PR is created.

  2. added and removed
    status:blockedBlocked by an unresolved dependency
    on Aug 7, 2026
  3. self-assigned this
    on Aug 7, 2026
  4. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    BUILDER_CLAIM / WORK_PLAN_REQUIRED

    Qy claims the single active implementation-planning slot for Issue #28.

    • exact planning base: origin/main@b3ba1411ce521d0d8526ae5805a162f5167f1e3c
    • planned branch after authorization: codex/issue-28-simulation-evidence
    • planned isolated worktree after authorization: /Users/qy/Documents/Clear402 x Moss Mini-Demo/worktrees/issue-28
    • writable paths: not yet authorized; the Work Plan must propose an exact closed set
    • current repository implementation WIP: planning only, no branch/worktree/code PR exists
    • first required evidence: exact-main source audit plus a complete closed Work Plan

    The Project In Progress state records planning ownership only. It does not authorize branch/worktree creation, file changes, dependencies, commits, a PR, Ready state, Merge Gate, or merge. The Work Plan must receive SINGLE_OPERATOR_SCOPE_REVIEW / PASS and a separate SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED record before implementation starts.

    The worktree path is inside the active permitted workspace because macOS denies this controller access to the historical sibling path /Users/qy/Documents/moss-mini-demo-issue-28; isolation semantics remain one dedicated worktree for one Issue.

  5. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    Final Implementation Work Plan v1 - M2-07 Simulation and Lossless Evidence Mapping

    Authority and baseline

    This remains planning only. No implementation branch, worktree, edit, dependency change, commit, or PR exists.

    Exact source facts

    1. MossPort is the fixed five-method application boundary and already has simulate(capability).
    2. M2-06: Implement capability construction, amount conversion and integrity #27 preserves the exact action-return object as simulatorInput and rejects hostile mutation before delegation.
    3. Pinned Moss calls eth_blockNumber once, passes that block as parameter 1 to every debug_traceCall and eth_estimateGas, verifies Receipt coverage before exposing a Receipt, and merges each prior state diff before the next transaction.
    4. Pinned Moss returns ordered results[] with transaction, optional Changes, optional Receipt/Outcome, exact Warnings, string-or-null gas, and optional halted.
    5. It does not expose block number/hash in SimulateOutcome; adapter-owned pass-through RPC observation is required.
    6. M2-10: Assemble DecisionInput, PreflightReport and presentation model #31 owns report assembly. MCP reduced output is not a complete source for M2-07: Implement simulation and lossless evidence mapping #28.

    A baseline, pin, or audited Moss control-flow change invalidates the positive rules and requires a new Scope Gate.

    Goal

    Pass the exact Capability to Moss, retain raw and immutable simulation evidence without dropping unknown JSON fields or order, and separately attribute Mini-Demo verification for Capability integrity, exact block, Receipt coverage, ordering, and state continuity. This is not safety, execution, signing, Decision, STOP, or live evidence.

    Closed writable paths

    Exactly these 13 paths are requested:

    1. packages/moss-adapter/src/types.ts
    2. packages/moss-adapter/src/source-bindings.ts
    3. packages/moss-adapter/src/simulation.ts
    4. packages/moss-adapter/src/evidence-mapper.ts
    5. packages/moss-adapter/src/index.ts
    6. packages/moss-adapter/test/fixtures/simulation.ts
    7. packages/moss-adapter/test/simulation.test.ts
    8. packages/moss-adapter/test/evidence-mapper.test.ts
    9. packages/moss-adapter/test/capability.test.ts
    10. packages/moss-adapter/test/contracts.test.ts
    11. packages/moss-adapter/test/production.test.ts
    12. packages/moss-adapter/test/fake.test.ts
    13. packages/moss-adapter/test/public-entry.smoke.mjs

    No wildcard is implied. A fourteenth path requires a prior Scope Amendment. Root metadata, lockfile, report-schema, decision-engine, Web/API, docs, workflows, vendor/moss, and .gitmodules are read-only.

    Dependencies and public boundary

    No dependency, package metadata, lockfile, workspace, lifecycle permission, submodule, or Moss pin change is authorized.

    MossPort remains exactly five methods; simulate(capability: RawCapability) is unchanged.

    The low-level MossSourceBindings adds one raw simulationRpcClient dependency and a second rpcClient argument on its simulator binding. The binding must build/use its Moss runtime with the adapter-supplied client and must not bypass it.

    RawSimulationEvidence becomes the full M2-07 contract. Supporting evidence/RPC types are type-only exports. There is no new runtime export, package subpath, Schema, or public mapper helper. The package-root runtime export set and server-only boundary remain exact.

    Recording RPC contract

    One isolated recording session is created per MossPort.simulate call.

    1. Each simulator request object is forwarded once by exact identity to the raw client, with no clone, normalization, mutation, retry, suppression, parameter replacement, or reordering.
    2. Record the exact eth_blockNumber response.
    3. Before returning it to Moss, query the raw client directly with eth_getBlockByNumber(block, false) and retain the pre-hash.
    4. Record parameter 1 of every debug_traceCall and eth_estimateGas.
    5. After simulation settles, query the same block for post-hash.
    6. PROVEN requires exactly one canonical block response, every observed simulation call bound to it, valid pre/post hashes, strict hash equality, and a complete observation lifecycle.
    7. Missing/malformed observations, multiple block responses, inconsistent parameters, lookup failure, or hash change become stable UNPROVABLE, never nearest/latest block evidence.
    8. Observation failure does not alter Moss control flow. Simulator/RPC rejection remains secret-safe SIMULATION_FAILED / simulate.
    9. Internal hash queries are adapter observation traffic, not Moss simulator requests.

    Request-equivalence tests cover request identity, count, order, method, params, response identity, and rejection behavior.

    Raw ownership and evidence layers

    MossOriginalEvidenceV0_1 retains:

    • exact raw Capability and exact raw SimulateOutcome source objects;
    • independent deeply frozen retained snapshots;
    • stable transaction and Change indices with original order;
    • Receipt trees/leaves and structured Outcomes;
    • exact Warning objects/code/message;
    • string-or-null gas without Number conversion;
    • rollback and halted;
    • every unknown valid JSON field in the full simulation snapshot.

    The adapter does not freeze, modify, decorate, normalize, or replace Moss-owned objects. Only adapter-owned snapshots/wrappers are frozen. Shared Change/Receipt references are permitted and preserved by structured clone. Cycles, Proxies, accessors, sparse arrays, Symbols, unsupported prototypes, non-finite values, lone surrogates, and non-JSON fields fail closed.

    MiniDemoDerivedVerificationV0_1 is separately labeled with derivedBy: "@moss-mini-demo/moss-adapter", ruleVersion: "0.1", exact mossCommit, block proof, four verification states, and deterministic source references. No derived field is called Moss original/raw, and no display model replaces raw evidence.

    Verification rules

    Capability integrity:

    Receipt coverage:

    • under the exact pin, Receipt presence means Moss creation and verifyReceiptCoverage passed;
    • all expected results with Receipts => PROVEN;
    • CHANGE_COVERAGE_MISMATCH, missing required Receipt, or incomplete result set => FAILED;
    • otherwise insufficient material => UNPROVABLE.

    Ordering:

    • pinned ordered Changes plus successful Receipt identity/order coverage => PROVEN;
    • CHANGE_ORDER_UNAVAILABLE, incomplete result set, or demonstrable order failure => FAILED;
    • missing proof without explicit order failure => UNPROVABLE.

    State continuity:

    • exactly one expected transaction => NOT_APPLICABLE;
    • complete multi-transaction result, no halt, no STATE_CHAIN_FAILED => PROVEN;
    • halt, incomplete multi-result, or STATE_CHAIN_FAILED => FAILED;
    • unobservable expected transaction structure => UNPROVABLE.

    Rules never parse Warning prose, invent evidence, or strengthen unknown states.

    Validation and failure boundary

    Caller/source objects are untrusted. The merged #27 descriptor-closed validation is reused. Before delegation the capability, raw RPC client, simulator binding, and complete Moss build identity must validate. After delegation protocol/method and full SimulateOutcome graph must validate.

    Malformed source output => secret-safe SOURCE_CONTRACT_VIOLATION / simulate.
    Source/RPC rejection => secret-safe SIMULATION_FAILED / simulate.
    No cause, URL, headers, query, calldata, account, params, raw message, or secret is exposed.
    An unsupported Moss commit cannot reuse the mapping rules or produce a positive claim.

    Test matrix

    simulation.test.ts:

    • exact action-return identity; pre/post digest; simulator mutation;
    • pass-through request/response/rejection equivalence;
    • single success; Approval + Swap one-block calls;
    • inconsistent trace/estimate block;
    • absent/multiple block response;
    • pre/post lookup failure; hash change;
    • session isolation;
    • acquisition failure sanitization;
    • no caller/request mutation.

    evidence-mapper.test.ts:

    • single success; Approval + Swap order;
    • Receipt tree/leaves; Outcomes; exact Warning;
    • rollback/halt; missing Receipt; coverage failure; ordering failure; state interruption;
    • single transaction NOT_APPLICABLE;
    • unsupported commit;
    • provenance separation; unknown field retention;
    • large gas string;
    • shared Change/Receipt references;
    • determinism, input immutability, independent deep freeze;
    • malformed, cyclic, accessor, Proxy, sparse, Symbol, non-finite, and lone-surrogate rejection.

    Existing tests change only to supply the new low-level RPC dependency/signature and retain all five-method, exact-identity, hostile-input, Fake/production parity, type-only, runtime-export, and server-only assertions. All fixtures are explicit synthetic offline data, not Moss/Monad/RPC/live evidence.

    Verification

    Node 22.23.1 and pnpm 11.16.0:

    pnpm install --frozen-lockfile
    pnpm --filter @moss-mini-demo/report-schema build
    pnpm exec vitest run packages/moss-adapter/test/simulation.test.ts
    pnpm exec vitest run packages/moss-adapter/test/evidence-mapper.test.ts
    pnpm exec vitest run packages/moss-adapter/test
    pnpm --filter @moss-mini-demo/moss-adapter build
    pnpm --filter @moss-mini-demo/moss-adapter typecheck
    pnpm test:package-import
    pnpm check
    pnpm test:web:bundle
    pnpm test:web:production
    git diff --check origin/main...HEAD
    git diff --name-only origin/main...HEAD
    git submodule status

    Isolation and non-goals

    No Monad live smoke (#29), alignment (#30), report/DecisionInput/presentation (#31), orchestrator/API (#33), Decision/STOP/MANUAL_REVIEW policy, UI, deployment, credential, endpoint, wallet, signing, transaction submission, Moss modification, Schema change, CI change, or real-evidence claim.

    Stop conditions

    Stop for a prior Scope Amendment if the baseline/pin differs; a fourteenth path, dependency, runtime export, package subpath, vendor/Schema/workflow change is needed; MossPort shape must change; exact request/response pass-through cannot hold; a positive rule needs prose parsing or assumption; complete raw evidence cannot be retained; or production secrets/live data/report/UI behavior is requested.

    Sequence

    After authorization: revalidate baseline; create one branch/worktree; add focused failing fixtures/tests; implement recorder; implement mapper; wire source binding; update compatibility tests; run focused/full matrices; audit exact paths; commit/push/Draft PR; wait exact-head CI; publish Implementation Report/QA Handoff; freeze; perform clean SINGLE_OPERATOR_QA.

    This requests a separate SINGLE_OPERATOR_SCOPE_REVIEW and then SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED for only this exact object.

    WORK_PLAN_V1_SUBMITTED / AWAITING_SCOPE_REVIEW

  6. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    SINGLE_OPERATOR_SCOPE_REVIEW / PASS

    This is a same-controller scope review by Qy. It is not an independent second-person review.

    Reviewed immutable planning object:

    • Work Plan v1: M2-07: Implement simulation and lossless evidence mapping #28 (comment)
    • comment ID: 5211843751
    • comment updated_at: 2026-08-07T03:19:04Z
    • exact body bytes: 11223 UTF-8 characters as returned by GitHub
    • body SHA-256 with no added newline: recorded in the following authorization object after a fresh API read
    • exact main: b3ba1411ce521d0d8526ae5805a162f5167f1e3c
    • exact Moss gitlink/source: 1ae6b6322d51fae9104f047efb94e601050b967f

    Scope review checks:

    • PASS: dependency M2-06: Implement capability construction, amount conversion and integrity #27 is merged, audited, and M2-07: Implement simulation and lossless evidence mapping #28 is truly Ready.
    • PASS: one goal is defined and does not absorb M2-08: Add Monad live smoke and provenance record #29, M2-09: Implement deterministic preflight alignment #30, M2-10: Assemble DecisionInput, PreflightReport and presentation model #31, M2-12: Implement preflight orchestrator and fail-closed API #33, or Gate work.
    • PASS: all 13 writable paths are exact and closed; no wildcard, metadata, lockfile, vendor, Schema, Web, docs, or workflow path is hidden.
    • PASS: zero dependency and zero runtime-export changes are explicit.
    • PASS: the five-method MossPort API remains unchanged.
    • PASS: the low-level MossSourceBindings RPC injection is necessary and sufficient for adapter-owned pass-through observation; trusting a caller-supplied observation record is not permitted.
    • PASS: the plan proves exact request/response identity while separating adapter hash queries from Moss simulator requests.
    • PASS: hash lookup failure and inconsistent/unobservable block context remain UNPROVABLE without altering Moss control flow.
    • PASS: source acquisition failure remains the existing structured, secret-safe SIMULATION_FAILED boundary.
    • PASS: raw objects are not frozen or modified; independent snapshots and derived wrappers are adapter-owned.
    • PASS: unknown JSON fields and stable order are retained.
    • PASS: shared Change references between Moss changes and Receipt leaves are explicitly allowed; cycles and descriptor-hostile graphs are not.
    • PASS: positive coverage/order/continuity rules are tied only to the exact audited Moss commit.
    • PASS: unsupported commit cannot inherit positive rules.
    • PASS: one-transaction continuity is NOT_APPLICABLE, not fabricated proof.
    • PASS: rollback, warning, missing Receipt, coverage/order failure, state interruption, acquisition failure, and block-proof failure are distinct.
    • PASS: original versus derived provenance is structural and cannot be relabeled by a display model.
    • PASS: focused tests cover every Issue matrix item plus determinism, immutability, hostile inputs, session isolation, and secret-safe failures.
    • PASS: existing exact-identity, production/Fake parity, public entry, and server-only contracts remain covered.
    • PASS: verification includes focused, package, full repository, package-import, Web bundle/production smoke, path, submodule, and diff gates.
    • PASS: stop conditions require a prior Scope Amendment for every unplanned path, dependency, export, pin, API, or trust-boundary change.

    No scope finding remains open.

    SINGLE_OPERATOR_SCOPE_REVIEW_PASS / READY_FOR_SCOPE_CONFIRMATION

  7. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED

    Frozen authorization object:

    Qy, acting as the sole project controller, confirms this implementation scope after the explicit same-controller review. No independent reviewer is claimed.

    Authorized writable paths, exactly:

    1. packages/moss-adapter/src/types.ts
    2. packages/moss-adapter/src/source-bindings.ts
    3. packages/moss-adapter/src/simulation.ts
    4. packages/moss-adapter/src/evidence-mapper.ts
    5. packages/moss-adapter/src/index.ts
    6. packages/moss-adapter/test/fixtures/simulation.ts
    7. packages/moss-adapter/test/simulation.test.ts
    8. packages/moss-adapter/test/evidence-mapper.test.ts
    9. packages/moss-adapter/test/capability.test.ts
    10. packages/moss-adapter/test/contracts.test.ts
    11. packages/moss-adapter/test/production.test.ts
    12. packages/moss-adapter/test/fake.test.ts
    13. packages/moss-adapter/test/public-entry.smoke.mjs

    Frozen constraints:

    Authorized implementation objects:

    • branch: codex/issue-28-simulation-evidence
    • isolated worktree: /Users/qy/Documents/Clear402 x Moss Mini-Demo/worktrees/issue-28

    Any baseline, pin, path, dependency, export, API, evidence rule, or downstream-boundary change invalidates this authorization until a prior Scope Amendment passes the same review flow.

    This authorizes implementation only. It is not QA PASS, review approval, READY_TO_MERGE, Merge Gate, merge permission, live evidence, or release evidence.

    SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED

  8. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    SCOPE_AMENDMENT_1 / REQUESTED

    Work Plan v1 remains unchanged except for one additional test path.

    Requested fourteenth writable path:

    1. packages/moss-adapter/test/errors.test.ts

    Reason discovered by the first full adapter regression:

    • the existing file owns a hostile secret-bearing simulation-result Proxy regression;
    • M2-07 changes the simulation source boundary from an unmapped placeholder to recording plus full mapping;
    • that test must supply the authorized raw simulation RPC dependency and a valid raw SimulateOutcome before asserting that a hostile result is still converted to secret-safe SOURCE_CONTRACT_VIOLATION / simulate;
    • omitting the file would leave an existing trust-boundary regression broken or unverified.

    Authorized change within this file is limited to its shared synthetic binding/fixture and the simulation source-error case. No error code, error source, production behavior, assertion strength, dependency, runtime export, package metadata, or other path changes.

    All original baseline, Moss pin, 13 paths, contracts, tests, non-goals, stop conditions, and downstream isolation remain frozen.

    SCOPE_AMENDMENT_1_SUBMITTED / AWAITING_SINGLE_OPERATOR_SCOPE_REVIEW

  9. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    SINGLE_OPERATOR_SCOPE_REVIEW / AMENDMENT_1 / PASS

    This is a same-controller review by Qy, not an independent review.

    Reviewed amendment: #28 (comment)

    • exact body SHA-256, no added newline: 6f0ccc193af47f51864ae2c6970aa9e0d0f6bd92977d01b553fe9fbb73f8718c
    • PASS: the new path is one existing trust-boundary test file only.
    • PASS: the need was reproduced by the full adapter regression.
    • PASS: the file already owns the exact hostile simulation source-error behavior.
    • PASS: changes are limited to test setup and preserving the existing strong sanitization assertion.
    • PASS: no source, dependency, API, export, pin, runtime behavior, or downstream scope is added.
    • PASS: the amended closed path set is exactly 14 files.
    • PASS: all original Work Plan constraints remain intact.

    No amendment finding remains open.

    SINGLE_OPERATOR_SCOPE_REVIEW_PASS / AMENDMENT_1_READY_FOR_AUTHORIZATION

  10. pillowtalk-Qy commented on Aug 7, 2026

    @pillowtalk-Qy
    ContributorAuthor

    SCOPE_AMENDMENT_1 / IMPLEMENTATION_AUTHORIZED

    Qy authorizes the reviewed amendment as the sole controller. No independent reviewer is claimed.

    The closed writable set is now the original 13 paths plus exactly:

    1. packages/moss-adapter/test/errors.test.ts

    Within that file only the shared synthetic simulation setup and existing hostile simulation source-error regression may change. Assertion strength must not decrease.

    Everything else in Work Plan v1 and the original authorization remains frozen. This is implementation-scope authorization only, not QA or merge authorization.

    SCOPE_AMENDMENT_1_AUTHORIZED

  11. pillowtalk-Qy commented on Aug 8, 2026

    @pillowtalk-Qy
    ContributorAuthor

    Implementation frozen / QA started

    Draft PR #75 is open at frozen head 479e3a3291a278eafdc80ca399eca3315c11365f.

    A new detached clean worktree will now test and review that exact immutable commit. This is SINGLE_OPERATOR_QA; no independent reviewer is claimed. The PR remains Draft and is not merge-ready yet.

    IMPLEMENTATION_FROZEN / CLEAN_SINGLE_OPERATOR_QA_IN_PROGRESS

  12. pillowtalk-Qy commented on Aug 8, 2026

    @pillowtalk-Qy
    ContributorAuthor

    POST_MERGE_AUDIT / COMPLETE

    PR #75 merged under branch protection as e468c6c035c3c35e12a0c1d7795d76d5306045eb.

    The merge tree equals the clean-QA reviewed tree. No post-merge finding remains open. This closes M2-07 and permits a fresh dependency-gate evaluation for #29, #30, and #33; it does not by itself authorize those implementations.

    POST_MERGE_AUDIT_PASS / M2_07_DONE

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions