@sanoma-ai/workflows 0.6.0 → 0.7.1

package/dist/change.d.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+import type { ApprovalState, Approver } from "./define.ts";
+import { type Driver } from "./op.ts";
+import { type Decision } from "./policy.ts";
+import { type Resource } from "./resource.ts";
+import { type PeopleResource } from "./shared.ts";
+import type { CheckResult } from "./source.ts";
+/**
+ * What the planner finds in a change, before the policy is asked: the attributes of the
+ * `Sanoma::Change` that `sanoma.change.merge` acts on, so a rule reads `resource.touches`.
+ */
+export declare const ChangeFacts: z.ZodObject<{
+    touches: z.ZodArray<z.ZodString>;
+    strandedRuns: z.ZodNumber;
+    stranded: z.ZodArray<z.ZodString>;
+    checksOk: z.ZodBoolean;
+    rules: z.ZodBoolean;
+}, z.core.$strip>;
+export type ChangeFacts = z.infer<typeof ChangeFacts>;
+/** What opening a change takes: its draft's id, and the pull request's title, body and the change page's link. */
+export declare const ChangeInput: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChangeInput = z.infer<typeof ChangeInput>;
+/** The change a call acts on: its policy target. */
+declare const target: ({ id }: {
+    id: string;
+}) => string;
+/** The operations of a change, on the built-in connector `sanoma`: only the `change` workflow calls them. */
+export declare const changeOps: import("./op.ts").Connector<"sanoma", {
+    readonly change: {
+        readonly open: {
+            readonly effect: "write";
+            readonly idempotent: true;
+            readonly description: "Open a change: push its draft's branch and open a pull request for it";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                body: z.ZodOptional<z.ZodString>;
+                page: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly output: z.ZodObject<{
+                number: z.ZodNumber;
+                url: z.ZodString;
+                head: z.ZodString;
+                branch: z.ZodString;
+            }, z.core.$strip>;
+            readonly target: typeof target;
+            readonly phrases: {
+                readonly expect: "change {id} is opened";
+            };
+        };
+        readonly review: {
+            readonly effect: "write";
+            readonly idempotent: true;
+            readonly description: "Report Sanoma's review of a change on its pull request";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                number: z.ZodNumber;
+                head: z.ZodString;
+                state: z.ZodEnum<{
+                    failure: "failure";
+                    pending: "pending";
+                }>;
+                description: z.ZodString;
+                page: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly output: z.ZodObject<{}, z.core.$strip>;
+            readonly target: typeof target;
+            readonly phrases: {
+                readonly expect: "change {id} is reviewed";
+            };
+        };
+        readonly merge: {
+            readonly effect: "write";
+            readonly idempotent: true;
+            readonly description: "Merge a change's pull request";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                number: z.ZodNumber;
+                head: z.ZodString;
+                title: z.ZodString;
+                facts: z.ZodObject<{
+                    touches: z.ZodArray<z.ZodString>;
+                    strandedRuns: z.ZodNumber;
+                    stranded: z.ZodArray<z.ZodString>;
+                    checksOk: z.ZodBoolean;
+                    rules: z.ZodBoolean;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            readonly output: z.ZodObject<{
+                outcome: z.ZodEnum<{
+                    blocked: "blocked";
+                    closed: "closed";
+                    merged: "merged";
+                    moved: "moved";
+                }>;
+                sha: z.ZodOptional<z.ZodString>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly target: typeof target;
+            readonly phrases: {
+                readonly expect: "change {id} is merged";
+            };
+        };
+        readonly close: {
+            readonly effect: "write";
+            readonly idempotent: true;
+            readonly description: "Close a change's pull request without merging it";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                number: z.ZodNumber;
+            }, z.core.$strip>;
+            readonly output: z.ZodObject<{
+                closed: z.ZodLiteral<true>;
+            }, z.core.$strip>;
+            readonly target: typeof target;
+            readonly phrases: {
+                readonly expect: "change {id} is closed";
+            };
+        };
+    };
+}>;
+/**
+ * The built-in workflow that alone may call `op`, what the operation does and what to do instead:
+ * `apply` for a writable resource type's change operations (`isChangeOp`), `change` for
+ * `sanoma.change.*`; undefined for any other. `resolveConfig` refuses a workflow that uses one, and
+ * a run's call of one outside its workflow fails.
+ */
+export declare function reservedFor(op: {
+    readonly vendor: string;
+    readonly resource: string;
+    readonly name: string;
+}, types: ReadonlyMap<string, Pick<Resource, "writable">>): {
+    workflow: string;
+    does: string;
+    instead: string;
+} | undefined;
+/** A placeholder: lane C5 replaces it with the driver over the repository's host. */
+export declare function changeDriver(): Driver;
+/**
+ * Each path, relative to the root with `/` between its parts, and each of its parent directories
+ * with a trailing `/`, sorted, each once: what a rule asks with `touches.contains("resources/finance/")`.
+ */
+export declare function touchesOf(files: readonly string[]): string[];
+/**
+ * The runtime's own rule, asked before any company policy and under `allowAll` too: a merge of a
+ * change to the rules (`facts.rules`, or `touches` naming `policies/` or `resources/people.ts`) waits for `admin`, whoever made it, until an approval
+ * addressed to `admin` covering the merge is approved; denied while no data file declares the
+ * group. Undefined for anything else, which the company's policy alone decides. `people` are the
+ * running instance's, never the change's, so a change cannot add its author to `admin`.
+ */
+export declare function runtimeHold(opId: string, input: unknown, approvals: readonly ApprovalState[], people: readonly PeopleResource[]): Decision | undefined;
+/** What a change run is told while it waits: new commits on its branch, a close asked for, or its pull request closed or merged on the host. */
+export type ChangeEvent = {
+    kind: "commits";
+} | {
+    kind: "close";
+    by: string;
+} | {
+    kind: "closed";
+} | {
+    kind: "merged";
+    sha: string;
+};
+/** Where a change is, as its run publishes it (`CHANGE_EVENT`) for the app. */
+export interface ChangeState {
+    id: string;
+    branch: string;
+    title: string;
+    page?: string;
+    phase: "opening" | "planning" | "checking" | "reviewing" | "waiting" | "merging" | "deploying" | "merged" | "closed" | "blocked";
+    pullRequest?: {
+        number: number;
+        url: string;
+    };
+    head?: string;
+    facts?: ChangeFacts;
+    check?: CheckResult;
+    decision?: {
+        answer: "allow" | "hold" | "deny";
+        approver?: Approver;
+        title?: string;
+        reasons?: string[];
+        reason?: string;
+    };
+    /** The review card on the host: unavailable in this version. */
+    card: {
+        status: "unavailable";
+        reason: string;
+    };
+    merged?: {
+        sha: string;
+        at: number;
+        deploy?: {
+            runId?: string;
+            followed?: string;
+            skipped?: string;
+        };
+    };
+    blocked?: string;
+}
+/** How a change run ended. */
+export interface ChangeReport {
+    outcome: "merged" | "closed";
+    head: string;
+    pullRequest: {
+        number: number;
+        url: string;
+    };
+    sha?: string;
+    deploy?: {
+        runId?: string;
+    };
+}
+export {};

package/dist/change.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { defineConnector, defineDriver, DriverError } from "./op.js";
+import { approve, approvedFor, deny } from "./policy.js";
+import { isChangeOp } from "./resource.js";
+import { APPLY_WORKFLOW, CHANGE_MERGE, CHANGE_WORKFLOW, groupNamesOf } from "./shared.js";
+// A change: how a draft of the company's repository goes live, as the built-in `change` workflow
+// runs it (lane C5): its four operations on the built-in connector `sanoma`, the facts a policy
+// decides its merge on (the attributes of its `Sanoma::Change`), and the runtime's own rule that
+// a change to the rules waits for `admin`, before any company policy is asked.
+/**
+ * What the planner finds in a change, before the policy is asked: the attributes of the
+ * `Sanoma::Change` that `sanoma.change.merge` acts on, so a rule reads `resource.touches`.
+ */
+export const ChangeFacts = z.object({
+    /** Every path the change edits and each of its parent directories (`touchesOf`). */
+    touches: z.array(z.string()),
+    /** How many waiting runs are of a workflow the change edits, which the publish cannot move. */
+    strandedRuns: z.number().int(),
+    /** Those runs' ids. */
+    stranded: z.array(z.string()),
+    /** Whether `sanoma check` passed on the change. */
+    checksOk: z.boolean(),
+    /** Whether the change edits the rules: a policy or a people file, which wait for `admin` (`runtimeHold`). */
+    rules: z.boolean(),
+});
+/** What opening a change takes: its draft's id, and the pull request's title, body and the change page's link. */
+export const ChangeInput = z.object({
+    id: z.string().regex(/^[\w-]{1,64}$/),
+    title: z.string().min(1),
+    body: z.string().optional(),
+    page: z.string().url().optional(),
+});
+/** The change a call acts on: its policy target. */
+const target = ({ id }) => `change:${id}`;
+/** A change once it has a pull request: its draft's id and the pull request's number. */
+const opened = { id: ChangeInput.shape.id, number: z.number().int().positive() };
+/** The operations of a change, on the built-in connector `sanoma`: only the `change` workflow calls them. */
+export const changeOps = defineConnector("sanoma", {
+    change: {
+        open: {
+            effect: "write",
+            idempotent: true,
+            description: "Open a change: push its draft's branch and open a pull request for it",
+            input: ChangeInput,
+            output: z.object({ number: z.number().int(), url: z.string(), head: z.string(), branch: z.string() }),
+            target,
+            phrases: { expect: "change {id} is opened" },
+        },
+        review: {
+            effect: "write",
+            idempotent: true,
+            description: "Report Sanoma's review of a change on its pull request",
+            input: z.object({
+                ...opened,
+                head: z.string(),
+                state: z.enum(["pending", "failure"]),
+                description: z.string(),
+                page: z.string().url().optional(),
+            }),
+            output: z.object({}),
+            target,
+            phrases: { expect: "change {id} is reviewed" },
+        },
+        merge: {
+            effect: "write",
+            idempotent: true,
+            description: "Merge a change's pull request",
+            input: z.object({ ...opened, head: z.string(), title: z.string(), facts: ChangeFacts }),
+            output: z.object({
+                outcome: z.enum(["merged", "closed", "moved", "blocked"]),
+                sha: z.string().optional(),
+                reason: z.string().optional(),
+            }),
+            target,
+            phrases: { expect: "change {id} is merged" },
+        },
+        close: {
+            effect: "write",
+            idempotent: true,
+            description: "Close a change's pull request without merging it",
+            input: z.object(opened),
+            output: z.object({ closed: z.literal(true) }),
+            target,
+            phrases: { expect: "change {id} is closed" },
+        },
+    },
+});
+/**
+ * The built-in workflow that alone may call `op`, what the operation does and what to do instead:
+ * `apply` for a writable resource type's change operations (`isChangeOp`), `change` for
+ * `sanoma.change.*`; undefined for any other. `resolveConfig` refuses a workflow that uses one, and
+ * a run's call of one outside its workflow fails.
+ */
+export function reservedFor(op, types) {
+    if (isChangeOp(op, types)) {
+        return { workflow: APPLY_WORKFLOW, does: "changes a declared resource", instead: "change the data file" };
+    }
+    if (op.vendor === "sanoma" && op.resource === "change") {
+        return { workflow: CHANGE_WORKFLOW, does: "changes the company's repository", instead: "send a draft for review" };
+    }
+    return undefined;
+}
+const notBuilt = async () => {
+    throw new DriverError("not built", { retryable: false });
+};
+/** A placeholder: lane C5 replaces it with the driver over the repository's host. */
+export function changeDriver() {
+    return defineDriver(changeOps, { change: { open: notBuilt, review: notBuilt, merge: notBuilt, close: notBuilt } });
+}
+/**
+ * Each path, relative to the root with `/` between its parts, and each of its parent directories
+ * with a trailing `/`, sorted, each once: what a rule asks with `touches.contains("resources/finance/")`.
+ */
+export function touchesOf(files) {
+    const touches = new Set();
+    for (const file of files) {
+        touches.add(file);
+        for (let end = file.indexOf("/"); end > 0; end = file.indexOf("/", end + 1))
+            touches.add(file.slice(0, end + 1));
+    }
+    return [...touches].toSorted();
+}
+/** The group the runtime holds a change to the rules for. */
+const ADMIN = "admin";
+/** The paths in `touches` that are the rules whatever `rules` says: the policies, and the template's people file. */
+const RULES = ["policies/", "resources/people.ts"];
+/** The runtime rule's id, as a hold's `reasons` name it. */
+const RULES_WAIT_FOR_ADMIN = "sanoma:rules-wait-for-admin";
+/**
+ * The runtime's own rule, asked before any company policy and under `allowAll` too: a merge of a
+ * change to the rules (`facts.rules`, or `touches` naming `policies/` or `resources/people.ts`) waits for `admin`, whoever made it, until an approval
+ * addressed to `admin` covering the merge is approved; denied while no data file declares the
+ * group. Undefined for anything else, which the company's policy alone decides. `people` are the
+ * running instance's, never the change's, so a change cannot add its author to `admin`.
+ */
+export function runtimeHold(opId, input, approvals, people) {
+    const facts = opId === CHANGE_MERGE ? input.facts : undefined;
+    // The planner's `rules`, or what `touches` already says: a fact left false cannot skip the rule.
+    if (!facts || !(facts.rules || RULES.some((path) => facts.touches.includes(path))))
+        return undefined;
+    if (!groupNamesOf(people).includes(ADMIN)) {
+        return deny(`A change to the policies or the people waits for the group "${ADMIN}", which no data file declares: ` +
+            `declare it in resources/people.ts`, [RULES_WAIT_FOR_ADMIN]);
+    }
+    const approver = { group: ADMIN };
+    if (approvedFor(approvals, CHANGE_MERGE, approver))
+        return undefined;
+    return approve(approver, { title: "A change to the rules waits for admin", reasons: [RULES_WAIT_FOR_ADMIN] });
+}
+//# sourceMappingURL=change.js.map

package/dist/change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change.js","sourceRoot":"","sources":["../src/change.ts"],"names":[],"mappings":"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"}

package/dist/chats.d.ts

@@ -0,0 +1,43 @@
+import type { UIMessage } from "ai";
+import type { Pool } from "pg";
+/** A chat as `SanomaClient.chats.list` reads it. */
+export interface Chat {
+    id: string;
+    /** Whose chat it is: the principal's id. Nobody else reads or continues it. */
+    person: string;
+    /** What runs its turns: `"loop"`, the app's own loop, or another engine the app knows. */
+    engine: string;
+    /** The draft it edits (`Source.draft`), once its first edit opened one. */
+    draftId?: string;
+    title: string;
+    /** When it was opened, in milliseconds since the epoch. */
+    createdAt: number;
+}
+/** The chats' store, `SanomaClient.chats`. */
+export interface Chats {
+    /**
+     * Opens the chat `id` (the browser's) for `person` on `engine`, titled `title`. An id another
+     * chat has is refused (`invalid_input`).
+     */
+    open(chat: {
+        id: string;
+        person: string;
+        engine: string;
+        title: string;
+    }): Promise<void>;
+    /** Records the draft the chat edits. */
+    attach(id: string, draftId: string): Promise<void>;
+    /**
+     * Writes these messages of the chat, each by its id: a message already there is replaced in its
+     * place, a new one goes after the rest, in the order given.
+     */
+    upsert(id: string, messages: readonly UIMessage[]): Promise<void>;
+    /** The chat's messages in order; none for a chat that has none. */
+    load(id: string): Promise<UIMessage[]>;
+    /** The chat `id`, or undefined when there is none. */
+    get(id: string): Promise<Chat | undefined>;
+    /** The person's chats, the newest first: the latest 50. */
+    list(person: string): Promise<Chat[]>;
+}
+/** The chats' store on the pool `db` gives, the config's database once it is prepared. */
+export declare function chatStore(db: () => Promise<Pool>): Chats;

package/dist/chats.js

@@ -0,0 +1,48 @@
+import { CHAT_MESSAGES_TABLE as MESSAGES, CHATS_TABLE as CHATS } from "./db.js";
+import { SanomaError } from "./errors.js";
+const COLUMNS = "id, person, engine, draft_id, title, created_at";
+const chatOf = ({ draft_id, created_at, ...row }) => ({
+    ...row,
+    ...(draft_id === null ? {} : { draftId: draft_id }),
+    createdAt: created_at.getTime(),
+});
+/** The chats' store on the pool `db` gives, the config's database once it is prepared. */
+export function chatStore(db) {
+    return {
+        async open({ id, person, engine, title }) {
+            const { rows } = await (await db()).query(`INSERT INTO ${CHATS} (id, person, engine, title) VALUES ($1, $2, $3, $4) ON CONFLICT (id) DO NOTHING RETURNING id`, [id, person, engine, title]);
+            if (!rows.length)
+                throw new SanomaError("invalid_input", `Chat ${id} exists already; open it with another id`);
+        },
+        async attach(id, draftId) {
+            await (await db()).query(`UPDATE ${CHATS} SET draft_id = $2 WHERE id = $1`, [id, draftId]);
+        },
+        async upsert(id, messages) {
+            if (!messages.length)
+                return;
+            if (messages.some((m) => !m.id))
+                throw new SanomaError("invalid_input", "A chat message needs an id");
+            // A new message's place is after the chat's last, in the order given.
+            await (await db()).query(`INSERT INTO ${MESSAGES} (chat_id, id, seq, message) ` +
+                `SELECT $1, m.value->>'id', last.seq + m.n, m.value ` +
+                `FROM jsonb_array_elements($2::jsonb) WITH ORDINALITY AS m (value, n), ` +
+                `(SELECT coalesce(max(seq), 0) AS seq FROM ${MESSAGES} WHERE chat_id = $1) AS last ` +
+                "ON CONFLICT (chat_id, id) DO UPDATE SET message = EXCLUDED.message", [id, JSON.stringify(messages)]);
+        },
+        async load(id) {
+            const { rows } = await (await db()).query(`SELECT message FROM ${MESSAGES} WHERE chat_id = $1 ORDER BY seq, id`, [id]);
+            return rows.map((row) => row.message);
+        },
+        async get(id) {
+            const { rows } = await (await db()).query(`SELECT ${COLUMNS} FROM ${CHATS} WHERE id = $1`, [id]);
+            return rows[0] && chatOf(rows[0]);
+        },
+        async list(person) {
+            const { rows } = await (await db()).query(`SELECT ${COLUMNS} FROM ${CHATS} WHERE person = $1 ORDER BY created_at DESC, id LIMIT 50`, [
+                person,
+            ]);
+            return rows.map(chatOf);
+        },
+    };
+}
+//# sourceMappingURL=chats.js.map

package/dist/chats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chats.js","sourceRoot":"","sources":["../src/chats.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 import { type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { ApprovalMessage } from "./approvals.ts";
-import { type SanomaConfig } from "./config.ts";
+import { type Chats } from "./chats.ts";
+import { type ResolvedConfig, type SanomaConfig } from "./config.ts";
 import { type CredentialStatus } from "./env.ts";
 import { type ApprovalState, Principal, type WorkflowDefinition } from "./define.ts";
 import { type ApplyInput, type ApplyReport } from "./apply.ts";
@@ -77,6 +78,21 @@ export interface CallOptions {
      */
     id?: string;
 }
+/** What `SanomaClient.connect` is given besides the config. */
+export interface ClientOptions {
+    /**
+     * Called, never awaited, right before each change a worker must run: a run's start (drift,
+     * apply and a held call are starts) and an approval's decision or withdrawal; never for a read. A process that
+     * runs a worker that stops when idle starts it again with it (`Supervisor.resume`). Must not throw.
+     */
+    onWrite?: () => void;
+    /**
+     * The config as the caller resolved it (`resolveConfig(config, options)`), for a client that
+     * shares its drivers with the caller, as `startWorker`'s `resolved` does. The caller closes its
+     * `dataStore`.
+     */
+    resolved?: ResolvedConfig;
+}
 /** Talks to the runtime from another process (the app, a script), through the shared Postgres. */
 export declare class SanomaClient {
     private readonly dbos;
@@ -84,17 +100,20 @@ export declare class SanomaClient {
     private readonly drivers;
     /** The config's own ledger store, or a Postgres one made for this client, which `close` then closes. */
     private readonly audit;
-    /** On the config's database, for the credentials table: opened on first use. */
-    private readonly credentialsPool;
+    /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
+    private readonly pool;
     /** What a direct call's driver reads secrets from, as a worker's live driver does. */
     private readonly storedSecrets;
+    /** The operator agent's chats: their rows and their transcripts, in the config's database. */
+    readonly chats: Chats;
+    private readonly options;
     private constructor();
     /**
      * Connects to the runtime's Postgres for the config's app. Checks the config first and throws
      * what the worker would refuse. Reads ledgers from the config's ledger store, or from the
      * Postgres store on its database when it has none.
      */
-    static connect(config: SanomaConfig): Promise<SanomaClient>;
+    static connect(config: SanomaConfig, options?: ClientOptions): Promise<SanomaClient>;
     /**
      * Checks the input against the workflow's schema, then queues a run for the worker. The run
      * gets the input as sent, not as the schema parsed it: the worker parses it once, so a schema
@@ -177,6 +196,33 @@ export declare class SanomaClient {
     decide(runId: string, message: ApprovalMessage, approvalId?: string, options?: {
         timeoutSeconds?: number;
     }): Promise<ApprovalState>;
+    /**
+     * Withdraws the run's pending approval `approvalId`, saying `reason`, as `options.by`: the run's
+     * starter, or someone who may decide it (`not_approver` otherwise, here and again in the run,
+     * which records who withdrew it). The run reads the
+     * withdrawal as a decision, and the step that waits on it throws `approval_withdrawn`. Returns
+     * the approval as withdrawn, and refuses as `decide` does: `already_decided` when it is not
+     * pending (or another decision reached the run first), `run_ended`, `no_pending_approval`,
+     * `run_not_found`; and returns it still `pending` when the run does not read the withdrawal
+     * within `timeoutSeconds` (30 by default).
+     */
+    withdraw(runId: string, approvalId: string, reason: string, options: {
+        by: Principal | string;
+        timeoutSeconds?: number;
+    }): Promise<ApprovalState>;
+    /**
+     * The run's approval `approvalId` (else its first pending one) and the run's row, when the
+     * approval is pending on a run that has not ended: `already_decided`, `run_ended`,
+     * `no_pending_approval` or `run_not_found` otherwise.
+     */
+    private pendingApproval;
+    /**
+     * Sends a message with an `id` to the approval and waits up to `timeoutSeconds` (30 by
+     * default) for the run to read it: the approval as the run then has it, still `pending` if it
+     * has not read it. `not_approver` when the run refused it, `already_decided` when another
+     * message decided it first.
+     */
+    private sendToApproval;
     /**
      * The run's output once it ends, or its error. Throws `run_running` when it has not ended
      * within `timeoutMs`; the run goes on.
@@ -253,8 +299,8 @@ export declare class SanomaClient {
      * `invalid_input` when none does.
      */
     private declared;
-    /** The pool the credentials are read and written with, on the database once it is prepared. */
-    private credentialsDb;
+    /** The pool the runtime's tables are read and written with, on the database once it is prepared. */
+    private db;
     /**
      * The principal as the data files declare it (`admit`): its id alone is taken, never the groups
      * a caller gives, and an id nobody declares is `not_admitted`.