distribution/PLAN.md

Distribution Platform in sx

Goal

Build an App Store-like distribution platform in sx, but not limited to iOS apps. It should distribute mobile, desktop, and server/client artifacts through a CI-friendly release workflow.

Supported targets for the first product direction:

• iOS: IPA metadata, TestFlight links, Enterprise/MDM manifests, artifact-only downloads
• Android: APK first, AAB later
• macOS: app archives, dmg/pkg metadata, signing and notarization status
• Linux: tarballs first, then deb/rpm/AppImage metadata
• Windows: zip/installer first, then MSIX/signing metadata

The main commands are:

• distd: the HTTP API, install page, and artifact server
• dist: the CI/admin CLI

The release workflow must be easy to integrate into CI. A CI job should be able to upload artifacts, create a release, attach platform variants, promote a channel, and receive machine-readable JSON output.

Product code should live in sx. C or system APIs are acceptable only as thin platform backends for capabilities that sx cannot express yet.

Product Shape

This is an operational distribution tool first, not a public marketplace. The initial product should feel like a release console: quiet, dense, fast to scan, and optimized for repeated internal/private release work.

Core principles:

• CI is the primary writer.
• Humans inspect, promote, revoke, download, and audit.
• Releases are immutable.
• Channels are mutable pointers to releases.
• Artifacts are content-addressed and never silently replaced.
• Every upload, publish, promotion, token change, and deletion writes an audit event.
• The first version should be understandable from the filesystem and SQLite database during development.

Users And Actors

• CI runner: publishes releases with dist ci publish.
• Release manager: promotes channels, checks validation, and reads audit logs.
• Developer/tester: downloads the current artifact for a platform/channel.
• Admin: creates apps, manages tokens, and configures identity constraints.
• distd: server/API/artifact store.
• dist: CLI for CI and local admin work.

Core Concepts

App:

• Product being distributed.
• Owns identity rules, allowed platforms, releases, channels, and tokens.

Release:

• Immutable version/build record for one app.
• Contains one or more platform artifacts.

Artifact:

• Uploaded file for a platform.
• Stored by digest and linked to release metadata.

Channel:

• Mutable pointer such as stable, beta, internal, nightly.
• Promotion changes the pointer, not the release.

Token:

• Scoped credential for CI and automation.
• Stored hashed, expires or can be revoked.

Audit event:

• Immutable record of important actions.

Main Workflows

CI publish:

1. CI builds artifacts.
2. CI writes or updates dist.json.
3. CI runs dist ci publish --server "$DIST_SERVER" --token "$DIST_TOKEN" --manifest dist.json --json.
4. dist validates the manifest and streams artifact uploads.
5. distd validates metadata and stores artifacts by digest.
6. The release is published.
7. A requested channel is promoted if policy allows it.
8. CI receives JSON with release ids, artifact ids, digests, and URLs.

Human release management:

1. Release manager opens the admin UI.
2. They inspect release status, artifact validation, and audit history.
3. They promote, rollback, revoke tokens, or download artifacts.

Install/download:

1. User opens an app/channel install page.
2. Platform detection chooses the most relevant artifact or install path.
3. The page shows accurate platform-specific actions and metadata.
4. Access policy determines whether the user can download or install.

iOS Install Policy

iOS needs special handling. The platform must not imply that a normal iPhone can install an arbitrary IPA from a web page.

Supported iOS modes:

• TestFlight: store a TestFlight link and open Apple's install flow.
• Enterprise/MDM: serve a valid HTTPS manifest plist for enrolled devices.
• Artifact only: allow authenticated IPA download, without presenting it as a normal mobile install action.

This distinction must be visible in both the API model and admin/install UI.

Architecture Overview

The intended stack is:

sx language and std primitives
  -> infra libraries: http, json, hashing, storage, db, auth, archive
  -> distribution domain: app, artifact, release, channel, token, audit
  -> interfaces: CLI, HTTP API, install pages, admin UI
  -> deployment: Docker image, NAS-friendly config, persistent data volume

Storage direction:

• SQLite first.
• Local filesystem artifact storage first.
• Object storage adapter later.

Deployment direction:

• Docker/OCI image.
• One persistent /data volume for database, artifacts, uploads, config, and logs.
• One HTTP port.
• /healthz endpoint.
• Runs behind a reverse proxy for TLS.
• Runs as a non-root user.
• UGREEN NAS deployment through Docker/Container Manager is a first-version requirement.

sx Foundation Work

Before the product can be implemented well, sx needs a stronger language and standard library foundation.

Language/module needs:

• pub exports so std modules do not leak private helpers.
• Alias imports and curated namespace barrels.
• Namespace member re-export syntax such as pub print :: core.print.
• Error handling that follows the real sx model. ! is an error channel, not a generic result wrapper.

Standard library needs, at overview level:

• Collections: extended List, HashMap
• Strings: validated UTF-8 String, StringBuilder, explicit Unicode model
• Bytes and paths
• Filesystem and process APIs
• Time, random, hashing, and encoding
• JSON, URL, MIME, config, CLI, and logging
• HTTP server/client and TLS boundary
• SQLite
• Archive inspection
• Testing helpers

Unicode must be specified precisely:

• String is validated UTF-8 bytes.
• Byte length, scalar values, grapheme clusters, and display width are distinct.
• APIs must clearly say which unit they operate on.
• Invalid UTF-8 must not silently become a String.

Implementation Phases

Phase 0 - sx language/module prerequisites:

• Add pub support, alias imports, and namespace member re-exports.

Phase 1 - standard library foundation:

• Build the std primitives needed for CLI, HTTP, storage, validation, and tests.

Phase 2 - product domain:

• Define apps, releases, artifacts, channels, tokens, policies, and audit events.

Phase 3 - storage:

• Add SQLite persistence and filesystem artifact storage.

Phase 4 - CLI first:

• Make dist ci publish --manifest dist.json --json work before the admin UI.

Phase 5 - HTTP API:

• Expose app, release, upload, download, channel, token, and audit endpoints.

Phase 6 - artifact validation:

• Validate APK and IPA first, then desktop artifact metadata.

Phase 7 - channels and install pages:

• Add promotion, rollback, download URLs, and platform-specific install pages.

Phase 8 - admin UI:

• Build a dense operational UI for apps, releases, artifacts, tokens, settings, install pages, and audit logs.

Phase 9 - packaging:

• Package distd and the admin UI into a Docker image suitable for UGREEN NAS.

CI Contract

The primary CI command should be:

dist ci publish \
  --server "$DIST_SERVER" \
  --token "$DIST_TOKEN" \
  --manifest dist.json \
  --json

The command should:

1. Validate the manifest.
2. Create or find the app.
3. Create a draft release.
4. Upload all artifacts with streaming SHA-256.
5. Validate platform metadata.
6. Publish the release.
7. Promote the requested channel if specified.
8. Print JSON containing release id, artifact ids, digests, and download URLs.

First Milestone

Milestone 1 is complete when:

• Required sx language/std primitives exist or have explicit temporary boundaries.
• distd can run locally.
• dist ci publish can publish a release with at least APK and IPA artifacts.
• Artifacts are stored by digest.
• SQLite stores apps, releases, artifacts, channels, tokens, and audit events.
• A channel can be promoted and rolled back.
• Install/download pages accurately handle iOS, Android, and desktop artifacts.
• The admin UI can inspect apps, releases, validations, tokens, and audit logs.
• A Docker image can run on a UGREEN NAS with a persistent data volume.

Non-goals For Version 1

• Public marketplace payments.
• Reviews and ratings.
• Organization billing.
• Sophisticated staged rollout targeting.
• CDN integration.
• Full signing/notarization automation.
• Object storage.
• Postgres.

Detailed Execution

PLAN.md is the overview. Detailed implementation breakdowns live in .agents/subplans/.

Before starting or resuming work, read:

• .agents/ORCHESTRATION.md
• .agents/CHECKPOINT.md
• .agents/checkpoint.json
• the active .agents/subplans/*.md file

The workflow is sequential and branch-based:

• Codex manages orchestration and validation.
• Snarky owns product briefs and final product acceptance.
• Opus owns layout/design decisions.
• Opus is the only role that writes code during Opus implementation phases.
• Implementation uses git branches, not worktrees.
• Checkpoints are updated after every completed slice and before stopping work.