Marid

Julia-first framework for web applications, APIs, and reactive scientific dashboards, with interoperable protocols and frontend independence.

Table of Contents

• What this is
• Quick start
• Local governed HTTP/JSON checkpoint
• AI-Assisted Installation
• What you get
• Repository map
• Where to go next
• Licence

What this is

Marid is an experimental Julia-first framework with thirteen independently scoped packages, a framework-independent browser client and a relationship explorer. The canonical project brief defines acceptance; the charter defines build order.

Warning

Prototype implementation exists, but release gates are not accepted. In-memory unit tests do not prove ArangoDB, GraphQL, gRPC or browser interoperability. The previous Gate 5 production-ready claim is superseded by the evidence ledger. See that ledger for the latest local results, explicit unsupported features and external CI blockers.

This repository is a Rhodium Standard Repository (RSR) monorepo: the Marid program paths (PROJECT_BRIEF.md, packages/, web/, contracts/, fixtures/, examples/, test/) are carried alongside machine-readable project metadata, an AI-agent gatekeeper protocol, CI/CD, and governance infrastructure.

Quick start

git clone https://github.com/metadatastician/marid.git
cd marid

# Check the repo satisfies the RSR shape:
just validate            # structure + metadata checks

# Read the contract before anything else:
#   PROJECT_BRIEF.md     # the product/engineering contract (§1–§9)
#   AGENTS.md              # repository instructions for coding agents
#   docs/agent-launch.adoc # the Gate 0 kickoff assignment

Julia and Bun local test versions are pinned in mise.toml. Julia packages have independent environments; there is intentionally no root Project.toml. The AffineScript toolchain/build is not yet proven and remains a Gate 0 blocker.

Local governed HTTP/JSON checkpoint

The unary HTTP example now binds its actual listener and generated policy to one IR descriptor. It uses HTTP.jl and JSON3; there is no real persistence or application authentication in this demonstration.

The CLI supports explicit legacy globals and opt-in --deny-by-default. Strict mode requires the separately delivered gateway patch, not unmodified upstream. See reproduction and deployment limits and the ordered evidence ledger. Full gateway CI and security dependencies remain blockers; no container deployment is claimed.

AI-Assisted Installation

If you are an AI agent installing this project, read the AI installation guide first — it gives the orientation order, the full prompt sequence, and the privacy notice.

The one trap worth stating up front: do not set RSR_NON_INTERACTIVE=1. It stubs the shell builtin read, which also disables the loops that perform token substitution — the run never terminates and substitutes nothing. Pipe answers to stdin instead.

What you get

• The Marid program — brief, thirteen-package prototype (packages/), browser-client skeleton (web/), contract registry (contracts/), fixtures (fixtures/), reference-application skeleton (examples/relationship_explorer/), and interop tests (test/interop/).

• Machine-readable metadata (.machine_readable/descriptiles/) — STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, CLADE, and anchors/ANCHOR, in deed, so tools and agents can read the project’s state and boundaries.

• AI gatekeeper protocol — 0-AI-MANIFEST.deed is the universal entry point that tells an AI agent how to work in this repo before it touches anything, with per-agent instructions in AGENTS.md.

• Typed ABI/FFI seam — src/interface/Abi/ (Idris2 type + layout proofs) over src/interface/ffi/ (Zig implementation), with generated C headers. Retained RSR spine, required by just validate; it is not Marid application code.

• CI/CD — GitHub Actions for quality, security (CodeQL, Scorecard, secret scanning), multi-forge mirroring, and RSR anti-pattern enforcement.

• Supply-chain & reproducibility — container layering (stapeln), Guix shells, SBOM, and signing hooks.

• Governance — GOVERNANCE.adoc, MAINTAINERS.adoc, .github/ community health files, and a release AUDIT.adoc gate.

Repository map

The authoritative map is generated, so it cannot drift from the tree: docs/architecture/REPOSITORY-MAP.adoc (regenerate with just repo-map; CI fails if it is stale).

The short version:

Path	What lives there
PROJECT_BRIEF.md, AGENTS.md	The Marid contract and the agent instructions — start here.
packages/, web/	The thirteen Julia packages and the browser client.
contracts/, fixtures/	Contract registry and interop fixtures.
examples/, test/	Reference application and cross-protocol tests.
README.adoc, CLAUDE.md	This file; the generated agent arrival pack.
src/, tests/	RSR spine seam and estate scaffolding tests.
docs/	Human documentation, including the full map above.
.machine_readable/	Manifests, contractiles and policies that tools read.
build/, Justfile	Every task runs through just; phases live in build/just/.
ci/, .github/	CI configuration; GitHub reads .github/ and no other path.

Where to go next

• The project brief — the canonical contract (§1–§9).

• AGENTS.md — repository instructions for coding agents.

• Agent launch prompts — the Gate 0 kickoff assignment.

• Marid architecture — contracts checklist (Gate 0 stub).

• Marid compatibility — version/feature matrices (Gate 0 stub).

• Marid roadmap — the six gates (Gate 0 stub).

• docs/audits/ — feasibility evidence (Gate 0 output).

• docs/adr/ — Marid architectural decisions.

• The repository map — generated; what every directory is for.

• EXPLAINME — the engineering deep-dive: how the pieces actually work.

• AFFIRMATION — the dated, signed honesty snapshot of the repo’s true state.

• AUDIT — the release audit gate.

• AI installation guide — for agents instantiating this template.

Licence

Code, configuration and scripts are Mozilla Public License 2.0 (MPL-2.0); prose documentation is CC-BY-SA-4.0. Both texts live in LICENSES/, and per-file SPDX-License-Identifier headers are authoritative. The GitHub-detected licence is MPL-2.0 (the root LICENSE).