Prompt-Sized Specifications
Relevant source files
The following files were used as context for generating this wiki page:
Prompt-Sized Specifications are core architectural artifacts in the Sploosh project, designed to facilitate "AI-native" development. These specifications are condensed, high-fidelity mirrors of the authoritative language specification that fit within the context windows (prompt budgets) of Large Language Models (LLMs). The primary goal is to allow AI coding agents to generate correct, compilable Sploosh code on the first attempt by providing the entire language definition as part of the system prompt.
This system ensures that the language remains accessible to models by enforcing strict token ceilings through Continuous Integration (CI). The specifications are divided into a "Core" reference and a "Web3" companion to optimize token usage based on the specific task requirements.
Sources: README.md:14-19, VISION.md:46-52
Architecture and Design Principles
The Prompt-Sized Specification system is built on the philosophy that a programming language should be small enough to be fully described within an LLM's high-attention context. This approach prioritizes LLM accuracy over human-centric ergonomics when the two conflict.
Core Principles
- Prompt-Loadable Core: The language core must stay small enough to be loaded alongside real-world task context.
- One Canonical Way: Every operation has exactly one syntactic form to eliminate ambiguity for models.
- Vocabulary Familiarity: Keywords (e.g.,
fn,let,match,spawn) are drawn from the most-trained tokens in existing languages to leverage prior LLM training. - CI Enforcement: The size of these mirrors is strictly controlled and verified on every commit.
Sources: VISION.md:46-52, README.md:9-19
Technical Workflow
The following diagram illustrates how Prompt-Sized Specifications are integrated into the development and CI workflow:
The CI pipeline uses a specialized script to tokenize and validate the mirrors against strict ceilings defined in the project vision.
Sources: scripts/check_prompt_budget.py:1-15, CONTRIBUTING.md:76-80
Token Budgets and Enforcement
The project defines specific token ceilings based on the cl100k_base encoding (used by models like GPT-4 and Claude). These budgets are calibrated to attention quality and prompt portability rather than maximum frontier context window capacity.
Defined Ceilings
| Artifact | Path | Token Ceiling | Warning Threshold |
|---|---|---|---|
| Core Mirror | docs/spec-plans/LANGUAGE_SPEC_PROMPT_CORE.md | 5,600 tokens | 90% (5,040 tokens) |
| Web3 Mirror | docs/spec-plans/LANGUAGE_SPEC_PROMPT_WEB3.md | 1,500 tokens | 90% (1,350 tokens) |
Sources: scripts/check_prompt_budget.py:12-15, VISION.md:49-52, CONTRIBUTING.md:82-84
Enforcement Script (check_prompt_budget.py)
The script scripts/check_prompt_budget.py is the primary tool for budget enforcement. It utilizes the tiktoken library to accurately count tokens and returns a non-zero exit code if the budget is exceeded, effectively blocking PRs that bloat the specification.
Sources: scripts/check_prompt_budget.py:33-55
Synchronisation and Maintenance
As a "spec-first" project, any change to language behavior must be reflected in the authoritative LANGUAGE_SPEC.md and simultaneously updated in the prompt-sized mirrors.
Maintenance Guidelines
- Sacred Rule: Stale or contradictory docs are considered language bugs.
- Conservative Additions: Adding a new feature generally requires removing another or splitting the artifact to maintain the token budget.
- Mirror Integrity: All mirror documents must always agree with the authoritative spec.
Sources: VISION.md:55-58, AGENTS.md:56-60, CONTRIBUTING.md:72-74
Data Relationship
This relationship ensures that the high-level summary used by AI agents is always derived from the same source of truth as the compiler implementation.
Sources: AGENTS.md:56-68, VISION.md:54-58
Impact on Security and Soundness
The Prompt-Sized Specifications are considered active security surfaces. Flaws in the specification—such as unsound rules or reentrancy footguns—are treated as vulnerabilities because they could lead AI agents to generate inherently unsafe code.
- Vulnerability Reporting: Security-relevant design flaws in the specifications (especially the Web3 surface) should be reported privately via the project's security policy.
- Design-Level Soundness: Security reviews of the specification mirrors are encouraged to ensure that the "AI-native" constraints do not compromise safety.
Sources: SECURITY.md:10-20, SECURITY.md:80-86
Prompt-Sized Specifications represent a shift toward prioritizing machine readability and context-window efficiency in language design, ensuring that Sploosh remains a viable target for automated coding agents.
Sources: README.md:9-12, VISION.md:8-12