nervur 0.13.0 → 0.15.0

package/src/program.js

@@ -0,0 +1,74 @@
+import { contract as read } from './contract.js';
+
+// A contract and its resolvers, made callable. This is the whole compiler, and
+// beings and organs both come out of it, because they are one kind of code: a
+// field of an organ is a resolver exactly as a field of a being is, and nothing
+// here can tell which it is holding. There is no second compiler anywhere, and
+// a design that wants one is wrong.
+//
+// A resolver is sovereign. It sees its arguments by the names its own contract
+// gave them, it reaches the world only through the context it was handed, and
+// it never throws — a resolver that raises is answered as silence, because
+// nothing in this system promises that an ask is fulfilled. A refusal a caller
+// must tell apart from silence is carried in the answer type instead.
+
+// Exactly the arguments the contract declares, and nothing else. What a caller
+// may ask is what the contract already showed it, so a parameter nobody
+// declared cannot ride in beside one that was.
+const given = (args, params) =>
+  Object.freeze(
+    Object.fromEntries(
+      Object.keys(args)
+        .filter(
+          (name) =>
+            params !== null &&
+            typeof params === 'object' &&
+            Object.hasOwn(params, name) &&
+            params[name] !== undefined,
+        )
+        .map((name) => [name, params[name]]),
+    ),
+  );
+
+const complete = (args, only) =>
+  Object.entries(args).every(([name, one]) => !one.required || only[name] !== undefined);
+
+export function program(one, resolvers) {
+  const held = typeof one === 'string' ? read(one) : one;
+
+  return Object.freeze({
+    // What may be asked here, which is the only place to find out. A field this
+    // does not name does not exist for a caller.
+    contract: held,
+
+    answer: async (field, params, context) => {
+      // Read as an own property, never through the prototype chain. Without
+      // this, `__proto__`, `constructor` and `toString` all name a field nobody
+      // declared, and a caller reaches something the contract never showed it.
+      const declared = Object.hasOwn(held.fields, field) ? held.fields[field] : undefined;
+      if (declared === undefined) return undefined;
+
+      const only = given(declared.args, params);
+      // A field short of an argument its contract made mandatory is not called
+      // at all. A resolver written against its own contract may read that
+      // argument without checking, and calling it anyway would make every
+      // resolver defensive about a promise the contract already made.
+      if (!complete(declared.args, only)) return undefined;
+
+      const resolver =
+        resolvers !== null &&
+        typeof resolvers === 'object' &&
+        Object.hasOwn(resolvers, field) &&
+        typeof resolvers[field] === 'function'
+          ? resolvers[field]
+          : undefined;
+      if (resolver === undefined) return undefined;
+
+      try {
+        return await resolver(only, context);
+      } catch {
+        return undefined;
+      }
+    },
+  });
+}

package/src/projection.js

@@ -0,0 +1,102 @@
+import { Refusal, print } from '@quo-systems/js';
+
+// The boundary, and there is exactly one of it. Inside a ground a contract is
+// GraphQL; on the wire there is Quo and only Quo. A stranger implementing the
+// protocol in another language has never heard of Nervur and must still read
+// the blueprint a being stands on, so a contract is projected into the kit's
+// own notation here and nowhere else.
+//
+// The projection never guesses. Where GraphQL says something the notation has
+// no word for, the contract is refused at build — a being that stood on a
+// blueprint that quietly dropped half its schema would have a digest that lied
+// to everyone who read it.
+
+const refuse = (code, detail) => {
+  throw new Refusal(code, detail);
+};
+
+// The closed set of scalars is the law's, so this table is closed too. A name
+// missing from it is not a scalar Nervur may invent — it is a word Quo does
+// not have.
+const SCALARS = Object.freeze({
+  Boolean: 'bool',
+  Int: 'int',
+  String: 'text',
+  Bytes: 'bytes',
+  B32: 'b32',
+  Being: 'being',
+  Invitation: 'invitation',
+  Card: 'card',
+});
+
+// The one word the notation has and GraphQL does not: a field that answers
+// nothing, which rides as zero bytes and is a real answer. GraphQL insists
+// every field has a type, so a contract spells it with this name in answer
+// position. It is not a type and may not be asked for or carried.
+const NOTHING = 'Nothing';
+
+// GraphQL is nullable by default and says so by omission; the notation is
+// required by default and says the other thing with `?`. This is the whole of
+// the difference and it is spelled out rather than inferred.
+function projectType(node, where, records) {
+  if (node.list) {
+    return node.required
+      ? { list: projectType(node.element, where, records) }
+      : { optional: { list: projectType(node.element, where, records) } };
+  }
+  const base = SCALARS[node.of] ?? (records.has(node.of) ? node.of : undefined);
+  if (base === undefined) {
+    refuse(
+      'NO_WORD',
+      node.of === NOTHING
+        ? `${NOTHING} at ${where}, which is not a type`
+        : `${node.of} at ${where}`,
+    );
+  }
+  return node.required ? { base } : { optional: { base } };
+}
+
+const projectArgs = (args, where, records) =>
+  Object.entries(args).map(([name, one]) => ({
+    name,
+    type: projectType(one, `${where}(${name})`, records),
+  }));
+
+// A record block holds plain fields: a name and a type, and nothing else. A
+// GraphQL object type whose fields take arguments is a type with behaviour,
+// which the notation has no word for at all.
+const projectRecord = (name, fields, records) =>
+  Object.freeze({
+    name,
+    fields: Object.entries(fields).map(([field, one]) => {
+      if (Object.keys(one.args).length > 0) refuse('NO_WORD', `arguments on ${name}.${field}`);
+      if (one.answers.of === NOTHING) refuse('NO_WORD', `${NOTHING} at ${name}.${field}`);
+      return { name: field, type: projectType(one.answers, `${name}.${field}`, records) };
+    }),
+  });
+
+// The blueprint a being actually stands on: one class block named for the
+// contract's root type, its declared fields flat, and every other type of the
+// schema behind it as a record. Ordering, canonical spelling, unused records
+// and recursion are the notation's own law, so they are the kit's `print` to
+// judge and never this file's.
+export function project(one) {
+  const records = new Set(Object.keys(one.records));
+  const blueprint = {
+    name: one.name,
+    fields: Object.entries(one.fields).map(([name, field]) => ({
+      name,
+      args: projectArgs(field.args, name, records),
+      answer:
+        field.answers.of === NOTHING && !field.answers.list
+          ? null
+          : projectType(field.answers, name, records),
+    })),
+    records: [...Object.entries(one.records)].map(([name, fields]) =>
+      projectRecord(name, fields, records),
+    ),
+  };
+  return print(blueprint);
+}
+
+export { NOTHING, SCALARS };

package/GETTING-STARTED.md

@@ -1,111 +0,0 @@
-# Getting started — two castles
-
-Picture a castle: one gate, its own residents, its own law. A **ground** is
-the castle — one sovereign process, one handler where every letter arrives.
-Its residents are **beings**; its capabilities are **modules**; the ground
-under it is a **floor** — a filesystem, or a browser's IndexedDB — and the
-stance it takes toward the world is its **terrain**. This page raises two
-castles on two terrains and has them speak: a **mountain** (a server, always
-reachable, always remembering) and a **house of cards** (a browser tab,
-raised in seconds, holding what it can afford to lose). Same castle, same
-law, different ground under it.
-
-Everything below runs today — the bench drives this exact story in
-`bench/worlds/story/`.
-
-## The mountain
-
-The machine's raise is one config and one daemon —
-[`nervurd`](https://www.npmjs.com/package/nervurd) is the host, and its
-README is the operator's full page. The five-minute shape:
-
-```sh
-npm install -g nervurd
-nervur self mint --self ./hand.json --heir ./heir.json
-nervur init --config ./castle.json --self ./hand.json
-NERVUR_SECRET=... nervurd --config ./castle.json
-```
-
-The config names the shelf, the door, the secret's environment variable,
-and the modules — the castle's capabilities, chosen by you:
-
-```json
-{
-  "cells": "/var/lib/nervur/castle.json",
-  "listen": { "host": "127.0.0.1", "port": 7001 },
-  "secret": "NERVUR_SECRET",
-  "modules": {}
-}
-```
-
-Keep the heir off the machine. Whoever takes the machine takes what the
-castle holds today; the heir is why they can never become it tomorrow.
-
-## The house of cards
-
-The browser's raise is two calls from
-[`@nervur-org/floor-web`](https://www.npmjs.com/package/@nervur-org/floor-web),
-because a tab closes constantly and the two acts must not blur:
-
-```js
-import { found, wake } from '@nervur-org/floor-web';
-
-// Once, ever: mint the identity, stand the castle, get custody back.
-let kept;
-const castle = found({ keep: (dump) => (kept = dump) });
-// castle.address — the name; castle.custody — the hand, the heir, the
-// secret: yours to keep (IndexedDB, or a mountain you trust), never the
-// ground's.
-
-// Every session after: same name, same residents, no identity act.
-// wake hands back the standing ground itself — woken.address is the name.
-const woken = wake({ held: kept, secret: castle.custody.secret });
-```
-
-Where `kept` and `custody` live is your choice, under this terrain's honest
-limit: a browser may evict what it keeps — a card castle holds what it can
-afford to lose, and keeps what is precious in its relationship with a
-mountain.
-
-## They speak
-
-A letter is a letter on every terrain: one signed envelope, carried
-however the two castles can reach each other — here, `fetch` to the
-mountain's door. First the mountain's keeper invites the card castle's
-founder (one signed act at the admin door — the CLI, or any client the
-keeper holds), and then the founder asks from the browser:
-
-```js
-import { Client, Tools, Voice } from 'nervur';
-
-const me = Voice.revive(castle.custody.hand);
-const talk = Client({
-  voice: me,
-  deliver: async (envelope) => {
-    const res = await fetch('http://127.0.0.1:7001', {
-      body: JSON.stringify(envelope),
-      headers: { 'content-type': 'application/json' },
-      method: 'POST',
-    });
-    return res.status === 200 ? res.json() : undefined;
-  },
-});
-
-const heard = await talk.ask(mountainAddress, '{ census { active } }');
-```
-
-The client verifies every answer from the address alone — the mountain's
-word arrives signed, and a broken or missing signature is dropped exactly
-like silence. A stranger who was never invited gets silence too, and cannot
-tell refusal from absence. That is the whole protocol: **say who you are,
-name whom you seek, and the castle answers or keeps quiet.**
-
-## Where to go next
-
-- [`nervur`'s README](README.md) — the library underneath both castles.
-- [`nervurd`'s README](../nervurd/README.md) — the operator's page: checks,
-  rotation, backups, the door's full behaviour.
-- [`@nervur-org/floor-web`](../floor-web/README.md) — the web floor's
-  terrain contract, founding and waking in full.
-- [`@nervur-org/species`](../species/README.md) — blueprints your castles
-  grow beings from.

package/NOTICE

@@ -1,2 +0,0 @@
-Nervur
-Copyright 2026 Razvan Gherghina

package/SECURITY.md

@@ -1,11 +0,0 @@
-# Security
-
-This package answers one question — by whose authority — and a hole in that
-answer is the most serious bug it can have.
-
-Report vulnerabilities privately to **<security@nervur.com>**. Do not open a
-public report. State what you ran, what you sent, and what answered; a
-proof of concept is welcome but not required.
-
-A person reads every report. Fixes ship as releases on the live 0.x line,
-and the report is credited if you want it to be.

package/admin.mjs

@@ -1,83 +0,0 @@
-const ADMIN = `({
-  name: 'nervur.ground',
-  needs: { modules: [{ module: 'memory', contract: 'nervur.memory' }] },
-  memory: {
-    'aliases/*': { type: 'String', class: 'data' },
-    wears: { type: 'String', class: 'data' },
-  },
-  interface: \`
-    input RefInput { address: String!, nextPkHash: String, rights: String }
-    type Resident { address: String!, alias: String, digest: String, active: Boolean! }
-    type Census { residents: [Resident!]!, stored: Int!, active: Int! }
-    type Query {
-      census: Census                   @rights(is: [SELF, MEMBER])
-      aliasOf(name: String!): String   @rights(is: [SELF, MEMBER])
-      attest(module: String!): Boolean @rights(is: [SELF, MEMBER])
-      opened: Boolean                  @rights(is: [SELF, MEMBER, STRANGER])
-      wears: String                    @rights(is: [SELF, MEMBER, STRANGER])
-    }
-    type Mutation {
-      invite(address: String!, nextPkHash: String, rights: String): Boolean @rights(is: [SELF, MEMBER])
-      drop(address: String!): Boolean                       @rights(is: [SELF, MEMBER])
-      extend(program: String): Boolean                      @rights(is: [SELF])
-      create(program: String!, refs: [RefInput!], data: String, config: String): String
-        @rights(is: [SELF, MEMBER])
-      activate(address: String!): String                   @rights(is: [SELF, MEMBER])
-      destroy(address: String!): String                    @rights(is: [SELF, MEMBER])
-      upgrade(address: String!, program: String!): Boolean  @rights(is: [SELF, MEMBER])
-      alias(name: String!, address: String!): Boolean       @rights(is: [SELF, MEMBER])
-      wear(address: String): Boolean                        @rights(is: [SELF, MEMBER])
-    }
-  \`,
-  resolvers: {
-    Query: {
-      census: (_, __, { registry }) => {
-        const residents = registry.residents();
-        return {
-          active: residents.filter((one) => one.active).length,
-          residents,
-          stored: residents.length,
-        };
-      },
-      aliasOf: (_, { name }, { modules }) => modules.memory.read('aliases/' + name),
-      attest: (_, { module }, { registry }) => registry.attest(module),
-      opened: (_, __, { modules }) => modules.memory.list('refs/').length > 0,
-      wears: (_, __, { modules }) => modules.memory.read('wears') ?? null,
-    },
-    Mutation: {
-      invite: (_, { address, nextPkHash, rights }, { modules }) =>
-        modules.memory.write('refs/' + address, {
-          nextPkHash: nextPkHash ?? null,
-          rights: rights ?? 'MEMBER',
-        }) !== undefined,
-      drop: (_, { address }, { modules }) => {
-        if (modules.memory.read('refs/' + address) === undefined) {
-          return false;
-        }
-        modules.memory.write('refs/' + address, undefined);
-        return modules.memory.read('refs/' + address) === undefined;
-      },
-      extend: (_, { program }, { registry }) => registry.extend(program) !== undefined,
-      create: (_, { program, refs, data, config }, { registry }) =>
-        registry.create({
-          config: config === undefined ? undefined : JSON.parse(config),
-          data: data ? JSON.parse(data) : {},
-          program,
-          refs: refs ?? [],
-        }),
-      activate: (_, { address }, { registry }) =>
-        registry.activate(address) === undefined ? null : address,
-      destroy: (_, { address }, { registry }) => registry.destroy(address) ?? null,
-      upgrade: (_, { address, program }, { registry }) =>
-        registry.upgrade({ address, program }) !== undefined,
-      alias: (_, { name, address }, { modules }) =>
-        modules.memory.write('aliases/' + name, address) !== undefined,
-      wear: (_, { address }, { modules }) => {
-        modules.memory.write('wears', address ?? undefined);
-        return modules.memory.read('wears') === (address ?? undefined);
-      },
-    },
-  },
-})`;
-
-export { ADMIN };