# 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`