docs: bespoke architecture, roadmap, topology, and ABI definitions for atsiser

Replace all template placeholders. Architecture: C source → ATS2 linear type
wrapping engine. Idris2 ABI defines LinearPtr, Viewtype, OwnershipState,
AllocationSite, BufferBounds with formal proofs. Zig FFI implements C analysis,
ownership graph construction, ATS2 generation, and round-trip compilation.
TOPOLOGY.md documents module map and data flow. ROADMAP covers 7 phases from
scaffold through ecosystem integration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for atsiser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -17,11 +17,13 @@ can-create-files = true
 
 [agent-constraints]
 # What AI agents must NOT do:
-# - Never use banned language patterns (believe_me, unsafeCoerce, etc.)
+# - Never use banned language patterns (believe_me, unsafeCoerce, $UNSAFE, etc.)
 # - Never commit secrets or credentials
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never generate ATS2 code that bypasses linear type discipline
+# - Never emit $UNSAFE casts in generated ATS2 wrappers
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,21 +1,23 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for atsiser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
+# Custom symbolic rules for atsiser
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "no-ats2-unsafe", pattern = "\\$UNSAFE", severity = "critical" }
+# - { name = "ownership-completeness", pattern = "malloc.*without.*free", severity = "warning" }
 
 [neural-config]
 # Neural pattern detection settings

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,25 +1,25 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for atsiser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "ci-triggered"
+target = "binary"  # Rust CLI binary + Zig shared library
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
 # 3. Run `just validate` to check compliance
 # 4. Run `just security` to audit for vulnerabilities
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Justfile
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
 # 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
 # 4. Tag and push

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,33 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "atsiser")
-    (description "Wrap C codebases in ATS linear types for zero-cost memory safety")
+    (description "Wrap C codebases in ATS2 linear types for zero-cost memory safety")
     (status "scaffold")
     (priority "—")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "scaffold-documented")
+    (completion-percentage 10)
+    (milestone "Architecture documented, ABI/FFI bespoke, all placeholders replaced"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "C source analysis — parse headers, identify allocation patterns, track ownership")
+    (step 2 "ATS2 wrapper generation — viewtype annotations, dataviewtype state machines")
+    (step 3 "Proof generation — praxi/prfun obligations for ownership and bounds")
+    (step 4 "Round-trip compilation — ATS2 → C with zero overhead verification")
+    (step 5 "Idris2 meta-proofs — prove generated ATS2 proofs are sound")
+    (step 6 "Ecosystem — BoJ cartridge, PanLL panels, CI/CD integration"))
 
   (blockers-and-issues
     (none "Project is in scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement C header parsing in src/core/")
+    (action "Implement allocation pattern detection (malloc/free pairing)")
+    (action "First working end-to-end example: simple C library → ATS2 wrapper")))

.machine_readable/ai/AI.a2ml

@@ -1,14 +1,22 @@
 
-# AI Assistant Instructions
+# AI Assistant Instructions for atsiser
 
 ## Repository Focus
-- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative.
+- `atsiser` wraps C codebases in ATS2 linear types for zero-cost memory safety.
+- Follows the hyperpolymath -iser pattern: manifest → analysis → Idris2 ABI → Zig FFI → codegen.
 - All machine-readable content lives under `.machine_readable/` — state files (a2ml), bot directives, and contractiles.
 - Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing.
 
+## Domain Knowledge
+- ATS2 viewtypes track pointer ownership at the type level (linear types).
+- `dataviewtype` encodes resource state machines (allocated → borrowed → freed).
+- `praxi`/`prfun` are proof-level functions — they generate zero runtime code.
+- Ownership graphs must be acyclic for a valid deallocation order to exist.
+- The Idris2 ABI layer proves meta-properties about the generated ATS2 code.
+
 ## Workflow
-1. Inspect `.machine_readable/STATE.a2ml` for blockers and next actions.
-2. Respect any constraints listed inside `.machine_readable/AGENTIC.a2ml` when tooling changes are requested.
+1. Inspect `.machine_readable/6a2/STATE.a2ml` for blockers and next actions.
+2. Respect any constraints listed inside `.machine_readable/6a2/AGENTIC.a2ml` when tooling changes are requested.
 3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message.
 
 ## Delivery Promises

.machine_readable/anchors/ANCHOR.a2ml

@@ -5,7 +5,7 @@
 
 [metadata]
 version = "1.0.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [anchor]
 schema = "hyperpolymath.anchor/1"
@@ -19,18 +19,19 @@ purpose = [
 ]
 
 [identity]
-project = "{{PROJECT_NAME}}"
-kind = "{{PROJECT_KIND}}"                # language | library | service | tool
-one-sentence = "{{PROJECT_PURPOSE}}"
-domain = "{{PROJECT_DOMAIN}}"
+project = "atsiser"
+kind = "tool"
+one-sentence = "Wrap C codebases in ATS2 linear types for zero-cost memory safety"
+domain = "memory-safety, linear-types, C-interop, formal-verification"
 
 [semantic-authority]
 policy = "canonical"
 
 owns = [
-  "Project semantics and specification",
-  "Invariant definitions and contractiles",
-  "Reference implementation behavior",
+  "C source analysis and allocation pattern detection",
+  "ATS2 viewtype/dataviewtype wrapper generation",
+  "Ownership graph construction and proof obligation emission",
+  "Round-trip ATS2-to-C compilation with zero overhead verification",
 ]
 
 [implementation-policy]

0-AI-MANIFEST.a2ml

@@ -1,14 +1,20 @@
-# ⚠️ STOP - CRITICAL READING REQUIRED
+# STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
 
 ## WHAT IS THIS?
 
-This is the AI manifest for **[YOUR-REPO-NAME]**. It declares:
+This is the AI manifest for **atsiser**. It declares:
 - Canonical file locations (where things MUST be, and nowhere else)
 - Critical invariants (rules that must NEVER be violated)
 - Repository structure and organization
 
+**atsiser** wraps existing C codebases in ATS2 linear types for zero-cost
+memory safety. It analyses C source code, identifies memory-critical patterns
+(malloc/free pairs, buffer accesses, pointer arithmetic), generates ATS2
+wrappers with viewtype/dataviewtype annotations, and compiles them back to C
+with all proofs erased — zero runtime overhead.
+
 ## CANONICAL LOCATIONS (UNIVERSAL RULE)
 
 ### Machine-Readable Metadata: `.machine_readable/` ONLY
@@ -55,7 +61,7 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 ### AI Configuration & Guides: `.machine_readable/ai/` ONLY
 
 - `AI.a2ml` - Language-specific or LLM-specific patterns
-- `PLACEHOLDERS.md` - Bootstrap guide
+- `PLACEHOLDERS.adoc` - Bootstrap guide
 
 ### Community & Forge Metadata: `.github/` ONLY
 
@@ -80,41 +86,47 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 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. **ATS2 safety** - Generated ATS2 code must never use `$UNSAFE` casts or bypass linear type discipline
 
 ## REPOSITORY STRUCTURE
 
 This repo follows the **Dual-Track** architecture:
 
 ```
-[YOUR-REPO-NAME]/
+atsiser/
 ├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
-├── README.adoc                 # High-level orientation (Rich Human)
-├── ROADMAP.adoc                # Future direction
+├── README.adoc                 # What atsiser does, architecture, CLI commands
+├── ROADMAP.adoc                # 7-phase roadmap (C analysis → ATS2 generation → proofs)
+├── TOPOLOGY.md                 # Module map and data flow diagram
 ├── CONTRIBUTING.adoc           # Human contribution guide
 ├── GOVERNANCE.adoc             # Decision-making model
 ├── Justfile                    # Task runner
-├── Containerfile               # OCI build
-├── LICENSE                     # Primary license
+├── Containerfile               # OCI build (Chainguard base)
+├── Cargo.toml                  # Rust CLI dependencies
+├── LICENSE                     # PMPL-1.0-or-later
 ├── src/                        # Source code
+│   ├── main.rs                 # CLI entry point
+│   ├── lib.rs                  # Library API
+│   ├── manifest/               # atsiser.toml parser
+│   ├── codegen/                # ATS2 wrapper generation
+│   ├── core/                   # C source analysis engine
 │   └── interface/              # Verified Interface Seams
-│       ├── abi/                # Idris2 ABI (The Spec)
-│       ├── ffi/                # Zig FFI (The Bridge)
-│       └── generated/          # C Headers (The Result)
+│       ├── abi/                # Idris2 ABI (proves memory safety properties)
+│       │   ├── Types.idr       # LinearPtr, Viewtype, OwnershipState, BufferBounds
+│       │   ├── Layout.idr      # Struct layout with per-field ownership
+│       │   └── Foreign.idr     # C analysis + ATS2 compilation FFI
+│       ├── ffi/                # Zig FFI (C-ABI bridge)
+│       └── generated/          # Auto-generated C headers
 ├── container/                  # Stapeln container ecosystem
-├── docs/                       # Technical depths
-│   ├── attribution/            # Citations, owners, maintainers (adoc)
-│   ├── architecture/           # Topology, diagrams
-│   ├── theory/                 # Domain theory
-│   └── practice/               # Manuals
-├── docs/legal/                  # Legal exhibits and full texts
+├── docs/                       # Technical documentation
 └── .machine_readable/          # ALL machine-readable metadata
 ```
 
 ## SESSION STARTUP CHECKLIST
 
-✅ Read THIS file (0-AI-MANIFEST.a2ml) first
-✅ Understand canonical location: `.machine_readable/`
-✅ State understanding of canonical locations
+Read THIS file (0-AI-MANIFEST.a2ml) first
+Understand canonical location: `.machine_readable/`
+State understanding of canonical locations
 
 ## ATTESTATION PROOF