distribution/.agents/subplans/01-language-and-stdlib.md

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