From 817f9074c48b94961faf0026b32c575af9a70bd9 Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Thu, 27 Aug 2026 14:29:42 +0200 Subject: [PATCH] =?UTF-8?q?chore:=20la=20r=C3=A8gle=20fondamentale=20devie?= =?UTF-8?q?nt=20toujours=20charg=C3=A9e,=20et=20la=20cha=C3=AEne=20cesse?= =?UTF-8?q?=20d'=C3=AAtre=20morte=20au=20sommet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .project/concepts/app-contract/_overview.md | 4 ++-- .../app-contract/knowledge_what-an-inbox-is-upstream.md | 2 +- .../app-contract/knowledge_what-an-iri-says-upstream.md | 4 ++-- .project/concepts/sign-in/knowledge_how-a-user-gets-in.md | 2 +- .project/rules/INDEX.md | 7 +++++++ .../nextgraph/no-divergence-from-nextgraph.md} | 7 +++++-- AGENTS.md | 4 ++++ CLAUDE.md | 1 + 8 files changed, 23 insertions(+), 8 deletions(-) create mode 100644 .project/rules/INDEX.md rename .project/{concepts/app-contract/rule_no-divergence-from-nextgraph.md => rules/nextgraph/no-divergence-from-nextgraph.md} (97%) create mode 100644 CLAUDE.md diff --git a/.project/concepts/app-contract/_overview.md b/.project/concepts/app-contract/_overview.md index 32d878c..1877fd0 100644 --- a/.project/concepts/app-contract/_overview.md +++ b/.project/concepts/app-contract/_overview.md @@ -29,14 +29,14 @@ vocabulary: This library exists so an application can be **written today against the NextGraph that does not ship yet**, and keep its code when it does. Everything under this concept governs that boundary: what the package publishes, what a caller may rely on, what it must not, and what disappears at migration. -The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `rule_no-divergence-from-nextgraph`. +The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `.project/rules/nextgraph/no-divergence-from-nextgraph.md`. This repo is the **provider** of `polyfill-surface`; consuming applications live in other repos, pull the engagement, and declare back what they actually consume — one `usage_.md` beside the contract, in the interface folder. The per-symbol ruling, with an epistemic label on every target-side claim, stays here in `docs/api-contract.md` — that is maintainer material, not the engagement. ## Read first - `polyfill-surface/contract_polyfill-surface` — the engagement itself, written from the caller's point of view. -- `rule_no-divergence-from-nextgraph` — the test that decides what may be built at all. +- `.project/rules/nextgraph/no-divergence-from-nextgraph.md` — the test that decides what may be built at all. - `knowledge_what-an-app-deletes-at-migration` — the two fates a published symbol can have. - `knowledge_what-an-iri-says-upstream` — the same two fates for a written *triple*: NextGraph's own vocabulary, ours, and which of our IRIs must outlive the migration. - `knowledge_what-an-inbox-is-upstream` — what the target actually offers around inboxes, and where a choice of ours begins. diff --git a/.project/concepts/app-contract/knowledge_what-an-inbox-is-upstream.md b/.project/concepts/app-contract/knowledge_what-an-inbox-is-upstream.md index 5291324..269e936 100644 --- a/.project/concepts/app-contract/knowledge_what-an-inbox-is-upstream.md +++ b/.project/concepts/app-contract/knowledge_what-an-inbox-is-upstream.md @@ -26,7 +26,7 @@ Anything built here therefore aligns on the **engine's model**, because levels 2 `InboxMsgContent` declares eight variants. `ContactDetails` and `SocialQuery` carry data and have processors. **`Link`, `Patch`, `ServiceRequest`, `ExtRequest`, `RemoteQuery` and `DialogRequest` carry nothing at all** — they are bare unit variants, so they cannot hold a reference, name a servicer, or describe an operation. -That distinction decides how much they bind us, and it is why the provenance taxonomy in [[rule_no-divergence-from-nextgraph]] separates a reserved name from a declared shape. +That distinction decides how much they bind us, and it is why the provenance taxonomy in the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`) separates a reserved name from a declared shape. ## Processing is closed, and so is posting diff --git a/.project/concepts/app-contract/knowledge_what-an-iri-says-upstream.md b/.project/concepts/app-contract/knowledge_what-an-iri-says-upstream.md index 3bdc453..1615d81 100644 --- a/.project/concepts/app-contract/knowledge_what-an-iri-says-upstream.md +++ b/.project/concepts/app-contract/knowledge_what-an-iri-says-upstream.md @@ -62,8 +62,8 @@ Naming them alike would say the wrong thing about both: it would promise the sca **Settled, read at the source.** Nothing upstream reserves, filters or validates a namespace; the engine stores and returns arbitrary IRIs; there is no extension convention to comply with and no procedure for claiming a segment. **Nothing upstream binds our choice, and nothing upstream breaks if we keep a `urn:` scheme.** -**A bet.** That upstream will not later claim `urn:` or begin separating by prefix. Nothing says it will; nothing says it will not — and *the absence of an implementation says nothing about what the target will do* ([[rule_no-divergence-from-nextgraph]]). The exposure is small and it falls on the scaffolding side, which is the half designed to disappear. +**A bet.** That upstream will not later claim `urn:` or begin separating by prefix. Nothing says it will; nothing says it will not — and *the absence of an implementation says nothing about what the target will do* (the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`)). The exposure is small and it falls on the scaffolding side, which is the half designed to disappear. **A bet, and the more expensive one.** Writing `urn:ng-helpers:` from here. Two packages now share one data format with no owner and no agreement about who may change it. -**Not a bet — a divergence, if it were ever done.** Putting our own terms under `did:ng:x:…`. That segment is the target's vocabulary space, `did:ng:x:ng#` is the engine's own, and `x` means nothing to the address grammar — so borrowing it would dress an invention in the target's vocabulary, which [[rule_no-divergence-from-nextgraph]] names as the most dangerous kind of all. +**Not a bet — a divergence, if it were ever done.** Putting our own terms under `did:ng:x:…`. That segment is the target's vocabulary space, `did:ng:x:ng#` is the engine's own, and `x` means nothing to the address grammar — so borrowing it would dress an invention in the target's vocabulary, which the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`) names as the most dangerous kind of all. diff --git a/.project/concepts/sign-in/knowledge_how-a-user-gets-in.md b/.project/concepts/sign-in/knowledge_how-a-user-gets-in.md index 633dc73..d9212ec 100644 --- a/.project/concepts/sign-in/knowledge_how-a-user-gets-in.md +++ b/.project/concepts/sign-in/knowledge_how-a-user-gets-in.md @@ -11,7 +11,7 @@ A newcomer holds nothing. To act they need a wallet imported once into the walle Then the page is handed to the broker, which opens the wallet and reloads the application **inside an iframe it hosts**. Outside that iframe there is no session. -**The redirect is not ours.** `@ng-org/web`'s `init()` performs it as its first statement — same host, same URL shape, same frame check. Verified in its shipped bundle: when `window.self === window.top` it assigns `window.location.href` from a hard-coded `redirect` constant. This package must not reimplement it; doing so would double a function of the layer below and diverge from it in the meantime (see `app-contract/rule_no-divergence-from-nextgraph`). +**The redirect is not ours.** `@ng-org/web`'s `init()` performs it as its first statement — same host, same URL shape, same frame check. Verified in its shipped bundle: when `window.self === window.top` it assigns `window.location.href` from a hard-coded `redirect` constant. This package must not reimplement it; doing so would double a function of the layer below and diverge from it in the meantime (see `.project/rules/nextgraph/no-divergence-from-nextgraph.md`). What is genuinely ours is the one thing `init()` cannot do: **put the identifier into the URL before `init()` reads it**. `init()` hands over `window.location.href`; it does not know the parameter exists. diff --git a/.project/rules/INDEX.md b/.project/rules/INDEX.md new file mode 100644 index 0000000..c60910e --- /dev/null +++ b/.project/rules/INDEX.md @@ -0,0 +1,7 @@ +# Rules (local) + +Each rule lists its one-line summary. **Read the full file** when a rule looks relevant — it contains the *why* and *how to apply* needed to use the rule with judgment. + +## nextgraph + +- **no-divergence-from-nextgraph** — Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled → `.project/rules/nextgraph/no-divergence-from-nextgraph.md` diff --git a/.project/concepts/app-contract/rule_no-divergence-from-nextgraph.md b/.project/rules/nextgraph/no-divergence-from-nextgraph.md similarity index 97% rename from .project/concepts/app-contract/rule_no-divergence-from-nextgraph.md rename to .project/rules/nextgraph/no-divergence-from-nextgraph.md index 411af5c..7df36fe 100644 --- a/.project/concepts/app-contract/rule_no-divergence-from-nextgraph.md +++ b/.project/rules/nextgraph/no-divergence-from-nextgraph.md @@ -1,6 +1,9 @@ --- -type: rule -summary: Never implement anything that diverges from NextGraph — ask "does the target do this?" first, and only then how badly a caller would be misled +name: no-divergence-from-nextgraph +summary: Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled +group: nextgraph +scope: local +created: 2026-08-27 --- # No divergence from NextGraph diff --git a/AGENTS.md b/AGENTS.md index e7ea3d0..854cfa4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,7 @@ ## Project vocabulary (always loaded) @.project/VOCABULARY.md + +## Rules + +@.project/rules/INDEX.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md