nervur 0.13.0 → 0.14.0

package/being.mjs

@@ -92,7 +92,7 @@ const custodial = (registry, fence) =>
         upgrade: (one) => (fence.open() ? registry.upgrade(one) : undefined),
       });
 
-const offered = (modules, program, mine) =>
+const offered = (modules, program, mine, seat) =>
   Object.freeze({
     ...Object.fromEntries(
       (program?.modules ?? [])
@@ -100,19 +100,47 @@ const offered = (modules, program, mine) =>
         .filter((name) => name !== 'memory' && modules[name] !== undefined)
         .map((name) => [name, modules[name]]),
     ),
-    memory: scoped(mine, program),
+    memory: scoped(mine, program, seat),
   });
 
 const grantable = (program) =>
   (program?.rights ?? [...STRUCTURAL, 'MEMBER']).filter((one) => !STRUCTURAL.includes(one));
 
-const referable = (mine, key, plain, program) => {
+const HORIZON = 7_776_000_000;
+
+const whole = (one) => Number.isSafeInteger(one) && one >= 0;
+
+const invitation = (plain, rights, program, seat) => {
+  const count = plain.count ?? 1;
+  const expiresAt = plain.expiresAt ?? 0;
+  if (!whole(count) || count < 1 || !whole(expiresAt)) {
+    return undefined;
+  }
+  const now = seat.now();
+  if (seat.administration) {
+    return count === 1 && expiresAt > 0 && expiresAt < now + HORIZON
+      ? { ...plain, count, expiresAt, rights }
+      : undefined;
+  }
+  const ceiling = program?.invites?.(rights);
+  if (ceiling !== undefined) {
+    if (ceiling.count > 0 && count > ceiling.count) {
+      return undefined;
+    }
+    if (ceiling.within > 0 && (expiresAt === 0 || expiresAt > now + ceiling.within)) {
+      return undefined;
+    }
+  }
+  return { ...plain, count, expiresAt, rights };
+};
+
+const referable = (mine, key, plain, program, seat) => {
   const rights = plain.rights ?? 'MEMBER';
   if (!grantable(program).includes(rights)) {
     return undefined;
   }
   if (key.startsWith('refs/pending/')) {
-    return { ...plain, rights };
+    return invitation(plain, rights, program, seat);
   }
   const held = mine.read(key);
   if (
@@ -131,14 +159,14 @@ const referable = (mine, key, plain, program) => {
   };
 };
 
-const scoped = (mine, program) =>
+const scoped = (mine, program, seat) =>
   Object.freeze({
     classOf: mine.classOf,
     list: mine.list,
     read: mine.read,
     write: (key, plain) => {
       if (key.startsWith('refs/') && plain !== undefined) {
-        const guarded = referable(mine, key, plain, program);
+        const guarded = referable(mine, key, plain, program, seat);
         return guarded === undefined ? undefined : mine.write(key, guarded);
       }
       return key.startsWith('refs/') ||
@@ -232,7 +260,18 @@ const successionOf = (memory, address) =>
     .filter((one) => one !== undefined)
     .sort((one, other) => one.v - other.v);
 
-const Being = ({ voice, address, cipher, deliver, modules, registry, span, vouched, watch }) => {
+const Being = ({
+  voice,
+  address,
+  cipher,
+  deliver,
+  modules,
+  registry,
+  administration,
+  span,
+  vouched,
+  watch,
+}) => {
   const held = spanOf(span);
   const memory = modules.memory;
   const root = rootFor({ memory, voice, address, cipher });
@@ -248,6 +287,7 @@ const Being = ({ voice, address, cipher, deliver, modules, registry, span, vouch
   });
   const succession = successionOf(memory, address);
   const stamp = Stamp();
+  const seat = Object.freeze({ administration: administration === true, now: stamp });
   const lanes = new Map();
   const answer = (spoken, claim) => {
     const body = Tools.canon(spoken);
@@ -331,10 +371,15 @@ const Being = ({ voice, address, cipher, deliver, modules, registry, span, vouch
         if (op?.acceptInvite !== undefined) {
           const offer = Tools.digest(Bytes.unbase64(op.acceptInvite.proof));
           const pending = mine.read(`refs/pending/${offer}`);
-          if (pending === undefined || pending.spent) {
+          const now = stamp();
+          if (
+            pending === undefined ||
+            !(pending.count > 0) ||
+            (pending.expiresAt > 0 && now > pending.expiresAt)
+          ) {
             return undefined;
           }
-          mine.write(`refs/pending/${offer}`, { spent: true });
+          mine.write(`refs/pending/${offer}`, { ...pending, count: pending.count - 1 });
           mine.write(`refs/${from}`, {
             nextPkHash: op.acceptInvite.nextPkHash ?? null,
             rights: pending.rights,
@@ -352,7 +397,7 @@ const Being = ({ voice, address, cipher, deliver, modules, registry, span, vouch
           program.ask({
             context: {
               from: program.caller ? from : undefined,
-              modules: offered(modules, program, turn),
+              modules: offered(modules, program, turn, seat),
               port: Port({ voice, mine: turn, deliver, fence, lanes, rights, stamp }),
               registry: custodial(registry, fence),
               rights,

package/blueprint.mjs

@@ -85,6 +85,8 @@ const doorHolder = (one) =>
 
 const RIGHTS_DIRECTIVE = 'directive @rights(is: [Rights!]!) on FIELD_DEFINITION';
 
+const INVITES_DIRECTIVE = 'directive @invites(count: Int!, within: Int!) on ENUM_VALUE';
+
 const DEFAULT_RIGHTS = `enum Rights { SELF MEMBER STRANGER }`;
 
 const codeOnly = (source) => {
@@ -150,6 +152,30 @@ const rightsOf = (field) => {
     : listed.value.values.map((one) => one.value ?? one.name?.value);
 };
 
+const whole = (one) => Number.isSafeInteger(one) && one >= 0;
+
+const ceilingOf = (value) => {
+  const marked = value.directives?.find((one) => one.name.value === 'invites');
+  if (marked === undefined) {
+    return undefined;
+  }
+  const argOf = (name) => {
+    const given = marked.arguments?.find((one) => one.name.value === name)?.value?.value;
+    return given === undefined ? undefined : Number(given);
+  };
+  return { count: argOf('count'), within: argOf('within') };
+};
+
+const ceilingsIn = (document) =>
+  new Map(
+    document.definitions
+      .filter((one) => one.kind === Kind.ENUM_TYPE_DEFINITION && one.name.value === 'Rights')
+      .flatMap((one) => one.values ?? [])
+      .map((value) => [value.name.value, ceilingOf(value)])
+      .filter(([, ceiling]) => ceiling !== undefined)
+      .map(([name, ceiling]) => [name, Object.freeze(ceiling)]),
+  );
+
 const resolverSources = (resolvers) =>
   Object.keys(resolvers)
     .sort()
@@ -202,7 +228,9 @@ const faults = (source) => {
     return ['it settles no blueprint object (VIII)'];
   }
   const declares = /enum\s+Rights\b/.test(written.interface) ? '' : DEFAULT_RIGHTS;
-  const sdl = [RIGHTS_DIRECTIVE, declares, written.interface].filter(Boolean).join('\n');
+  const sdl = [RIGHTS_DIRECTIVE, INVITES_DIRECTIVE, declares, written.interface]
+    .filter(Boolean)
+    .join('\n');
   let document;
   let schema;
   try {
@@ -241,6 +269,17 @@ const faults = (source) => {
   if (bare.length > 0) {
     found.push(`the door ${bare.join(', ')} declares no rights, and every door declares them (VI)`);
   }
+  for (const [right, ceiling] of ceilingsIn(document)) {
+    if (STRUCTURAL.includes(right)) {
+      found.push(
+        `${right} carries an @invites ceiling, and a structural right is never invited into (VI)`,
+      );
+    } else if (!whole(ceiling.count) || !whole(ceiling.within)) {
+      found.push(
+        `${right}'s @invites ceiling is not two whole numbers of zero or more (VI): count ${ceiling.count}, within ${ceiling.within}`,
+      );
+    }
+  }
   for (const [held, doors] of outside) {
     found.push(
       `the Rights enum does not name ${held}, which ${doors.length} door${doors.length === 1 ? '' : 's'} stand behind: ${doors.join(', ')} (VI)`,
@@ -342,7 +381,9 @@ const Blueprint = (source) => {
   try {
     const written = evaluated(source);
     const declares = /enum\s+Rights\b/.test(written.interface) ? '' : DEFAULT_RIGHTS;
-    const sdl = [RIGHTS_DIRECTIVE, declares, written.interface].filter(Boolean).join('\n');
+    const sdl = [RIGHTS_DIRECTIVE, INVITES_DIRECTIVE, declares, written.interface]
+      .filter(Boolean)
+      .join('\n');
     const document = parse(sdl);
     const schema = buildSchema(sdl);
     const declaredNames = (schema.getType('Rights')?.getValues() ?? []).map((one) => one.name);
@@ -376,9 +417,18 @@ const Blueprint = (source) => {
     if (undeclared.length > 0) {
       return undefined;
     }
+    const ceilings = ceilingsIn(document);
+    const misinvited = [...ceilings].filter(
+      ([right, ceiling]) =>
+        STRUCTURAL.includes(right) || !whole(ceiling.count) || !whole(ceiling.within),
+    );
+    if (misinvited.length > 0) {
+      return undefined;
+    }
 
     return Object.freeze({
       admits,
+      invites: (held) => ceilings.get(held),
       bindings: (given) =>
         modules
           .filter((one) => one.binding !== undefined)

package/ground.mjs

@@ -284,6 +284,7 @@ const Ground = (modules = {}, { span } = {}) => {
   const buildAdmin = () =>
     Being({
       address,
+      administration: true,
       cipher: modules.cipher,
       deliver: (envelope) => deliver(envelope),
       modules: modulesFor(adminVoice, adminDeclared()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A distributed system of sovereign beings — one door, one question: by whose authority.",
   "license": "Apache-2.0",
   "author": "Razvan Gherghina",

package/program.mjs

@@ -90,6 +90,7 @@ const Program = (source) => {
     config: blueprint.config,
     declares: blueprint.declares,
     digest: blueprint.digest,
+    invites: blueprint.invites,
     introspect: async (held) => {
       const filtered = seenBy(held);
       if (filtered === undefined) {