diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/SECURITY.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index 8089d3c..cdcdabe 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the oblibeniser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..8df1057 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,36 @@ +== TEST-NEEDS.md — oblibeniser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Integration tests (Rust) |1 |`+tests/integration_tests.rs+` + +|Verification tests |Unit-level |`+verification/tests/+` directory +present + +|FFI tests |Present |`+src/interface/ffi/test/+` +|=== + +=== What’s Covered + +* [x] Integration test framework in place +* [x] FFI interface verification tests +* [x] Cargo-based test execution + +=== Still Missing (for CRG B+) + +* [ ] Property-based testing (proptest) +* [ ] Fuzzing targets +* [ ] Performance benchmarks +* [ ] Cross-platform CI matrix + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/oblibeniser && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 9523cac..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ -# TEST-NEEDS.md — oblibeniser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Integration tests (Rust) | 1 | `tests/integration_tests.rs` | -| Verification tests | Unit-level | `verification/tests/` directory present | -| FFI tests | Present | `src/interface/ffi/test/` | - -## What's Covered - -- [x] Integration test framework in place -- [x] FFI interface verification tests -- [x] Cargo-based test execution - -## Still Missing (for CRG B+) - -- [ ] Property-based testing (proptest) -- [ ] Fuzzing targets -- [ ] Performance benchmarks -- [ ] Cross-platform CI matrix - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/oblibeniser && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 70% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 83ac357..4aa56b0 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,18 @@ - - -# TOPOLOGY.md — oblibeniser +== TOPOLOGY.md — oblibeniser -## Purpose +=== Purpose -oblibeniser makes state-mutating operations reversible and auditable via Oblíbený (Czech: "favourite"). Every operation targeted by an `oblibeniser.toml` manifest gets an automatic inverse function, enabling undo/redo with configurable stack depth, hash-chained audit trails for tamper-evident logging, and time-travel debugging by navigating operation history. It targets systems where correctability and auditability are first-class requirements. +oblibeniser makes state-mutating operations reversible and auditable via +Oblíbený (Czech: "`favourite`"). Every operation targeted by an +`+oblibeniser.toml+` manifest gets an automatic inverse function, +enabling undo/redo with configurable stack depth, hash-chained audit +trails for tamper-evident logging, and time-travel debugging by +navigating operation history. It targets systems where correctability +and auditability are first-class requirements. -## Module Map +=== Module Map -``` +.... oblibeniser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, build, run, info @@ -20,11 +24,11 @@ oblibeniser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... oblibeniser.toml manifest │ ┌────▼────┐ @@ -40,4 +44,4 @@ oblibeniser.toml manifest │ Codegen │ emit generated/oblibeniser/ (inverse wrappers, audit trail module, │ │ verification script, undo/redo stack) └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 58% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 60bb914..04d615c 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,10 +1,8 @@ - - -# oblibeniser — Topology +== oblibeniser — Topology -## Data Flow +=== Data Flow -``` +.... User manifest (oblibeniser.toml) | v @@ -39,11 +37,11 @@ User manifest (oblibeniser.toml) | v Generated output (reversible operation wrappers in target language) -``` +.... -## Reversible Operation Lifecycle +=== Reversible Operation Lifecycle -``` +.... 1. RECORD oblibeniser_record_forward(handle, name, pre_snapshot) -> assigns operation ID, captures pre-state @@ -66,36 +64,62 @@ User manifest (oblibeniser.toml) 8. TIME-TRAVEL oblibeniser_time_travel(handle, target_op_id) -> rewind by applying inverses down the stack -``` - -## Module Map - -| Module | Location | Purpose | -|--------|----------|---------| -| CLI | `src/main.rs` | Command-line interface (init, validate, generate, build, run, info) | -| Library | `src/lib.rs` | Library root (re-exports manifest, codegen, abi) | -| Manifest | `src/manifest/` | Parse and validate `oblibeniser.toml` | -| Codegen | `src/codegen/` | Generate reversible wrappers | -| ABI Types | `src/interface/abi/Types.idr` | ReversibleOperation, InverseProof, AuditEntry, StateSnapshot, UndoStack | -| ABI Layout | `src/interface/abi/Layout.idr` | C-ABI struct layouts with alignment proofs | -| ABI Foreign | `src/interface/abi/Foreign.idr` | FFI function declarations | -| FFI Impl | `src/interface/ffi/src/main.zig` | Zig implementation of all FFI functions | -| FFI Build | `src/interface/ffi/build.zig` | Zig build configuration | -| FFI Tests | `src/interface/ffi/test/integration_test.zig` | Integration tests | - -## Key Types (Idris2 ABI) - -| Type | Size | Align | Purpose | -|------|------|-------|---------| -| `StateSnapshot` | 40 bytes | 8 | Pre/post state capture | -| `ReversibleOperation` | variable | 8 | Forward op + snapshots + inverse flag | -| `AuditEntry` | 64 bytes | 8 | Hash-chained audit record | -| `UndoStack` | 24 bytes | 8 | Bounded LIFO operation history | -| `InverseProof` | (type-level) | — | Dependent type proving `inverse(forward(x)) = x` | - -## Ecosystem Position - -``` +.... + +=== Module Map + +[width="100%",cols="30%,37%,33%",options="header",] +|=== +|Module |Location |Purpose +|CLI |`+src/main.rs+` |Command-line interface (init, validate, generate, +build, run, info) + +|Library |`+src/lib.rs+` |Library root (re-exports manifest, codegen, +abi) + +|Manifest |`+src/manifest/+` |Parse and validate `+oblibeniser.toml+` + +|Codegen |`+src/codegen/+` |Generate reversible wrappers + +|ABI Types |`+src/interface/abi/Types.idr+` |ReversibleOperation, +InverseProof, AuditEntry, StateSnapshot, UndoStack + +|ABI Layout |`+src/interface/abi/Layout.idr+` |C-ABI struct layouts with +alignment proofs + +|ABI Foreign |`+src/interface/abi/Foreign.idr+` |FFI function +declarations + +|FFI Impl |`+src/interface/ffi/src/main.zig+` |Zig implementation of all +FFI functions + +|FFI Build |`+src/interface/ffi/build.zig+` |Zig build configuration + +|FFI Tests |`+src/interface/ffi/test/integration_test.zig+` |Integration +tests +|=== + +=== Key Types (Idris2 ABI) + +[width="100%",cols="22%,21%,25%,32%",options="header",] +|=== +|Type |Size |Align |Purpose +|`+StateSnapshot+` |40 bytes |8 |Pre/post state capture + +|`+ReversibleOperation+` |variable |8 |Forward op + snapshots + inverse +flag + +|`+AuditEntry+` |64 bytes |8 |Hash-chained audit record + +|`+UndoStack+` |24 bytes |8 |Bounded LIFO operation history + +|`+InverseProof+` |(type-level) |— |Dependent type proving +`+inverse(forward(x)) = x+` +|=== + +=== Ecosystem Position + +.... iseriser (meta-framework) | +-- typedqliser (#1 priority) @@ -106,4 +130,4 @@ iseriser (meta-framework) | +-- proven (shared Idris2 library) +-- typell (type theory engine) -``` +.... diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..7c0bcbe --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — oblibeniser (Developer) + +=== What is oblibeniser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 7ddd90f..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — oblibeniser (Developer) - -## What is oblibeniser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..1277e36 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — oblibeniser (User) + +=== What is oblibeniser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 014ab6f..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — oblibeniser (User) - -## What is oblibeniser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture