0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: PMPL-1.0-or-later
# 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 **verisimiser**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization

**verisimiser** augments existing databases with VeriSimDB octad capabilities.
It wraps PostgreSQL, SQLite, MongoDB, Redis, and other backends to add eight
octad dimensions (data, metadata, provenance, lineage, constraints, access
control, temporal, simulation) without requiring database migration.

## 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)

## 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 PMPL-1.0-or-later 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. **Tier isolation** - Tier 1 capabilities NEVER write to the target database
10. **Sidecar integrity** - Provenance hash chains are append-only and tamper-evident

## VERISIMISER-SPECIFIC INVARIANTS

- **Octad dimensions**: data, metadata, provenance, lineage, constraints, access-control, temporal, simulation
- **Tier 1 (piggybacks)**: drift detection, provenance tracking, temporal versioning -- sidecar-only
- **Tier 2 (overlays)**: graph, vector, tensor, semantic, document, spatial -- additional storage
- **Supported backends**: PostgreSQL, SQLite, MongoDB, Redis (extensible)
- **VQL-UT**: Type-safe query interface for octad queries

## REPOSITORY STRUCTURE

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

```
verisimiser/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # High-level orientation (Rich Human)
├── ROADMAP.adoc                # Future direction
├── CONTRIBUTING.adoc           # Human contribution guide
├── Justfile                    # Task runner
├── Containerfile               # OCI build
├── Cargo.toml                  # Rust build config
├── LICENSE                     # Primary license (PMPL-1.0-or-later)
├── src/                        # Source code
│   ├── main.rs                 # CLI entry point (clap subcommands)
│   ├── lib.rs                  # Library root
│   ├── manifest/               # TOML manifest parsing
│   ├── tier1/                  # Tier 1 piggyback capabilities
│   │   ├── drift.rs            # Cross-modal drift detection
│   │   ├── provenance.rs       # SHA-256 hash-chain provenance
│   │   └── temporal.rs         # Temporal versioning sidecar
│   ├── tier2/                  # Tier 2 augmentation overlays
│   ├── abi/                    # ABI module (Rust side)
│   ├── intercept/              # Per-database interception strategies
│   └── interface/              # Verified Interface Seams
│       ├── abi/                # Idris2 ABI (The Spec)
│       │   ├── Types.idr       # OctadDimension, DatabaseBackend, etc.
│       │   ├── Layout.idr      # Octad record memory layout
│       │   └── Foreign.idr     # Database connection, overlay, VQL-UT FFI
│       ├── ffi/                # Zig FFI (The Bridge)
│       │   ├── build.zig
│       │   ├── src/main.zig
│       │   └── test/integration_test.zig
│       └── generated/          # C Headers (The Result)
├── container/                  # Stapeln container ecosystem
├── docs/                       # Technical depths
│   ├── attribution/            # Citations, owners, maintainers (adoc)
│   ├── architecture/           # Topology, diagrams, threat model
│   ├── theory/                 # Domain theory
│   └── legal/                  # Legal exhibits and full texts
└── .machine_readable/          # ALL machine-readable metadata
    └── 6a2/                    # STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
```

## 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 verisimiser. 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. Tier 1 capabilities
never write to the target database."**