Skip to content

Commit 43866d8

Browse files
turadgturadg
committed
Add initial xsnap worker binaries plan
0 parents  commit 43866d8

1 file changed

Lines changed: 162 additions & 0 deletions

File tree

‎PLAN.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# xsnap-worker-binaries Plan (Linux/macOS)
2+
3+
## Objective
4+
Create and operate a dedicated repository that builds and publishes prebuilt `xsnap-worker` binaries as npm platform packages for Linux and macOS, version-locked to `@agoric/xsnap`.
5+
6+
Windows is not supported.
7+
8+
## Scope
9+
This repo is responsible for:
10+
- Building `xsnap-worker` binaries for supported targets.
11+
- Packaging binaries into platform-specific npm packages.
12+
- Producing SHA256 manifest artifacts for release/debug binaries.
13+
- Publishing packages in a release flow that agoric-sdk can gate on.
14+
15+
This repo is not responsible for:
16+
- JS wrapper behavior in `@agoric/xsnap`.
17+
- Runtime resolver logic inside agoric-sdk.
18+
- Windows binaries.
19+
20+
## Supported Target Matrix
21+
- `linux-x64`
22+
- `linux-arm64`
23+
- `darwin-x64`
24+
- `darwin-arm64`
25+
26+
Planned package names:
27+
- `@agoric/xsnap-linux-x64`
28+
- `@agoric/xsnap-linux-arm64`
29+
- `@agoric/xsnap-darwin-x64`
30+
- `@agoric/xsnap-darwin-arm64`
31+
32+
## Deliverables
33+
1. Repository bootstrap
34+
- Initialize git repository and baseline docs.
35+
- Add `README.md`, `PLAN.md`, and contribution/release notes.
36+
37+
2. Build pipeline
38+
- Add CI workflow to build `xsnap-worker` for all supported targets.
39+
- Produce both release and debug binaries per target.
40+
- Normalize output layout for packaging and hashing.
41+
42+
3. Package templates
43+
- Add per-platform package template with:
44+
- Minimal `package.json` (`os`, `cpu`, `files`, exact versioning policy).
45+
- Binary placement convention (release/debug paths).
46+
- License/readme metadata.
47+
48+
4. Hash manifest generation
49+
- Generate SHA256 digests for all shipped binaries.
50+
- Emit machine-readable manifest artifact per version (JSON).
51+
- Include source revision metadata used to build binaries.
52+
53+
5. Publish automation
54+
- Implement versioned publish flow for all platform packages.
55+
- Enforce all-or-nothing publish semantics for the supported package set.
56+
- Add dry-run and validation mode.
57+
58+
6. Verification and smoke tests
59+
- Verify package installability by platform constraints.
60+
- Verify binary executability and debug/release path presence.
61+
- Verify manifest and packaged bytes are consistent.
62+
63+
7. Release contract for agoric-sdk integration
64+
- Document release order and expected artifacts:
65+
1) publish all supported platform packages at `X.Y.Z`
66+
2) verify npm availability
67+
3) unblock `@agoric/xsnap@X.Y.Z` publish in agoric-sdk
68+
- Provide a stable manifest artifact format that agoric-sdk can consume.
69+
70+
## Proposed Repository Structure
71+
```text
72+
.
73+
├── .github/workflows/
74+
│ ├── build.yml
75+
│ ├── release.yml
76+
│ └── verify.yml
77+
├── packages/
78+
│ ├── xsnap-linux-x64/
79+
│ ├── xsnap-linux-arm64/
80+
│ ├── xsnap-darwin-x64/
81+
│ └── xsnap-darwin-arm64/
82+
├── scripts/
83+
│ ├── build-<target>.sh
84+
│ ├── stage-packages.sh
85+
│ ├── generate-manifest.sh
86+
│ ├── verify-artifacts.sh
87+
│ └── publish-all.sh
88+
├── manifests/
89+
│ └── (generated per release)
90+
└── README.md
91+
```
92+
93+
## Implementation Milestones
94+
### Milestone 1: Bootstrap and conventions
95+
- Create workspace layout and package naming conventions.
96+
- Define binary path contract used by downstream resolver.
97+
- Define versioning rules (exact `X.Y.Z`, no range drift).
98+
99+
Exit criteria:
100+
- Repo structure exists and docs describe release contract.
101+
102+
### Milestone 2: Build + package on CI
103+
- Build all supported targets in CI.
104+
- Stage binaries into package directories.
105+
- Produce installable tarballs for each platform package.
106+
107+
Exit criteria:
108+
- CI artifacts include 4 platform package tarballs and both build modes.
109+
110+
### Milestone 3: Hash manifest + verification gates
111+
- Generate per-version SHA256 manifest.
112+
- Add CI checks for digest correctness and reproducibility constraints.
113+
- Validate packaged artifact paths match manifest entries.
114+
115+
Exit criteria:
116+
- CI fails on any hash/path mismatch.
117+
118+
### Milestone 4: Publish flow
119+
- Add controlled publish pipeline (tag-driven).
120+
- Ensure all four packages publish at the same version.
121+
- Add post-publish availability checks.
122+
123+
Exit criteria:
124+
- One command/workflow publishes all supported packages and verifies npm visibility.
125+
126+
### Milestone 5: Integration handoff to agoric-sdk
127+
- Document artifact/manifest retrieval instructions.
128+
- Provide sample inputs for agoric-sdk prepublish gate.
129+
- Confirm release choreography with agoric-sdk maintainers.
130+
131+
Exit criteria:
132+
- agoric-sdk can gate `@agoric/xsnap` publish on package availability and manifest.
133+
134+
## CI/CD Requirements
135+
- Use GitHub Actions for build, verify, and publish workflows.
136+
- Store npm publish token in GitHub secrets with least privilege.
137+
- Use immutable tags for releases (`vX.Y.Z`).
138+
- Run verification before publish and after publish.
139+
140+
## Versioning and Release Policy
141+
- Platform packages use exact versions matching `@agoric/xsnap`.
142+
- No partial releases for a version.
143+
- Rebuilds for same version are disallowed unless explicitly yanked and republished under new version.
144+
145+
## Risks and Mitigations
146+
- Cross-platform build drift:
147+
- Mitigation: pin toolchains and capture source/toolchain metadata in manifest.
148+
- Missing package at wrapper publish time:
149+
- Mitigation: strict publish order + post-publish availability checks.
150+
- Integrity mismatch:
151+
- Mitigation: mandatory SHA256 verification in CI and manifest artifact generation.
152+
153+
## Non-Goals
154+
- `win32-x64` and `win32-arm64` build and publish.
155+
- `.exe` packaging conventions.
156+
- Windows-specific CI and runtime validation.
157+
158+
## Immediate Next Steps
159+
1. Create baseline `README.md` and workflow skeletons.
160+
2. Implement build scripts for the four supported targets.
161+
3. Implement package staging and manifest generation scripts.
162+
4. Add verify workflow and make it required before release workflow.

0 commit comments

Comments
 (0)