symboliclight 1.0.0

Spec-native, AI-friendly language for typed CLI and backend apps.

SymbolicLight

SymbolicLight Language, or SL, is a spec-native, AI-friendly application language for building typed CLI and backend apps with less glue code.

It is designed for developers who want application code that is easy for humans and AI tools to generate, review, test, and maintain. SL v1.0 focuses on explicit models, stores, routes, commands, tests, and task-spec alignment.

SymbolicLight is not trying to replace Python, Rust, or TypeScript everywhere. Its first goal is narrower:

Write application intent, data models, storage, routes, commands, and tests in one compact source file.

SL compiles to readable Python 3.11 so generated apps can run on the existing Python ecosystem.

Naming

• Formal project and brand name: SymbolicLight.
• Developer-facing language name: SL.
• Compiler command: slc.
• Source file extension: .sl.

Use SymbolicLight in project, website, release, and positioning text. Use SL in developer docs, examples, tutorials, and day-to-day language references.

Current Stable Baseline

SL v1.0 supports:

• app declarations.
• module declarations and explicit import "./file.sl" as name.
• intent "./file.intent.yaml" links to IntentSpec contracts.
• permissions from intent.permissions and test from intent.acceptance declarations.
• enum declarations and type record declarations.
• pure fn declarations inside modules and apps.
• Option<T> and Result<T, E> type references.
• store declarations backed by SQLite or optional Postgres.
• command handlers compiled to CLI subcommands.
• route GET/POST/PUT/PATCH/DELETE handlers compiled to JSON HTTP routes.
• typed route bodies and Response<T> status responses.
• fixture declarations and golden tests.
• typed config declarations.
• SQLite helpers such as count, exists, and test-only clear.
• JSON schema generation through slc schema.
• test blocks compiled to lightweight Python assertions.
• official formatting through slc fmt.
• source-map sidecars and best-effort .sl runtime backreferences.
• incremental slc check cache reuse.
• JSON diagnostics for tools through slc check --json.
• machine-readable doctor reports through slc doctor --json.
• read-only migration plans through slc migrate plan.
• local LSP support through slc lsp.
• local VS Code syntax, snippets, and language-server wiring under editors/vscode.
• local playground under playground/.
• IntentSpec-aware slc doctor route, command, and permission alignment hints.
• IntentSpec acceptance checks through slc test for apps that declare test from intent.acceptance.
• route auth checks through the minimal request.header(...) helper.
• schema drift inspection through slc doctor --db.
• optional Postgres runtime support through symboliclight[postgres].
• comment-preserving formatting for common // comment positions.
• repeatable release smoke checks through scripts/release_check.py.
• starter API templates through slc new api --template.
• docs, VS Code, and release notes maintenance checks.

Quick Start

Install from a local checkout for development:

pip install -e ".[dev]"

After building a local v1.0 package, install the wheel directly:

python -m build
pip install dist/symboliclight-1.0.0-py3-none-any.whl
slc check examples/todo_app.sl
slc check examples/todo_app.sl --json
slc build examples/todo_app.sl --out build/todo_app.py
slc schema examples/notes_api.sl --out build/notes_schema.json
slc fmt examples/todo_app.sl --check
slc doctor examples/todo_app.sl
slc doctor examples/todo_app.sl --json
slc doctor examples/gallery/small-admin-backend/app.sl --db build/admin.sqlite
slc doctor examples/gallery/small-admin-backend/app.sl --db build/admin.sqlite --json
slc migrate plan examples/gallery/project-ops-api/app.sl --db build/project_ops.sqlite
slc check examples/gallery/project-ops-api/app_postgres.sl
slc new api my-api --template todo --backend sqlite
slc new api ops-api --template project-ops --backend postgres
slc lsp
python build/todo_app.py test
python build/todo_app.py add "Buy milk"
python build/todo_app.py list
python build/todo_app.py serve

SQLite generated apps use only the Python standard library: argparse, sqlite3, http.server, and json. Postgres generated apps require installing symboliclight[postgres].

10-minute Trial Path

slc check examples/todo_app.sl
slc build examples/todo_app.sl --out build/todo_app.py
python build/todo_app.py test
python build/todo_app.py add "Buy milk"
slc new api my-api --template todo --backend sqlite
slc check my-api/src/app.sl

For a guided first app, read Build a Todo App. For a compact syntax overview, read Language Tour.

Example

app TodoApp {
  intent "./todo.intent.yaml"

  type Todo = {
    id: Id<Todo>,
    title: Text,
    done: Bool,
  }

  store todos: Todo

  command add(title: Text) -> Todo {
    return todos.insert({ title: title, done: false })
  }

  route GET "/todos" -> List<Todo> {
    return todos.all()
  }
}

Typed request bodies and status responses:

route POST "/notes" body CreateNote -> Response<Note> {
  let note = notes.insert({ title: request.body.title, body: request.body.body })
  return response(status: 201, body: note)
}

Multi-file apps use explicit imports:

module models {
  enum Status { open, closed }

  type Issue = {
    id: Id<Issue>,
    title: Text,
    status: Status,
    assignee: Option<Text>,
  }

  fn is_open(status: Status) -> Bool {
    return status == Status.open
  }
}

app IssueTracker {
  import "./models.sl" as models

  store issues: models.Issue

  command create(title: Text) -> models.Issue {
    return issues.insert({ title: title, status: models.Status.open })
  }

  route GET "/open" -> Bool {
    return models.is_open(models.Status.open)
  }
}

Relationship With IntentSpec

IntentSpec describes task intent, permissions, output contracts, and acceptance tests.

SymbolicLight implements the application.

Together:

IntentSpec = what should be built and how it is accepted
SymbolicLight = the application implementation

IntentSpec validation is optional in normal slc check runs. If the intentspec package is installed, SL validates referenced intent files. Missing IntentSpec support is reported as a warning unless --strict-intent is used.

When an app declares test from intent.acceptance, slc test runs a v0.6 offline acceptance bridge after generated app tests pass. It checks SL route and command hints, permission mismatches, and required_sections assertions from the IntentSpec output contract.

Commands

slc check <file.sl>
slc check <file.sl> --json
slc check <file.sl> --no-cache
slc build <file.sl> --out build/app.py
slc build <file.sl> --out build/app.py --no-source-map
slc schema <file.sl> --out build/schema.json
slc run <file.sl> -- add "Buy milk"
slc test <file.sl>
slc fmt <file.sl>
slc doctor <file.sl>
slc doctor <file.sl> --json
slc doctor <file.sl> --db path/to/app.sqlite
slc doctor <file.sl> --db path/to/app.sqlite --json
slc migrate plan <file.sl> --db path-or-url
slc new api <name> --template todo --backend sqlite
slc new api <name> --template project-ops --backend postgres
slc lsp
slc init <dir>
slc new api <name>
slc add route GET /items <file.sl>

Release Check

python scripts/release_check.py --skip-package
python scripts/docs_check.py
python scripts/vscode_check.py
python scripts/freeze_check.py
python scripts/example_matrix.py
python -m build
python scripts/package_smoke.py --gallery
python scripts/release_notes.py --from v0.13.0-rc2 --to HEAD --out build/release-notes-v1.0.0.md
python scripts/release_check.py

For the local v1.0.0 baseline, run the full release check from a clean worktree. The check builds a local wheel, installs it into a temporary environment, runs installed slc against the gallery, exercises a doctor --db fixture where the stored schema hash matches but the SQLite structure is missing a column, runs migration-plan smoke checks, and runs compatibility fixtures for prior v0.x examples. No GitHub, TestPyPI, or PyPI upload is performed by these commands.

Project Status

This repository is prepared as a local v1.0 stable baseline. The goal is to keep typed backend and CLI apps compact, testable, and AI-friendly while still producing readable, runnable Python. Public redistribution is a separate owner decision after reviewing the local release artifacts.