0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

# STOP — CRITICAL READING REQUIRED

**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

## WHAT IS THIS?

This is the AI manifest for **lustreiser**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization

Lustreiser generates formally verified real-time embedded code via Lustre, the
synchronous dataflow language used in avionics (SCADE), nuclear reactor
protection, and automotive safety systems. It analyses control logic, extracts
dataflow patterns, generates Lustre nodes with clock calculus, and compiles to
deterministic C for embedded targets — with Idris2-proven timing bounds.

## CANONICAL LOCATIONS (UNIVERSAL RULE)

### Machine-Readable Metadata: `.machine_readable/` ONLY

These 6 a2ml files MUST exist in `.machine_readable/6a2/` directory ONLY:
1. **STATE.a2ml** - Project state, progress, blockers
2. **META.a2ml** - Architecture decisions, governance
3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
4. **AGENTIC.a2ml** - AI agent interaction patterns
5. **NEUROSYM.a2ml** - Neurosymbolic integration config
6. **PLAYBOOK.a2ml** - Operational runbook

**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.

### Anchor File: `.machine_readable/anchors/ANCHOR.a2ml` ONLY

Canonical authority and semantic-boundary declaration MUST exist at:

` .machine_readable/anchors/ANCHOR.a2ml `

Do not place `ANCHOR.a2ml` at repository root.

### Maintenance Policies: `.machine_readable/policies/` ONLY

Canonical maintenance/governance files MUST exist under:

` .machine_readable/policies/ `

Minimum required files:
- `MAINTENANCE-AXES.a2ml`
- `MAINTENANCE-CHECKLIST.a2ml`
- `SOFTWARE-DEVELOPMENT-APPROACH.a2ml`

Do not place maintenance policy files in repository root.

### Bot Directives: `.machine_readable/bot_directives/` ONLY

Bot-specific instructions for your automated agents.

### Contractiles: `.machine_readable/contractiles/` ONLY

Policy enforcement contracts (k9, dust, lust, must, trust).

### AI Configuration & Guides: `.machine_readable/ai/` ONLY

- `AI.a2ml` - Language-specific or LLM-specific patterns
- `PLACEHOLDERS.adoc` - Bootstrap guide

### Community & Forge Metadata: `.github/` ONLY

- `CODEOWNERS` - Review assignments
- `MAINTAINERS` - Machine-readable contact list
- `SUPPORT` - Support channels
- `SECURITY.md` - Technical security policy
- `CONTRIBUTING.md` - Technical contribution manual
- `CODE_OF_CONDUCT.md` - Conduct rules

### Agent Instructions

- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## DOMAIN CONTEXT

### Lustre Language Background

Lustre is a **synchronous dataflow language** for safety-critical real-time systems.

Key concepts:
- **Nodes**: Functions that transform streams of values at each clock tick
- **Streams**: Infinite sequences of typed values, one per clock tick
- **Temporal operators**: `pre` (previous value), `fby` (followed-by), `->` (initialisation)
- **Clock calculus**: `when` (downsample), `merge` (recombine) — type-level sampling rates
- **Synchronous hypothesis**: All computations complete before the next tick

### Safety Standards

Generated code must be suitable for certification under:
- **DO-178C** — Software for airborne systems (avionics)
- **IEC 61508** — Functional safety of electrical/electronic systems (industrial/nuclear)
- **ISO 26262** — Functional safety of road vehicles (automotive)

### Architecture

```
lustreiser.toml → Rust CLI → Control Flow Analysis → Idris2 ABI (timing proofs)
    → Lustre Codegen (.lus) → Deterministic C (no malloc, no recursion)
    → Zig FFI Bridge
```

## CORE INVARIANTS

1. **No state file duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc.
2. **Single source of truth** - `.machine_readable/` is authoritative
3. **No stale metadata** - If root state files exist, they are OUT OF DATE
4. **License consistency** - All code MPL-2.0 unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`)
7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile`
8. **Container orchestration** - `selur-compose`, never `docker-compose`
9. **Deterministic C output** - Generated C must never use malloc, recursion, or unbounded loops
10. **Timing proofs required** - Every generated node must have an Idris2-verified WCET bound

## REPOSITORY STRUCTURE

This repo follows the **Dual-Track** architecture:

```
lustreiser/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # High-level orientation (Rich Human)
├── ROADMAP.adoc                # Phased development plan
├── CONTRIBUTING.adoc           # Human contribution guide
├── Justfile                    # Task runner
├── Containerfile               # OCI build
├── Cargo.toml                  # Rust dependencies
├── LICENSE                     # MPL-2.0
├── src/                        # Source code
│   ├── main.rs                 # CLI entry point
│   ├── lib.rs                  # Library API
│   ├── manifest/               # lustreiser.toml parser
│   ├── codegen/                # Lustre node generation
│   ├── abi/                    # Rust-side ABI types
│   └── interface/              # Verified Interface Seams
│       ├── abi/                # Idris2 ABI (timing proofs, clock calculus)
│       │   ├── Types.idr       # LustreNode, Clock, DataflowStream, WCET
│       │   ├── Layout.idr      # Stream buffer memory layout proofs
│       │   └── Foreign.idr     # Lustre compilation FFI declarations
│       ├── ffi/                # Zig FFI (C-ABI bridge)
│       │   ├── build.zig
│       │   ├── src/main.zig    # Lustre compilation and timing FFI
│       │   └── test/           # Integration tests
│       └── generated/          # Auto-generated C headers
├── container/                  # Stapeln container ecosystem
├── docs/                       # Technical documentation
│   ├── architecture/           # Topology, dataflow diagrams
│   └── theory/                 # Lustre semantics, clock calculus
└── .machine_readable/          # ALL machine-readable metadata
    └── 6a2/                    # STATE, META, ECOSYSTEM, etc.
```

## SESSION STARTUP CHECKLIST

1. Read THIS file (0-AI-MANIFEST.a2ml) first
2. Understand canonical location: `.machine_readable/`
3. State understanding of canonical locations
4. Read `.machine_readable/6a2/STATE.a2ml` for current project state

## ATTESTATION PROOF

**"I have read the AI manifest for lustreiser. All machine-readable content
(state files, anchors, policies, bot directives, contractiles, AI guides) is
located in `.machine_readable/` ONLY, and community metadata is in `.github/`.
I will not create duplicate files in the root directory. I understand that
generated C code must be deterministic and that timing proofs are mandatory."**