Repository navigation
M2-04: Create moss-adapter package and public ports #25
Description
Type: Architecture Skeleton
Priority: P0 / trust boundary
Initial status: Blocked
Owner: Moss Integration
Depends on: M2-01, M2-03
Blocks: M2-05, M2-06, M2-07
Writable: packages/moss-adapter/**, required workspace metadata
唯一目标
建立 @moss-mini-demo/moss-adapter 唯一 public entry、ports、errors、build info 和测试 fake；不实现选择或 Decision。
固定 public port
interface MossPort {
describe(protocolId: string, method: string): Promise<RawOperationContract>;
quote(protocolId: string, input: QuoteInput): Promise<RawQuote>;
action(protocolId: string, input: ActionInput): Promise<RawCapabilityEvidence>;
simulate(capability: RawCapability): Promise<RawSimulationEvidence>;
buildInfo(): MossBuildInfo;
}固定 evidence 层
RawOperationContract:
exact loaded Stub + protocol/method + loaded riskLabels + source
RawCapabilityEvidence:
operation contract + exact raw Capability + independent snapshot + integrity
RawSimulationEvidence:
exact raw simulation + source context + Moss original + Mini-Demo derived
验收
[ ] 只有一个 documented public entry
[ ] production/FakeMossPort 共用同一 port
[ ] describe 保留 exact Stub/risk labels
[ ] 不把 risk label 冒充 CapabilityNode 字段
[ ] errors structured/secret-safe
[ ] chainId 143 显式校验
[ ] raw 与 normalized 分层
[ ] Moss original 与 Mini-Demo derived 分层
[ ] 无 Decision/STOP/MANUAL_REVIEW 逻辑
[ ] 不修改 Capability
[ ] public import test 通过
验证
pnpm --filter @moss-mini-demo/moss-adapter build
pnpm vitest run packages/moss-adapter/test
pnpm test:package-import
pnpm check
git diff --checkCodex 指令
只建立 Adapter 边界、类型、错误、buildInfo 和 fake。不要提前写 Quote selection、
Capability digest、simulation mapper 或 Decision。用 public-entry tests 锁定依赖方向。
Activity
pillowtalk-Qy commentedon Aug 5, 2026
DEPENDENCY_GATE_CLEARED
Issue #24 has been squash-merged by PR #70 into
main@93235e5c3ef531075c860beadc6ad2ce6b3dc8a0.Evidence:
ac40e615ffd197abdba1eb4946a3d1fd9d4d677eaae0397da1ba4924422d5a456123e9a4243b1797Moss-Mini-Demo/moss@1ae6b6322d51fae9104f047efb94e601050b967fIssue #25 is now dependency-ready and remains unassigned. Its next permitted action is an independent, closed Work Plan based on the exact main SHA above.
Ready is not SCOPE_CONFIRMED, implementation start, QA PASS, Review, Merge Gate, or merge authorization. No branch, worktree, file change, commit, or PR is authorized by this dependency record.
pillowtalk-Qy commentedon Aug 5, 2026
M2_EXECUTION_SLOT_ASSIGNED
Builder:
pillowtalk-QyPlanning baseline:
origin/main@1e42babfa457ad20ac1efcecca227aceb4995c2bUpstream execution-slot evidence:
39ded5f45322d1fe79811c8908b067ad94f71d541e42babfa457ad20ac1efcecca227aceb4995c2bIssue #25 is now the single active Builder slot and is moved to Project In Progress for planning.
Planned branch after scope confirmation:
codex/issue-25-moss-adapter-portsPlanned isolated worktree after scope confirmation:
/Users/qy/Documents/moss-mini-demo-issue-25The first required evidence is a closed, path-specific Work Plan covering package ownership, public ports, dependency direction, server-only boundaries, exact workspace/lockfile changes, tests, failure behavior, and the prohibition on product orchestration or live-chain evidence outside the approved scope.
In Progress starts planning only. It is not
SCOPE_CONFIRMED, implementation authorization, QA PASS, Review, READY_TO_MERGE, Merge Gate, or merge authorization. Do not create the branch, worktree, file change, dependency update, commit, push, or PR before Maintainer scope confirmation.Issue #23 remains Ready and unassigned. Issues #26-#31 and #33-#34 remain Blocked; in particular, #33 is not released because #26, #27, #28, #31 and its other direct dependencies remain unsatisfied.
pillowtalk-Qy commentedon Aug 5, 2026
Final Implementation Work Plan - M2-04 Moss Adapter Ports - Awaiting Maintainer Scope Confirmation
0. Status and authority
Source: Issue #25, the accepted M2 dependency record for #24, and the current
M2 execution-slot assignment. This is a planning artifact only. It requests a
new Maintainer Scope Gate; it is not scope confirmation or implementation
authorization.
Exact planning baseline:
origin/main@1e42babfa457ad20ac1efcecca227aceb4995c2bfeat: add Web API baseline and strict contracts (#71)vendor/moss@1ae6b6322d51fae9104f047efb94e601050b967fcodex/issue-25-moss-adapter-ports/Users/qy/Documents/moss-mini-demo-issue-25No branch, worktree, file change, dependency update, commit, push, or PR is
created by this comment.
In ProgressandReadyare not Scope Confirmed,implementation authorization, QA PASS, Review, Merge Gate, or merge
authorization.
This plan supersedes no prior implementation and does not delete history. It
is a closed proposal for #25 only. The Builder stops until a Maintainer records
an explicit
SCOPE_CONFIRMED/IMPLEMENTATION_AUTHORIZEDdecision.1. Goal and closed boundary
Create the package
@moss-mini-demo/moss-adapteras the sole documented publicentry for the Moss integration boundary. The package will define the common
MossPort, raw evidence envelopes, structured secret-safe adapter errors,fixed
MossBuildInfo, and offlineProductionandFakeimplementationswith the same port interface.
The adapter preserves source values and provenance. It does not decide whether
a quote is selected, whether a capability is safe, or whether an action may be
executed. It is an offline boundary package, not a runnable product, wallet,
RPC client, or live-chain integration.
2. Exact Moss dependency and provenance decision
The accepted #24 submodule remains the only Moss source of record:
vendor/moss;https://github.com/Moss-Mini-Demo/moss.git;1ae6b6322d51fae9104f047efb94e601050b967f;docs/moss-dependency.md.The adapter package will not put
@themoss/core,@themoss/simulator, Kuru,or Pancake into its package manifest, and the root lockfile will not resolve
any legacy registry package. In particular,
@themoss/core@0.1.0from thelegacy npm Plan API is explicitly rejected.
The exact dependency direction for this issue is:
pinned vendor/moss build -> server-owned MossSourceBindings -> moss-adapterMossSourceBindingsis an internal, server-only structural binding. It acceptsraw values produced by the exact pinned Moss build and is injected into
ProductionMossPort; the adapter never importsvendor/mossby a filesystempath and never copies Moss source. There is intentionally no
file:,link:,git URL, registry dependency, or TypeScript path from the root package to the
submodule. This is required because #24's quality gate builds the submodule,
then deinitializes
vendor/mossbefore the root frozen install. A later,separately authorized integration task may provide the composition binding;
that task is outside #25.
The adapter records the exact #24 MossBuildInfo and rejects a binding whose
reported source identity or chain id is not compatible with that record. Tests
use inline synthetic bindings only; they are not Moss or chain evidence.
3. Sole public entry and exported surface
packages/moss-adapter/package.jsonexposes only the.entry. It exposes nosubpath exports and no private source path. The public entry is
@moss-mini-demo/moss-adapter.Runtime exports are limited to:
createProductionMossPort;createFakeMossPort;MossAdapterError;MOSS_BUILD_INFO.Type exports are limited to the port, input, raw evidence, build-info, source
binding, and error-code contracts named in this plan:
MossPort,MossSourceBindings,QuoteInput,ActionInput;RawOperationContract,RawQuote,RawCapability,RawCapabilityEvidence,RawSimulationEvidence;MossBuildInfo,MossOriginalSource,MiniDemoDerivedSource;MossAdapterErrorCode,ChainId143.No runtime Schema, Decision helper, quote-selection helper, capability digest,
simulation mapper, or unapproved public helper is added.
4. Fixed public port
The only runtime port contract is:
ProductionMossPortandFakeMossPortimplement this exact interface. Theadapter does not add a second port, overload the methods with product policy,
or expose a way to bypass the port.
QuoteInputandActionInputcarry the protocol/method operation context andopaque JSON-safe request parameters. The adapter does not select among quotes,
validate user intent, create a wallet action, or send an action.
5. Raw evidence contracts and layering
All evidence has two explicit layers.
mossOriginalis an exact, opaque valuefrom the pinned Moss source.
miniDemoDerivedcontains only fields derived bythis adapter boundary and is labelled as such. The adapter never relabels a
derived value as Moss evidence.
RawOperationContractcontains:protocolIdandmethodas the requested operation identifiers;mossOriginal.stub, preserving the exact loaded MossStubobject/value;mossOriginal.riskLabels, preserving the exact loaded risk labels;miniDemoDerived, containing only the normalized protocol, method, operationkind, and a copied risk-label view for local transport;
MossBuildInfoand source context.Risk labels remain an operation/Stub property. They are never copied onto a
CapabilityNode, interpreted as a capability digest, or used to make aDecision.
RawQuotecontains the operation contract, the exact raw quote inmossOriginal.value, and aminiDemoDerivedstatus ofNOT_NORMALIZED/DEFERRED_TO_M2_05. It is one raw quote result; collection andselection belong to #26.
RawCapabilityEvidencecontains:mossOriginal.value;snapshotmade from that raw value without changing the rawvalue or claiming cryptographic integrity;
miniDemoDerived.integritywith statusNOT_EVALUATEDand an explicitDEFERRED_TO_M2_06reason;The snapshot is only an independently owned, deep-frozen transport copy. No
canonical serialization, digest, capability mutation, or trust decision is
implemented here. Digest and integrity verification remain #27.
RawSimulationEvidencecontains the exact raw simulation result and sourcecontext in
mossOriginal, plus aminiDemoDerivedstatusNOT_MAPPED/DEFERRED_TO_M2_07. It does not map receipts, outcomes, coverage,alignment, or Decision fields. Simulation mapping remains #28.
Every envelope is JSON-safe at its public boundary. Non-JSON values or a source
object that cannot be snapshotted are rejected with a structured contract
error; no coercion silently changes the evidence.
6. Build information and chain identity
MOSS_BUILD_INFOis the exact immutable #24 identity, including source mode,upstream and integration repository, the pinned Moss commit, patchset digest,
package versions, and
officialRelease: false.buildInfo()returns thissame contract from both implementations.
Chain identity is an explicit adapter responsibility:
143(ChainId143);ProductionMossPortvalidates the injected binding's declared chain id beforeany method delegates;
FakeMossPortvalidates its configured chain id at construction;CHAIN_ID_MISMATCH;This check is configuration/provenance validation, not live-chain evidence.
7. Structured, secret-safe errors
All adapter failures are
MossAdapterErrorvalues with stable fields:code: MossAdapterErrorCode;operation(describe,quote,action,simulate, orbuildInfo);protocolId/methodcontext when they match the bounded identifiergrammar;
retryableboolean;The code set is closed for #25 and includes
INVALID_INPUT,CHAIN_ID_MISMATCH,SOURCE_CONTRACT_VIOLATION,UNSUPPORTED_PROTOCOL,UNSUPPORTED_METHOD,DESCRIBE_FAILED,QUOTE_FAILED,ACTION_FAILED, andSIMULATION_FAILED.Driver exceptions are converted to the corresponding stable code. Raw error
objects, RPC URLs, headers, account values, private keys, API keys, params,
capabilities, receipts, and original exception messages are never stored in or
returned by the public error. Tests inject secret-looking sentinel strings and
assert that they do not occur in
message, enumerable fields, or serializederror output.
8. Production and Fake behavior
createProductionMossPort(bindings)creates the production boundary aroundserver-only
MossSourceBindings. Each method:for exact preservation;
It performs no quote ranking, capability digesting, simulation mapping,
alignment, decision, STOP, MANUAL_REVIEW, RPC, wallet, signing, or transaction
work.
createFakeMossPort(config)accepts only inline synthetic operation, quote,capability, and simulation values and implements the same method signatures,
chain validation, source/derived labels, and error shape. It is a deterministic
development double, never a Moss/Monad fixture and never real evidence. Fake
values are not exported as product data.
9. Server-only and browser boundary
packages/moss-adapteris a server-only package. Its runtime entry importsserver-onlyand is built for the Node/Next server condition. The browsercondition must fail closed; no adapter runtime is imported by
apps/webclientcode.
The public-entry smoke runs once with the Node
react-servercondition andonce as a normal browser-like import that must fail with the server-only guard.
The existing Web bundle scan remains mandatory and must find no
@moss-mini-demo/moss-adapter,@themoss/*,vendor/moss, or Moss build-infomarker in browser output. No browser API, UI, Web orchestration, or Clear402
surface is added by #25.
10. Exact repository writable list
The implementation may modify exactly these 18 repository paths, and no other
path:
package.jsonpnpm-lock.yamlpackages/moss-adapter/package.jsonpackages/moss-adapter/tsconfig.jsonpackages/moss-adapter/tsconfig.build.jsonpackages/moss-adapter/src/types.tspackages/moss-adapter/src/errors.tspackages/moss-adapter/src/build-info.tspackages/moss-adapter/src/source-bindings.tspackages/moss-adapter/src/production.tspackages/moss-adapter/src/fake.tspackages/moss-adapter/src/index.tspackages/moss-adapter/test/contracts.test.tspackages/moss-adapter/test/errors.test.tspackages/moss-adapter/test/production.test.tspackages/moss-adapter/test/fake.test.tspackages/moss-adapter/test/server-only.test.tspackages/moss-adapter/test/public-entry.smoke.mjspnpm-workspace.yamlis an explicitly audited metadata file but requires zerocontent change: the existing
packages/*entry already registers the exactadapter package and the existing
allowBuildspolicy is unchanged. Adding avendor workspace entry, a second build-script permission, or a new workspace
glob is forbidden. If implementation discovers that a pnpm-workspace change is
actually necessary, it stops and requests a revised Scope Gate instead of
expanding this list.
No changes are allowed to
vendor/mosscontents or gitlink,.gitmodules,.github/workflows/quality-gate.yml, ADRs, report-schema, decision-engine,fixtures, Web/API files, governance, permissions, branch protection, Issue,
Project, Milestone,
README.md, ordocs/real-vs-mock.md.11. Required package metadata and root scripts
packages/moss-adapter/package.jsonis a private workspace package with onepublic
.export and only the existingserver-onlyruntime dependency. Itmust not add
@themoss/*, a registry Moss package, a new third-party package,or a subpath export.
The lockfile changes only by adding the adapter workspace importer and the
resolved
server-onlyentry if it is not already present. No unrelated lockfilerefresh is accepted.
Root
package.jsonchanges are limited to the established clean-checkoutordering:
build: report-schema, decision-engine, moss-adapter, then web;typecheck: prepare report-schema, run the root strict no-emit check, thenadapter and web package checks;
test:package-import: retain existing report-schema and decision-enginesmokes and append the adapter public-entry smoke;
check: retain the existing quality-gate sequence and contents; it remainsthe only CI entry point.
The adapter package has explicit
buildandtypecheckscripts. Noprebuild,pretypecheck,postinstall, or other hidden lifecycle script is introduced.No workflow edit or second build-script permission is introduced.
12. Tests and evidence
All tests use inline synthetic values and bounded error sentinels. No real
address, private key, API key, RPC result, quote, receipt, wallet, or chain
record is used.
Required coverage:
Mini-Demo-derived fields;
on CapabilityNode;
NOT_NORMALIZED;and integrity is explicitly
NOT_EVALUATED;NOT_MAPPED;contract shapes;
143succeeds and missing/non-143 ids fail closed;once;
@moss-mini-demo/moss-adaptersucceeds afterbuild and never through a private source path.
13. Implementation sequence after authorization
origin/mainand create the exact branch/worktree named above.contracts.
MossPort.list is a stop condition.
14. Verification from a clean clone
Run on Node
22.23.1and pnpm11.16.0, from a fresh isolated checkout withno pre-existing
dist:node --version pnpm --version pnpm install --frozen-lockfile pnpm --filter @moss-mini-demo/moss-adapter build pnpm --filter @moss-mini-demo/moss-adapter typecheck pnpm vitest run packages/moss-adapter/test pnpm test:package-import pnpm build pnpm typecheck pnpm test pnpm check pnpm test:web:bundle pnpm test:web:prod git diff --check origin/main...HEAD git diff --name-only origin/main...HEAD git status --shortThe production start/health commands are regression checks for the existing
Web baseline; #25 must not change its API contract. The expected changed-path
set must be exactly the 18 paths above. The existing
quality-gateworkflow,with its unchanged name, trigger scope, and
contents: readpermission, mustpass on the exact pushed head. Any CI result from another head is not evidence.
15. Acceptance, stop conditions, and rollback
Acceptance requires all of the following:
decision;
the adapter importer;
check, Web production smoke, andexact-head
quality-gateall pass;approval, authorization, or Decision evidence.
Stop immediately and return to the Maintainer if:
maindiffers from the baseline before branch creation;permission, a second build-script permission, a new public helper, or any
path outside the 18-item list;
align evidence, or make a Decision.
Rollback is a single revert of the #25 implementation commit (or deletion of
only the exact #25 branch/PR before merge). Never revert #24, #32, main,
required checks, or the submodule gitlink as part of #25.
16. Explicit non-goals
#25 does not implement Quote selection, Capability digest, simulation mapper,
Alignment, Decision, STOP, MANUAL_REVIEW, Web/API orchestration, RPC or
live-chain access, Clear402, wallet, signing, transaction construction or
submission, database, deployment, UI, fixtures, or changes to #8, #9, #20,
#23, or any M3 task.
17. Requested decision
Please record one of:
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED, with this exact path list anddependency direction accepted; or
SCOPE_CHANGES_REQUESTED, naming the path, API, or dependency decision thatmust change.
Until the first decision is recorded, Builder status is
WORK_PLAN_SUBMITTED / AWAITING_MAINTAINER_SCOPE_CONFIRMATIONand noimplementation action is authorized.
pillowtalk-Qy commentedon Aug 5, 2026
SCOPE_CHANGES_REQUESTED
Reviewed Work Plan: #25 (comment)
Planning baseline:
main@1e42babfa457ad20ac1efcecca227aceb4995c2bReviewed Work Plan body SHA-256:
9dbbfc567c45b0e2d8939f5fc6985a2cba7023451c2e1ce8859266fb42bdb47eThe following Scope Gate checks pass:
vendor/mossremains the organization submodule gitlink at exact commit1ae6b6322d51fae9104f047efb94e601050b967f, withhttps://github.com/Moss-Mini-Demo/moss.gitand no branch, tag, floating ref, copied source, or package-manager Moss dependency;packages/*andapps/*;vendor/mossis not absorbed into it;server-only@0.0.1link and unchanged sole'sharp@0.34.5': truepolicy;apps/weband its API contracts are read-only regression targets, not writable implementation scope;MossPortand five methods;@moss-mini-demo/moss-adapterthrough the.public entry;One verification blocker prevents implementation authorization:
pnpm test:web:prod, but no such script exists on the frozen baseline. The approved root production smoke command ispnpm test:web:production.Required correction:
pnpm test:web:prodwith the existingpnpm test:web:productioncommand throughout the complete Work Plan.test:web:prodalias or otherwise expandpackage.json; root script changes remain limited to the ordering and adapter public-entry additions already listed.Submit a complete revised Work Plan as a new comment so this reviewed plan remains an audit record. No implementation is authorized from the current plan. Until a Maintainer records
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZEDfor the revision, do not create the branch, worktree, file change, dependency update, commit, push, or PR.#25 remains Open, assigned to
pillowtalk-Qy, and Project In Progress for planning only. This is not QA, Review, READY_TO_MERGE, Merge Gate, or merge authorization.pillowtalk-Qy commentedon Aug 5, 2026
Revised Final Implementation Work Plan - M2-04 Moss Adapter Ports - Awaiting Maintainer Scope Confirmation
Revision source: SCOPE_CHANGES_REQUESTED. This complete revision preserves the exact baseline, 18 writable paths, dependencies, public surface, port contract, tests, risk boundaries, and non-goals. Its only scope delta is correcting the production-smoke script name to the baseline existing
pnpm test:web:production; the historical Work Plan remains unchanged as an audit record.0. Status and authority
Source: Issue #25, the accepted M2 dependency record for #24, and the current
M2 execution-slot assignment. This is a planning artifact only. It requests a
new Maintainer Scope Gate; it is not scope confirmation or implementation
authorization.
Exact planning baseline:
origin/main@1e42babfa457ad20ac1efcecca227aceb4995c2bfeat: add Web API baseline and strict contracts (#71)vendor/moss@1ae6b6322d51fae9104f047efb94e601050b967fcodex/issue-25-moss-adapter-ports/Users/qy/Documents/moss-mini-demo-issue-25No branch, worktree, file change, dependency update, commit, push, or PR is
created by this comment.
In ProgressandReadyare not Scope Confirmed,implementation authorization, QA PASS, Review, Merge Gate, or merge
authorization.
This plan supersedes no prior implementation and does not delete history. It
is a closed proposal for #25 only. The Builder stops until a Maintainer records
an explicit
SCOPE_CONFIRMED/IMPLEMENTATION_AUTHORIZEDdecision.1. Goal and closed boundary
Create the package
@moss-mini-demo/moss-adapteras the sole documented publicentry for the Moss integration boundary. The package will define the common
MossPort, raw evidence envelopes, structured secret-safe adapter errors,fixed
MossBuildInfo, and offlineProductionandFakeimplementationswith the same port interface.
The adapter preserves source values and provenance. It does not decide whether
a quote is selected, whether a capability is safe, or whether an action may be
executed. It is an offline boundary package, not a runnable product, wallet,
RPC client, or live-chain integration.
2. Exact Moss dependency and provenance decision
The accepted #24 submodule remains the only Moss source of record:
vendor/moss;https://github.com/Moss-Mini-Demo/moss.git;1ae6b6322d51fae9104f047efb94e601050b967f;docs/moss-dependency.md.The adapter package will not put
@themoss/core,@themoss/simulator, Kuru,or Pancake into its package manifest, and the root lockfile will not resolve
any legacy registry package. In particular,
@themoss/core@0.1.0from thelegacy npm Plan API is explicitly rejected.
The exact dependency direction for this issue is:
pinned vendor/moss build -> server-owned MossSourceBindings -> moss-adapterMossSourceBindingsis an internal, server-only structural binding. It acceptsraw values produced by the exact pinned Moss build and is injected into
ProductionMossPort; the adapter never importsvendor/mossby a filesystempath and never copies Moss source. There is intentionally no
file:,link:,git URL, registry dependency, or TypeScript path from the root package to the
submodule. This is required because #24's quality gate builds the submodule,
then deinitializes
vendor/mossbefore the root frozen install. A later,separately authorized integration task may provide the composition binding;
that task is outside #25.
The adapter records the exact #24 MossBuildInfo and rejects a binding whose
reported source identity or chain id is not compatible with that record. Tests
use inline synthetic bindings only; they are not Moss or chain evidence.
3. Sole public entry and exported surface
packages/moss-adapter/package.jsonexposes only the.entry. It exposes nosubpath exports and no private source path. The public entry is
@moss-mini-demo/moss-adapter.Runtime exports are limited to:
createProductionMossPort;createFakeMossPort;MossAdapterError;MOSS_BUILD_INFO.Type exports are limited to the port, input, raw evidence, build-info, source
binding, and error-code contracts named in this plan:
MossPort,MossSourceBindings,QuoteInput,ActionInput;RawOperationContract,RawQuote,RawCapability,RawCapabilityEvidence,RawSimulationEvidence;MossBuildInfo,MossOriginalSource,MiniDemoDerivedSource;MossAdapterErrorCode,ChainId143.No runtime Schema, Decision helper, quote-selection helper, capability digest,
simulation mapper, or unapproved public helper is added.
4. Fixed public port
The only runtime port contract is:
ProductionMossPortandFakeMossPortimplement this exact interface. Theadapter does not add a second port, overload the methods with product policy,
or expose a way to bypass the port.
QuoteInputandActionInputcarry the protocol/method operation context andopaque JSON-safe request parameters. The adapter does not select among quotes,
validate user intent, create a wallet action, or send an action.
5. Raw evidence contracts and layering
All evidence has two explicit layers.
mossOriginalis an exact, opaque valuefrom the pinned Moss source.
miniDemoDerivedcontains only fields derived bythis adapter boundary and is labelled as such. The adapter never relabels a
derived value as Moss evidence.
RawOperationContractcontains:protocolIdandmethodas the requested operation identifiers;mossOriginal.stub, preserving the exact loaded MossStubobject/value;mossOriginal.riskLabels, preserving the exact loaded risk labels;miniDemoDerived, containing only the normalized protocol, method, operationkind, and a copied risk-label view for local transport;
MossBuildInfoand source context.Risk labels remain an operation/Stub property. They are never copied onto a
CapabilityNode, interpreted as a capability digest, or used to make aDecision.
RawQuotecontains the operation contract, the exact raw quote inmossOriginal.value, and aminiDemoDerivedstatus ofNOT_NORMALIZED/DEFERRED_TO_M2_05. It is one raw quote result; collection andselection belong to #26.
RawCapabilityEvidencecontains:mossOriginal.value;snapshotmade from that raw value without changing the rawvalue or claiming cryptographic integrity;
miniDemoDerived.integritywith statusNOT_EVALUATEDand an explicitDEFERRED_TO_M2_06reason;The snapshot is only an independently owned, deep-frozen transport copy. No
canonical serialization, digest, capability mutation, or trust decision is
implemented here. Digest and integrity verification remain #27.
RawSimulationEvidencecontains the exact raw simulation result and sourcecontext in
mossOriginal, plus aminiDemoDerivedstatusNOT_MAPPED/DEFERRED_TO_M2_07. It does not map receipts, outcomes, coverage,alignment, or Decision fields. Simulation mapping remains #28.
Every envelope is JSON-safe at its public boundary. Non-JSON values or a source
object that cannot be snapshotted are rejected with a structured contract
error; no coercion silently changes the evidence.
6. Build information and chain identity
MOSS_BUILD_INFOis the exact immutable #24 identity, including source mode,upstream and integration repository, the pinned Moss commit, patchset digest,
package versions, and
officialRelease: false.buildInfo()returns thissame contract from both implementations.
Chain identity is an explicit adapter responsibility:
143(ChainId143);ProductionMossPortvalidates the injected binding's declared chain id beforeany method delegates;
FakeMossPortvalidates its configured chain id at construction;CHAIN_ID_MISMATCH;This check is configuration/provenance validation, not live-chain evidence.
7. Structured, secret-safe errors
All adapter failures are
MossAdapterErrorvalues with stable fields:code: MossAdapterErrorCode;operation(describe,quote,action,simulate, orbuildInfo);protocolId/methodcontext when they match the bounded identifiergrammar;
retryableboolean;The code set is closed for #25 and includes
INVALID_INPUT,CHAIN_ID_MISMATCH,SOURCE_CONTRACT_VIOLATION,UNSUPPORTED_PROTOCOL,UNSUPPORTED_METHOD,DESCRIBE_FAILED,QUOTE_FAILED,ACTION_FAILED, andSIMULATION_FAILED.Driver exceptions are converted to the corresponding stable code. Raw error
objects, RPC URLs, headers, account values, private keys, API keys, params,
capabilities, receipts, and original exception messages are never stored in or
returned by the public error. Tests inject secret-looking sentinel strings and
assert that they do not occur in
message, enumerable fields, or serializederror output.
8. Production and Fake behavior
createProductionMossPort(bindings)creates the production boundary aroundserver-only
MossSourceBindings. Each method:for exact preservation;
It performs no quote ranking, capability digesting, simulation mapping,
alignment, decision, STOP, MANUAL_REVIEW, RPC, wallet, signing, or transaction
work.
createFakeMossPort(config)accepts only inline synthetic operation, quote,capability, and simulation values and implements the same method signatures,
chain validation, source/derived labels, and error shape. It is a deterministic
development double, never a Moss/Monad fixture and never real evidence. Fake
values are not exported as product data.
9. Server-only and browser boundary
packages/moss-adapteris a server-only package. Its runtime entry importsserver-onlyand is built for the Node/Next server condition. The browsercondition must fail closed; no adapter runtime is imported by
apps/webclientcode.
The public-entry smoke runs once with the Node
react-servercondition andonce as a normal browser-like import that must fail with the server-only guard.
The existing Web bundle scan remains mandatory and must find no
@moss-mini-demo/moss-adapter,@themoss/*,vendor/moss, or Moss build-infomarker in browser output. No browser API, UI, Web orchestration, or Clear402
surface is added by #25.
10. Exact repository writable list
The implementation may modify exactly these 18 repository paths, and no other
path:
package.jsonpnpm-lock.yamlpackages/moss-adapter/package.jsonpackages/moss-adapter/tsconfig.jsonpackages/moss-adapter/tsconfig.build.jsonpackages/moss-adapter/src/types.tspackages/moss-adapter/src/errors.tspackages/moss-adapter/src/build-info.tspackages/moss-adapter/src/source-bindings.tspackages/moss-adapter/src/production.tspackages/moss-adapter/src/fake.tspackages/moss-adapter/src/index.tspackages/moss-adapter/test/contracts.test.tspackages/moss-adapter/test/errors.test.tspackages/moss-adapter/test/production.test.tspackages/moss-adapter/test/fake.test.tspackages/moss-adapter/test/server-only.test.tspackages/moss-adapter/test/public-entry.smoke.mjspnpm-workspace.yamlis an explicitly audited metadata file but requires zerocontent change: the existing
packages/*entry already registers the exactadapter package and the existing
allowBuildspolicy is unchanged. Adding avendor workspace entry, a second build-script permission, or a new workspace
glob is forbidden. If implementation discovers that a pnpm-workspace change is
actually necessary, it stops and requests a revised Scope Gate instead of
expanding this list.
No changes are allowed to
vendor/mosscontents or gitlink,.gitmodules,.github/workflows/quality-gate.yml, ADRs, report-schema, decision-engine,fixtures, Web/API files, governance, permissions, branch protection, Issue,
Project, Milestone,
README.md, ordocs/real-vs-mock.md.11. Required package metadata and root scripts
packages/moss-adapter/package.jsonis a private workspace package with onepublic
.export and only the existingserver-onlyruntime dependency. Itmust not add
@themoss/*, a registry Moss package, a new third-party package,or a subpath export.
The lockfile changes only by adding the adapter workspace importer and the
resolved
server-onlyentry if it is not already present. No unrelated lockfilerefresh is accepted.
Root
package.jsonchanges are limited to the established clean-checkoutordering:
build: report-schema, decision-engine, moss-adapter, then web;typecheck: prepare report-schema, run the root strict no-emit check, thenadapter and web package checks;
test:package-import: retain existing report-schema and decision-enginesmokes and append the adapter public-entry smoke;
check: retain the existing quality-gate sequence and contents; it remainsthe only CI entry point.
The adapter package has explicit
buildandtypecheckscripts. Noprebuild,pretypecheck,postinstall, or other hidden lifecycle script is introduced.No workflow edit or second build-script permission is introduced.
12. Tests and evidence
All tests use inline synthetic values and bounded error sentinels. No real
address, private key, API key, RPC result, quote, receipt, wallet, or chain
record is used.
Required coverage:
Mini-Demo-derived fields;
on CapabilityNode;
NOT_NORMALIZED;and integrity is explicitly
NOT_EVALUATED;NOT_MAPPED;contract shapes;
143succeeds and missing/non-143 ids fail closed;once;
@moss-mini-demo/moss-adaptersucceeds afterbuild and never through a private source path.
13. Implementation sequence after authorization
origin/mainand create the exact branch/worktree named above.contracts.
MossPort.list is a stop condition.
14. Verification from a clean clone
Run on Node
22.23.1and pnpm11.16.0, from a fresh isolated checkout withno pre-existing
dist:node --version pnpm --version pnpm install --frozen-lockfile pnpm --filter @moss-mini-demo/moss-adapter build pnpm --filter @moss-mini-demo/moss-adapter typecheck pnpm vitest run packages/moss-adapter/test pnpm test:package-import pnpm build pnpm typecheck pnpm test pnpm check pnpm test:web:bundle pnpm test:web:production git diff --check origin/main...HEAD git diff --name-only origin/main...HEAD git status --shortThe production start/health commands are regression checks for the existing
Web baseline; #25 must not change its API contract. The expected changed-path
set must be exactly the 18 paths above. The existing
quality-gateworkflow,with its unchanged name, trigger scope, and
contents: readpermission, mustpass on the exact pushed head. Any CI result from another head is not evidence.
15. Acceptance, stop conditions, and rollback
Acceptance requires all of the following:
decision;
the adapter importer;
check, Web production smoke, andexact-head
quality-gateall pass;approval, authorization, or Decision evidence.
Stop immediately and return to the Maintainer if:
maindiffers from the baseline before branch creation;permission, a second build-script permission, a new public helper, or any
path outside the 18-item list;
align evidence, or make a Decision.
Rollback is a single revert of the #25 implementation commit (or deletion of
only the exact #25 branch/PR before merge). Never revert #24, #32, main,
required checks, or the submodule gitlink as part of #25.
16. Explicit non-goals
#25 does not implement Quote selection, Capability digest, simulation mapper,
Alignment, Decision, STOP, MANUAL_REVIEW, Web/API orchestration, RPC or
live-chain access, Clear402, wallet, signing, transaction construction or
submission, database, deployment, UI, fixtures, or changes to #8, #9, #20,
#23, or any M3 task.
17. Requested decision
Please record one of:
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED, with this exact path list anddependency direction accepted; or
SCOPE_CHANGES_REQUESTED, naming the path, API, or dependency decision thatmust change.
Until the first decision is recorded, Builder status is
WORK_PLAN_SUBMITTED / AWAITING_MAINTAINER_SCOPE_CONFIRMATIONand noimplementation action is authorized.
pillowtalk-Qy commentedon Aug 5, 2026
SCOPE_CONFIRMED / IMPLEMENTATION_AUTHORIZED
Authorized Work Plan: #25 (comment)
Implementation baseline:
main@1e42babfa457ad20ac1efcecca227aceb4995c2bAuthorized Work Plan body SHA-256:
bab5c67b4cb56f87e929c738549a3420620dafa0f58b4bf42666065757fc4a6dMaintainer Scope Gate result: PASS.
The complete revised Work Plan is authorized with these frozen boundaries:
vendor/mossremains the independent organization submodule at exact gitlink1ae6b6322d51fae9104f047efb94e601050b967f; no gitlink,.gitmodules, vendor-source, tracked-ref, root-workspace, npm Moss dependency or source-copy change;'sharp@0.34.5': truepolicy remains unchanged;@moss-mini-demo/moss-adapterthrough export.only, with the runtime and type exports listed in the Work Plan;MossPortand five methods, with fixed chain-id, source/derived, build-info and secret-safe error boundaries;apps/webremains read-only, while its public import, browser-bundle and production-start/health checks remain mandatory regressions;pnpm test:web:production; no alias or additional root script is authorized.Builder Qy may now re-fetch and confirm the exact baseline, create only
codex/issue-25-moss-adapter-portsin the planned isolated worktree, implement the authorized scope, and open one Draft PR withCloses #25only. If main changes before branching, or another path, dependency, permission, public export, port behavior or later-Issue semantic becomes necessary, stop and request a new Maintainer Scope Gate.This record authorizes implementation only. It is not Pre-PR QA, Review, READY_TO_MERGE, Merge Gate, or merge authorization. The implementation PR must remain Draft until exact-head QA handoff and subsequent Maintainer review.
#25 remains Open, assigned to
pillowtalk-Qy, and Project In Progress. No downstream Issue is released by this authorization.