7176e63503
sx delivered most of the foundation since the plan was written: alias re-exports instead of pub, the modules/std.sx facade barrel, and native std fs/process/json/cli/hash/log/test/socket/mem. Replace the 'sx Foundation Work' section with as-built status + remaining gaps, mark Phase 0 done / Phase 1 partial, note the superseded subplan-01 slices, and drop the retired flow-harness execution contract (subplan 08, roles, checkpoint files).
165 lines
5.1 KiB
Markdown
165 lines
5.1 KiB
Markdown
# Subplan 01 - sx Language And Standard Library
|
||
|
||
> **Status (2026-06-11):** largely superseded by sx itself. Slice 1 shipped
|
||
> as-built with a different design — there is no `pub`; aliases are the
|
||
> re-export mechanism and `modules/std.sx` is the barrel. Slice 2 is settled
|
||
> (`!` error channel, `catch (e)` bindings). Slices 5–7 partially shipped
|
||
> (`std.fs`, `std.process`, `std.hash` SHA-256, `std.json`, `std.cli`,
|
||
> `std.log`). Still open: Unicode/String model (Slice 3),
|
||
> HashMap/StringBuilder (Slice 4), bytes/paths (Slice 5 remainder),
|
||
> time/random/encoding (Slice 6 remainder), config (Slice 7 remainder), and
|
||
> HTTP/TLS/SQLite/archive/testing helpers (Slice 8). See "sx Foundation
|
||
> Status" in `PLAN.md`.
|
||
|
||
## Goal
|
||
|
||
Build the language and std primitives required before the distribution platform
|
||
can be implemented cleanly in sx.
|
||
|
||
## Work Location
|
||
|
||
- Primary repo: `/Users/agra/projects/sx`
|
||
- Planning repo: `/Users/agra/projects/distribution`
|
||
|
||
## Prerequisites
|
||
|
||
- Read `/Users/agra/projects/sx/readme.md`
|
||
- Read `/Users/agra/projects/sx/specs.md`
|
||
- Read `/Users/agra/projects/sx/docs/error-handling.md`
|
||
- Re-read `PLAN.md` sections:
|
||
- `Phase 0 - sx Language and Module Prerequisites`
|
||
- `Standard Library API Surface`
|
||
- `Detailed Std Struct And Method Sketches`
|
||
|
||
## Slice 1 - Public Exports And Namespace Aliases
|
||
|
||
Deliver:
|
||
|
||
- Add `pub` declarations for public module members.
|
||
- Add public namespace member re-export aliases:
|
||
- `pub print :: core.print`
|
||
- `pub format :: core.format`
|
||
- Support alias imports without forcing every caller to know the source module.
|
||
- Add parser, AST, resolver, and compiler tests.
|
||
- Add examples for module barrels such as `std.sx`.
|
||
|
||
Acceptance:
|
||
|
||
- Private module members are not importable outside their namespace.
|
||
- Re-exported members keep correct identity for diagnostics and docs.
|
||
- Cycles and duplicate public names produce clear errors.
|
||
|
||
## Slice 2 - Error Handling Alignment
|
||
|
||
Deliver:
|
||
|
||
- Audit all proposed std signatures against sx error handling.
|
||
- Replace any incorrect `!T` assumptions with the actual sx shape.
|
||
- Add tests that show success and error return forms.
|
||
|
||
Acceptance:
|
||
|
||
- New std APIs follow the actual sx error model.
|
||
- Distribution platform examples compile with the same error style.
|
||
|
||
## Slice 3 - Unicode And String Model
|
||
|
||
Deliver:
|
||
|
||
- Define `String` as validated UTF-8 bytes.
|
||
- Define explicit terms:
|
||
- byte length
|
||
- Unicode scalar value
|
||
- grapheme cluster
|
||
- code point index is not a random-access string index
|
||
- Add `std.unicode` primitives for validation, scalar iteration,
|
||
normalization policy, case mapping policy, and ASCII fast paths.
|
||
- Add `StringBuilder` for efficient construction.
|
||
|
||
Acceptance:
|
||
|
||
- Invalid UTF-8 cannot silently become `String`.
|
||
- APIs that operate on bytes, scalars, and display width are named distinctly.
|
||
- Platform identifiers and paths do not accidentally use display width logic.
|
||
|
||
## Slice 4 - Collections
|
||
|
||
Deliver:
|
||
|
||
- Extend `List` with reserve, resize, insert, remove, pop, clear, sort, find,
|
||
contains, map/filter style helpers where idiomatic.
|
||
- Add `HashMap` with deterministic iteration option or clear documentation that
|
||
order is unspecified.
|
||
- Add hash/equality hooks for custom key types.
|
||
- Add tests for resize, collisions, deletion, and iteration.
|
||
|
||
Acceptance:
|
||
|
||
- Manifest parsing, route tables, and in-memory product stores can be written
|
||
without ad hoc arrays.
|
||
|
||
## Slice 5 - Bytes, Paths, FS, And Process
|
||
|
||
Deliver:
|
||
|
||
- `std.bytes` for slices, builders, compare, copy, starts_with, ends_with.
|
||
- `std.path` with platform-aware join, normalize, basename, dirname, extension.
|
||
- `std.fs` with open/read/write/stat/mkdir/rename/remove/temp_dir/walk.
|
||
- `std.process` with args, env, cwd, exit, spawn, wait, stdout/stderr capture.
|
||
|
||
Acceptance:
|
||
|
||
- A CLI can read a manifest, inspect files, spawn validation helpers, and write
|
||
artifacts safely.
|
||
|
||
## Slice 6 - Time, Random, Hashing, Encoding
|
||
|
||
Deliver:
|
||
|
||
- `std.time` timestamps, durations, monotonic clock, RFC3339 parse/format.
|
||
- `std.random` secure bytes and deterministic PRNG for tests.
|
||
- `std.hash` SHA-256 streaming.
|
||
- `std.encoding` hex, base64url, percent encoding.
|
||
|
||
Acceptance:
|
||
|
||
- Release ids, token hashes, artifact digests, and audit timestamps can be
|
||
implemented without platform-specific shims.
|
||
|
||
## Slice 7 - JSON, Config, CLI, And Logging
|
||
|
||
Deliver:
|
||
|
||
- `std.json` parser/writer with useful typed access.
|
||
- `std.config` for env/file/CLI config layering.
|
||
- `std.cli` parser with subcommands, flags, help, exit codes.
|
||
- `std.log` structured events and levels.
|
||
|
||
Acceptance:
|
||
|
||
- `dist ci publish --manifest dist.json --json` can parse args and emit stable
|
||
JSON output.
|
||
|
||
## Slice 8 - HTTP, TLS, SQLite, Archive, Testing
|
||
|
||
Deliver:
|
||
|
||
- `std.http` server/client basics.
|
||
- `std.tls` client/server wiring or explicit temporary boundary.
|
||
- `std.db.sqlite` minimal prepared statements and transactions.
|
||
- `std.archive` zip/tar/gzip reading needed for artifacts.
|
||
- `std.testing` assertions, fixtures, temp directories, golden files.
|
||
|
||
Acceptance:
|
||
|
||
- `distd` can expose endpoints, persist releases, inspect artifacts, and run
|
||
repeatable tests.
|
||
|
||
## Checkpoint Notes
|
||
|
||
After each slice, update:
|
||
|
||
- `.agents/CHECKPOINT.md`
|
||
- `.agents/checkpoint.json`
|
||
- Any changed API signatures in `PLAN.md`
|