154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
# Subplan 01 - sx Language And Standard Library
|
|
|
|
## 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`
|