ALP

Appearance

ALP Specification — Compliance Test Suite ​

Version: 80.0.0 Status: Stable

1. Compliance Overview ​

mermaid
flowchart TD
    Suite[Compliance Suite] --> Valid[Valid Fixtures]
    Suite --> Invalid[Invalid Fixtures]
    Valid --> Pass[Parser MUST Accept]
    Invalid --> Fail[Parser MUST Reject]
    Suite --> Categories[Test Categories]
    Categories --> Schema[Schema Validation]
    Categories --> Graph[Dependency Graph]
    Categories --> Policy[Policy Enforcement]
    Categories --> Lifecycle[Lifecycle State Machine]

2. Overview ​

The ALP Compliance Test Suite provides a standardized set of test fixtures to ensure that custom parser implementations conform to the ALP v1.0.0 specification.

Because ALP uses strict indentation, typed object validation, and complex dependency graph resolution, subtle parsing errors can lead to corrupt agent contexts. Passing the compliance suite guarantees interoperability across the ecosystem.

2. Test Suite Structure ​

The compliance suite is organized into two primary categories: valid and invalid.

tests/compliance/
├── valid/
│   ├── 01-minimal.alp
│   ├── 02-all-types.alp
│   ├── 03-multiline-strings.alp
│   └── ... (and their expected output ASTs in JSON)
└── invalid/
    ├── 01-bad-indent.alp
    ├── 02-missing-id.alp
    ├── 03-tab-characters.alp
    └── ... (and their expected error codes)

3. Valid Test Cases ​

Files in the valid/ directory MUST be parsed without errors.

For strict compliance, parser developers SHOULD compare their parser's internal Abstract Syntax Tree (AST) output against the provided .json baseline files in the directory to ensure properties, lists, and multi-line strings were extracted correctly.

Key Validation Areas: ​

  • Preservation of leading whitespace in multi-line strings.
  • Correct merging of block properties and nested blocks.
  • Accurate identification of inline_id vs id property.
  • Successful resolution of ALPEL interpolation nodes ${ }.

4. Invalid Test Cases ​

Files in the invalid/ directory MUST trigger a parser error. The parser MUST halt and reject the file.

Error Reporting Requirements ​

To pass the compliance suite, a parser MUST report errors that include:

  1. Line number of the violation.
  2. Column number (if applicable).
  3. Error Category (e.g., SyntaxError, IndentationError, ValidationError).

Key Violation Areas: ​

  • Tabs: Any \t character used for indentation MUST throw an IndentationError.
  • Indentation Levels: A property indented by 3 spaces (instead of 2) MUST throw an IndentationError.
  • Missing Required Fields: A @task without an id MUST throw a ValidationError.
  • Unclosed Strings: A missing closing quote MUST throw a SyntaxError.
  • Invalid Enums: Passing priority: extreme MUST throw a ValidationError.

5. Running the Suite ​

A standard compliance harness will be provided as a CLI tool (alp-test-harness).

Parser authors can run their parser against the suite by providing an executable that takes a file path as input and outputs the AST as JSON to stdout, or outputs error details to stderr.

bash
alp-test-harness --executable="./my-custom-parser"