From 884aab6eb281d480caa126f9367ba15bf70f55dc Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 17 Aug 2026 17:00:08 +0100 Subject: [PATCH] Rename README.md to README.adoc Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- README.adoc | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 179 -------------------------------------------------- 2 files changed, 183 insertions(+), 179 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..50f3067 --- /dev/null +++ b/README.adoc @@ -0,0 +1,183 @@ +// SPDX-License-Identifier: MPL-2.0 += JanusKey — Reversible File Operations +:toc: preamble +:toc-title: Contents +:icons: font +:doctype: article + +image:https://img.shields.io/badge/OpenSSF-BestPractices-green[link="https://www.bestpractices.dev/projects/XXXX"] + +A Rust CLI for file operations that carry their own inversion metadata. Undo deletes, modifications, and moves in milliseconds without external backups. Formal proofs of complete reversibility are pending. + +== Overview + +JanusKey is a file operation utility suite that pursues complete reversibility through architectural design. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for inversion—the goal is to make data loss architecturally impossible. + +Every `jk delete`, `jk modify`, or `jk move` stores the inverse operation in an append-only log backed by content-addressed storage (SHA-256). Rolling back is a metadata lookup, not a filesystem search or a tape restore. + +[CAUTION] +==== +**Formal proofs of complete reversibility are pending.** The engineering mechanism (inversion metadata) is implemented in Rust. The mathematical guarantee that this construction makes data loss impossible under all allowed operations has not yet been mechanically verified. See link:EXPLAINME.adoc#_reversibility_guarantee[EXPLAINME §Reversibility guarantee]. +==== + +== What is standard and what is ours + +[cols="1,2,2", options="header"] +|=== +| Concept | Status | Home + +| Content-addressed storage (SHA-256) +| Standard (Git, IPFS, Nix) +| Storage layer + +| Append-only operation log +| Standard (event sourcing, WAL) +| Metadata store + +| Transactional commit/rollback +| Standard (databases) +| Transaction manager + +| CLI for reversible file operations +| Standard (various undo/trash utilities) +| `jk` command suite + +| Inversion metadata attached to every operation +| **Novel packaging** (operations carry their own inverse) +| Operation layer + +| Maximal Principle Reduction (MPR) +| **Novel vocabulary** for "secure by construction" +| Design philosophy +|=== + +== The reversibility mechanism + +Every operation stores sufficient metadata for inversion: + +[cols="1,2", options="header"] +|=== +| Operation | Inversion metadata stored + +| Delete +| Full file content + metadata in content-addressed storage + +| Modify +| Original content hash + location in content store + +| Move +| Original path + +| Copy +| Destination path +|=== + +Rollback is an lookup-then-execute operation against the append-only log, bounded by metadata retrieval time (milliseconds), not filesystem scan time. + +== The secure obliteration exception + +Reversibility is the default. Secure obliteration (`jk shred`) is the deliberate, explicit exception. It is best-effort only: + +* Overwrite-in-place cannot guarantee physical erasure on SSDs (wear leveling), CoW filesystems (ZFS, Btrfs), or journaling filesystems. +* The threat model for `shred` assumes spinning-rust physical media. On modern media, physical destruction is the only guaranteed obliteration. + +== Commands + +[cols="1,2", options="header"] +|=== +| Command | Description + +| `jk init` +| Initialize JanusKey in current directory + +| `jk delete ` +| Delete files (reversible) + +| `jk modify ` +| Modify files with sed-like syntax + +| `jk move ` +| Move/rename files + +| `jk copy ` +| Copy files + +| `jk undo [--count N]` +| Undo last operation(s) + +| `jk begin [name]` +| Start a transaction + +| `jk commit` +| Commit current transaction + +| `jk rollback` +| Rollback current transaction + +| `jk preview` +| Preview pending changes + +| `jk history` +| Show operation history + +| `jk status` +| Show current status +|=== + +== Architecture + +┌────────────────────────────┐ +│ JanusKey CLI │ jk delete, jk modify, jk move +├────────────────────────────┤ +│ Operation Layer │ Generates inverse metadata +├────────────────────────────┤ +│ Transaction Manager │ Groups ops, commit/rollback +├────────────────────────────┤ +│ Metadata Store │ Append-only operation log +├────────────────────────────┤ +│ Content-Addressed Storage │ SHA-256, deduplication +└────────────────────────────┘ + +== Known scope boundaries + +[CAUTION] +==== +**Formal proofs are pending.** The claim "data loss is architecturally impossible" is an engineering intent supported by the inversion-metadata mechanism. It is not yet a mechanically verified theorem. The `src/abi/` and `idrisiser/` directories suggest Idris 2 specification targets, but these are not yet discharging the reversibility guarantee. +==== + +[CAUTION] +==== +**Secure obliteration is best-effort.** `jk shred` cannot guarantee physical erasure on SSD, CoW, or journaling filesystems. This is a physical constraint, not a software bug. +==== + +[CAUTION] +==== +**MPR is design vocabulary, not a verified method.** Maximal Principle Reduction describes the design philosophy of eliminating vulnerability by construction (no irreversible code path exists). It is not a formal method with mechanical tooling in this repo. +==== + +== Build + +[source,bash] +---- +# Build from source (requires Rust) +cargo build --workspace --release + +# Initialize +jk init + +# Run tests +cargo test --workspace +---- + +== Documentation + +* link:EXPLAINME.adoc[EXPLAINME] — claim-by-claim receipts and known gaps +* link:Glossary.adoc[Glossary] — terminology reference +* `ARCHITECTURE.md` — architecture map and completion dashboard +* `ROADMAP.adoc` — development roadmap + +== License + +SPDX-License-Identifier: MPL-2.0 — see link:LICENSE[LICENSE]. + +Prose documentation is licensed under CC-BY-SA-4.0; see `LICENSES/`. diff --git a/README.md b/README.md deleted file mode 100644 index 2ee7ab6..0000000 --- a/README.md +++ /dev/null @@ -1,179 +0,0 @@ - - -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) -[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) - -Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> -:toc: macro :icons: font :source-highlighter: rouge :experimental: -:url-github: :url-gitlab: - :url-bitbucket: - :url-codeberg: - - -**Reversible File Operations (formal proofs pending) Through Maximal -Principle Reduction** - -[![RSR Certified](https://img.shields.io/badge/RSR-Certified-gold)](https://github.com/hyperpolymath/rhodium-standard-repositories) - -
- -
- -# Overview - -JanusKey is a file operation utility suite that pursues complete -reversibility through architectural design rather than logging or -backups. Unlike traditional backup systems that restore from external -state, JanusKey operations carry sufficient information for inversion — -the goal is to make data loss architecturally impossible (formal proofs -pending). - -## Key Features - -- **Reversible by design** - Every operation carries inversion metadata - (formal proofs pending) - -- **Instant Rollback** - Undo changes in milliseconds - -- **Data loss resistant by construction** - reversibility is the - architectural goal the pending proofs are to establish. (Note: *secure - obliteration* is the deliberate exception and is best-effort only — - overwrite-in-place cannot guarantee physical erasure on SSD/CoW/journaling - media; see the threat model.) - -- **Complete Audit Trail** - Every change tracked automatically - -- **Transaction Support** - Group operations, commit/rollback together - -- **Content-Addressed Storage** - SHA256 hashing with deduplication - -# Quick Start - -```bash -# Build from source (requires Rust) -cargo build --workspace --release - -# Initialize JanusKey in your project -jk init - -# Delete files (reversible) -jk delete *.log - -# Undo the delete -jk undo - -# Transactions for batch operations -jk begin -jk delete temp*.txt -jk modify "s/DEBUG/INFO/g" config.yaml -jk preview # Review changes -jk commit # Or: jk rollback -``` - -# Commands - -| Command | Description | -|----|----| -| `jk` `init` | Initialize JanusKey in current directory | -| `jk` `delete` `` | Delete files (reversible) | -| `jk` `modify` `` `` | Modify files with sed-like syntax | -| `jk` `move` `` `` | Move/rename files | -| `jk` `copy` `` `` | Copy files | -| `jk` `undo` `[--count` `N]` | Undo last operation(s) | -| `jk` `begin` `[name]` | Start a transaction | -| `jk` `commit` | Commit current transaction | -| `jk` `rollback` | Rollback current transaction | -| `jk` `preview` | Preview pending changes | -| `jk` `history` | Show operation history | -| `jk` `status` | Show current status | - -# Architecture - -JanusKey implements **Maximal Principle Reduction (MPR)**, a security -methodology where vulnerability elimination occurs by construction -rather than verification. - - +----------------------------+ - | JanusKey CLI | <-- jk delete, jk modify, jk move - +----------------------------+ - | Operation Layer | <-- Generates inverse metadata - +----------------------------+ - | Transaction Manager | <-- Groups ops, commit/rollback - +----------------------------+ - | Metadata Store | <-- Append-only operation log - +----------------------------+ - | Content-Addressed Storage | <-- SHA256, deduplication - +----------------------------+ - -## Reversibility Guarantee - -Every operation stores sufficient metadata for perfect inversion: - -- **Delete**: Stores full content + metadata for restoration - -- **Modify**: Stores original content hash for rollback - -- **Move**: Stores original path for unmove - -- **Copy**: Destination path for deletion - -# Installation - -## From Source (Rust) - -```bash -# Clone the repository -git clone {url-github} -cd januskey - -# Build release binary -cargo build --workspace --release - -# Install to PATH -cargo install --path . -``` - -# Mirrors - -| Platform | URL | -|------------------|-----------------| -| GitHub (primary) | {url-github} | -| GitLab | {url-gitlab} | -| Bitbucket | {url-bitbucket} | -| Codeberg | {url-codeberg} | - -# License - -This project is licensed under the Mozilla Public License, v. 2.0. See -the `LICENSE` file for details. - -SPDX-License-Identifier: CC-BY-SA-4.0 - -# Contributing - -See CONTRIBUTING. - -# Research - -JanusKey is based on research into reversible computing (formal proofs -are a target, not yet complete) and Maximal Principle Reduction. See the -white paper in `docs/` for formal proofs and theoretical foundations. - -# Metadata - -- Domain: software-development - -- Framework: RSR (Rhodium Standard Repository) - -- Language: Rust - -- Dublin Core: .well-known/dc.xml - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard.