From e3f639dd59f6f8fd7aeac0fd63ff8025ee0ef86c Mon Sep 17 00:00:00 2001 From: Jodson Graves Date: Sun, 12 Jul 2026 09:21:06 -0400 Subject: [PATCH] docs: JFA conformance self-description + repo discipline CONFORMANCE.md declares the repo's role (front end + member-economy layers) in the architecture's terms, before product specifics, and binds each claim to its mechanism honestly as of main: record built (single-witness StandIn, labeled), covenant and economy stubs whose package docs carry the binding invariants, built implementations in the open PR stack. CLAUDE.md carries the per-layer invariants, refuse-or-flag list, and tension protocol for agent-assisted work. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ CONFORMANCE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 CLAUDE.md create mode 100644 CONFORMANCE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6c4d0bc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,47 @@ +# CLAUDE.md — Cloudy + +## What this repo is + +The **front end** of a Janus-Facing Architecture substrate, and the home of the member-economy layers: the per-operator dialog record, the reputation covenant, and member-issued credit. Read `CONFORMANCE.md` first — it is the role declaration and the invariant-to-binding table, and it must be updated in the same PR as any change that alters a binding. + +## Non-negotiable invariants + +Not negotiable by feature request. Grouped by the layer they defend. + +**Record (`internal/record`)** +- Append-only: no update, no delete, anywhere. Corrections are new entries. +- No PII in the commons: never add a `string` field, memo channel, or marshal/export path to a commons type (Entry, Checkpoint, Countersignature, Proof, WitnessedCheckpoint). Erasable content belongs to the member-local store only. +- Dialog-sealed: both members' seals over the same canonical bytes; no self-dialog. +- A witness confers no authority: witnessing is retrospective countersigning; any API that makes a witness signature a precondition for an operation is an invariant violation — stop and flag. +- StandIn honesty: any surface presenting witnessed data carries the computed stand-in label; never present one witness as federation. +- Domain tags are frozen once durable data exists. The pending product rename must land before durable persistence. + +**Covenant (`internal/covenant`)** +- Never average ratings into a score — carry the full distribution, count at each level beside the total. +- The lowest rating is the breach itself. Volume never absolves harm. +- Symmetric: every claim answerable; dismissals are annotations, never erasures. +- Reputation gates **whether** a member transacts on trust, never **how much**. Non-portable by default. + +**Economy (`internal/economy`)** +- Balances are a deterministic function of the sealed record; every sealed exchange moves two balances that net to zero. +- Issuance gated by the covenant, capped by a separate limit never derived from the harm distribution. +- Credit is earned, never bought; never redeemable for fiat. Denomination is not redemption. Escrow-first; the escrow-to-credit switch is governance, never a code default. + +**Identity** +- Single participant identity: one member is simultaneously contributor and consumer. Never split into producer and consumer identities, in any schema, type, or UI. +- Persons never appear on the coordination wire; member identity stays platform-scoped, PII member-local and erasable. + +## Change discipline + +1. Branch → PR → CI green → human review. The author never merges their own PR. Claude drafts and proposes; a human disposes. +2. `CONFORMANCE.md` rides along: a change altering any binding updates it in the same PR. +3. A stub stays labeled a stub until its implementation satisfies its package doc's invariants; never quietly promote one. +4. Never force-push, rewrite published history, or move a published tag. + +## Requests to refuse or flag + +Stop, name the tension, and surface it — do not implement quietly: average ratings or show a single score; edit or delete a record entry; add PII or free-text to a commons type; let users buy or cash out credits; raise a credit limit from reputation; split producer/consumer identities; make witnessing a gate; present a single-witness deployment as federated. + +## Tension protocol + +If you notice yourself reframing an invariant so a feature becomes convenient, implementing a stand-in without labeling it, or routing around an open problem instead of noting it — stop. Name the tension, attach it to the invariant or open problem by name, and propose the minimal conformant move. Surface it; do not absorb it. diff --git a/CONFORMANCE.md b/CONFORMANCE.md new file mode 100644 index 0000000..b22a8e0 --- /dev/null +++ b/CONFORMANCE.md @@ -0,0 +1,47 @@ +# Conformance — Janus-Facing Architecture + +The repo's self-description in the architecture's own terms, stated **before** anything product-specific, per the architecture's ordering rule. Every conformance claim is bound to the mechanism and check that enforces it, or it is labeled a stand-in or stub. Unbound prose is marketing. + +The architecture is **Janus-Facing Architecture (JFA)** — NTARI's unified architecture document, free documentation under the project's AGPL-3.0 commons. + +## Role declaration + +Cloudy is a **front end** of a JFA substrate — the member-facing application — and the home of the **member-economy layers** the substrate coordination protocol deliberately does not define: the per-operator dialog record, the reputation covenant, and member-issued credit. Members exist here and only here; the coordination wire below this repo knows no persons. Cloudy is a standalone, forkable product: it speaks the published protocol and any conformant coordinator can serve it. + +| This repo's term | Architecture role | +|---|---| +| `internal/record` | the **per-operator dialog ledger** — append-only, dialog-sealed, witnessed | +| `internal/covenant` | the **assessment scale** implementation (member reputation as covenant) | +| `internal/economy` | **member-issued credit** (the member economy) | +| `internal/coord` | consumption of the substrate **coordination protocol** | +| Member | a person, platform-scoped; PII stays member-local and erasable | + +## Invariants and their bindings — as of `main` + +Statuses are stated per the architecture's honesty rule. Built member-layer work beyond this exists in the open PR stack and updates this table as it lands. + +| Invariant (architecture) | Status on main | Mechanism / check | +|---|---|---| +| Record is **append-only**; corrections are new entries | **Built** | `internal/record`: Store/Log expose Append only — update and delete are absent verbs; package doc states the structural rules; tests | +| Record is **dialog-sealed** — what two members agreed, not what one asserts | **Built** | Dual-seal verification over canonical bytes; self-dialog rejected at construction | +| **No PII in the commons**; narrative stays member-local and erasable | **Built** | Commons types carry hashes, keys, and instants only; erasable content lives in a type-disjoint member-local store | +| **Witnessing** with structural independence; a single-witness deployment is a labeled stand-in | **Built (stand-in)** | Witness countersignatures with pairwise-independence verification; the StandIn label is computed, not asserted | +| Covenant: **never average**; full distribution; symmetric; gates whether-never-how-much | **Stub, labeled** | `internal/covenant` package doc declares the non-negotiable invariants it must satisfy when built; built implementation in review | +| Economy: balances a **deterministic function of the sealed record**; zero-sum; escrow-first; earned-never-bought | **Stub, labeled** | `internal/economy` package doc declares the invariants; built implementation in review | +| **Single participant identity** — one member, simultaneously contributor and consumer | Design-binding | No producer/consumer split exists in any schema or type; binds every member surface as it lands | +| **Forkability** | Built | Consumes the coordination protocol at a published version tag; no coordinator is privileged | + +## Stand-ins and open residuals + +- **Single-witness StandIn.** Every witnessed checkpoint today has fewer than two independent witnesses; the record layer computes and reports this label structurally. Live federation is the architecture's open problem 2 — the keystone build. +- **Covenant and economy are stubs on main.** Their package docs carry the binding invariants; the built implementations are in the open, stacked PRs and must satisfy those docs to merge. +- **Record domain-tag rename** (product naming) is pending and must land **before any durable persistence** — retagging after durable logs exist would be a rewrite. +- **Named record residuals** (steganographic floor, timestamp covert channel, witness amnesia, liveness gap) are documented in the record package doc rather than pretended away. + +## Dependency declaration + +Consumes `sohocloud-protocol` at a published version tag — nothing else from the stack. The member layers reference sealed exchanges by opaque leaf ID, by value, never by importing record types into other layers; conversion happens only at the composition root. + +## Product-specific notes (last, per the ordering rule) + +Cloudy ships as a standalone consumer product (its own member API and app surfaces, in review). SoHoLINK is the reference coordinator it speaks to; any conformant coordinator may replace it.