@cloudhal/agent-runtime 0.0.0-stage → 0.1.1

package/dist/src/roles.js

@@ -0,0 +1,292 @@
+/**
+ * Staff roles (RFC-0005 §2, ADR-0018): named sets of the policy engine's scopes, so people and
+ * agents stay one kind of actor and an agent key never does more than the person who created it.
+ * This module is the single source for the policy engine, REST, MCP and Studio (via `/api/instance`).
+ */
+import { AGENT_MODES,                 isMoreAutonomous, REMOTE_AGENT_MODES } from "./modes.js";
+import { holds, isKeyScope, KEY_SCOPES,             weakerScopes } from "./policy.js";
+
+                                                                                   
+
+/** Highest rank first: Owner > Administrator > Editor > Author > Contributor. */
+export const ROLES                  = ["owner", "administrator", "editor", "author", "contributor"];
+
+export function isRole(value         )                {
+  return typeof value === "string" && (ROLES                     ).includes(value);
+}
+
+/** Higher is more senior. */
+export function rank(role      )         {
+  return ROLES.length - ROLES.indexOf(role);
+}
+
+// RFC-0016 (D6): every role may use in-editor AI; the owner's switch and the daily cap limit it.
+const READ          = ["site:read", "content:read", "preview:create", "ai:invoke"];
+const EDITOR          = [
+  ...READ,
+  "content:write",
+  "site:publish",
+  "site:rollback",
+  "site:write",
+  "asset:manage",
+  "audit:read",
+  "members:invite",
+  "analytics:read",
+  // RFC-0007 §10.1 (D6): every comment; commenter emails through the person-only scope.
+  "comments:read",
+  "comments:moderate",
+  "comments:reply",
+  "commenters:data",
+  // RFC-0008 §10.2: every release and gate (`releases:publish` comes with `site:publish`), and
+  // automations — an automation's key is narrowed to its owner's role on every call (ADR-0018).
+  "schedules:read",
+  "schedules:write",
+  "automations:manage",
+];
+
+/**
+ * Role → scopes (RFC-0005 §2.1). Implied scopes are not repeated. The Owner holds `*`, so a future
+ * scope reaches the Owner without a migration; Administrator holds every non-wildcard scope.
+ */
+export const ROLE_SCOPES                                           = {
+  // RFC-0008 §10.2: Contributors read the schedule and make draft releases and requests of their
+  // own work; they approve nothing.
+  contributor: [
+    ...READ,
+    "content:draft:own",
+    "asset:upload",
+    "schedules:read",
+    "schedules:write:own",
+  ],
+  // RFC-0006 §9.1: Authors and above read analytics; Contributors do not in v1.
+  // RFC-0007 §10.1 (D6): Authors read comments and moderate and reply on their own entries;
+  // Contributors get no comment scopes in v1.
+  // RFC-0008 §10.2: Authors schedule and approve their own releases (`releases:publish:own`
+  // comes with `site:publish:own`).
+  author: [
+    ...READ,
+    "content:write:own",
+    "site:publish:own",
+    "asset:upload",
+    "analytics:read",
+    "comments:read",
+    "comments:moderate:own",
+    "comments:reply:own",
+    "schedules:read",
+    "schedules:write:own",
+  ],
+  editor: EDITOR,
+  administrator: [...EDITOR, "site:settings", "members:manage", "agents:manage", "site:create"],
+  owner: ["*"],
+};
+
+export function roleScopes(role      )          {
+  return [...ROLE_SCOPES[role]];
+}
+
+/**
+ * The most autonomous mode a key created by this role may hold (RFC-0005 §5.2): a Contributor has
+ * no publish power, so `auto` would be meaningless. `bypass` stays local only.
+ */
+export function modeCap(role      )            {
+  return role === "contributor" ? "edits" : "auto";
+}
+
+export const MODE_CAPS                                    = Object.fromEntries(
+  ROLES.map((r) => [r, modeCap(r)]),
+)                           ;
+
+/** `mode`, lowered to `cap` when it is more autonomous. */
+export function clampMode(mode           , cap           )            {
+  return isMoreAutonomous(mode, cap) ? cap : mode;
+}
+
+/** Remote modes a role's keys may hold, least autonomous first. */
+export function modesFor(role      )              {
+  const cap = modeCap(role);
+  return REMOTE_AGENT_MODES.filter((m) => AGENT_MODES.indexOf(m) <= AGENT_MODES.indexOf(cap));
+}
+
+/**
+ * Narrows a key's scopes to a role (RFC-0005 §5.1): keeps each key scope the role holds; else the
+ * strongest weaker variant the role holds; else drops it. Person-only scopes and `*` never survive
+ * on a key (I7).
+ *
+ * `narrow(["content:write","site:publish"], author)` → `["content:write:own","site:publish:own"]`.
+ */
+export function narrow(keyScopes                   , roleScopeSet                  )          {
+  const out          = [];
+  const add = (s       ) => {
+    if (!out.includes(s)) out.push(s);
+  };
+  for (const k of keyScopes) {
+    if (k === "*") {
+      for (const s of KEY_SCOPES) if (holds(roleScopeSet, s)) add(s);
+      continue;
+    }
+    if (!isKeyScope(k)) continue;
+    if (holds(roleScopeSet, k)) add(k);
+    else {
+      const weaker = weakerScopes(k).find((w) => holds(roleScopeSet, w));
+      if (weaker) add(weaker);
+    }
+  }
+  return out;
+}
+
+/** Scopes a key requested that the role cannot give it (after narrowing nothing is dropped). */
+export function scopesAboveRole(requested                  , role      )          {
+  return requested.filter((s) => !holds(ROLE_SCOPES[role], s));
+}
+
+/** Why a member action breaks the rank rule (RFC-0005 §3, I4, I12), as data. */
+                         
+          
+                
+                     
+                   
+                  
+
+const RANK_TEXT                              = {
+  self: "nobody changes their own role or removes themselves",
+  owner_role: "the owner role moves only by ownership transfer",
+  target_is_owner: "the Owner cannot be demoted or removed; transfer ownership first",
+  role_too_high: "your role cannot give this role",
+  not_allowed: "your role cannot manage members",
+};
+
+export function describeRankProblem(problem             )         {
+  return RANK_TEXT[problem];
+}
+
+/** May `inviter` invite someone as `role`? Editors invite Contributors and Authors only (†). */
+export function inviteProblem(inviter      , role      )                          {
+  if (role === "owner") return "owner_role";
+  const scopes = ROLE_SCOPES[inviter];
+  if (holds(scopes, "members:manage")) return undefined;
+  if (!holds(scopes, "members:invite")) return "not_allowed";
+  return role === "contributor" || role === "author" ? undefined : "role_too_high";
+}
+
+export function canInvite(inviter      , role      )          {
+  return inviteProblem(inviter, role) === undefined;
+}
+
+/** Roles `inviter` may invite, highest first. */
+export function invitableRoles(inviter      )         {
+  return ROLES.filter((r) => canInvite(inviter, r));
+}
+
+                            
+                 
+             
+ 
+
+/** May `actor` change `target`'s role to `to`? */
+export function roleChangeProblem(
+  actor           ,
+  target           ,
+  to      ,
+)                          {
+  if (actor.userId === target.userId) return "self";
+  if (!holds(ROLE_SCOPES[actor.role], "members:manage")) return "not_allowed";
+  if (target.role === "owner") return "target_is_owner";
+  if (to === "owner") return "owner_role";
+  return undefined;
+}
+
+/** May `actor` remove `target`? */
+export function removalProblem(actor           , target           )                          {
+  if (actor.userId === target.userId) return "self";
+  if (!holds(ROLE_SCOPES[actor.role], "members:manage")) return "not_allowed";
+  if (target.role === "owner") return "target_is_owner";
+  return undefined;
+}
+
+/**
+ * What a person can do, for UI gating (RFC-0005 I16: cosmetic; the server decides). Each ability
+ * is a scope check except `ownership.transfer` (Owner only).
+ */
+export const ABILITIES = {
+  "entries.create": "content:draft:own",
+  "entries.editOwnPublished": "content:write:own",
+  "entries.editAny": "content:write",
+  "pages.write": "content:write",
+  "publish.own": "site:publish:own",
+  "publish.any": "site:publish",
+  rollback: "site:rollback",
+  "structure.write": "site:write",
+  "assets.upload": "asset:upload",
+  "assets.manage": "asset:manage",
+  "activity.all": "audit:read",
+  "settings.write": "site:settings",
+  "members.invite": "members:invite",
+  "members.manage": "members:manage",
+  "agents.manage": "agents:manage",
+  // RFC-0034 §3: creating sites in Studio.
+  "sites.create": "site:create",
+  // RFC-0006 §9.1: reading analytics; changing the site's analytics settings (Administrator).
+  "analytics.read": "analytics:read",
+  "analytics.settings": "site:settings",
+  // RFC-0007 §10.1: the comment queue; moderating and replying (`:own` on one's own entries is
+  // enough for the first of each pair); commenter emails and erasure; the site's comment settings.
+  "comments.read": "comments:read",
+  "comments.moderate": "comments:moderate:own",
+  "comments.moderateAny": "comments:moderate",
+  "comments.reply": "comments:reply:own",
+  "comments.replyAny": "comments:reply",
+  "commenters.data": "commenters:data",
+  "comments.settings": "site:settings",
+  // RFC-0008 §10.1: the calendar; releases and gates of one's own nodes, and of anyone's;
+  // approving releases (own, any); automations; the kill switch and daily cap.
+  "schedules.read": "schedules:read",
+  "schedules.write": "schedules:write:own",
+  "schedules.writeAny": "schedules:write",
+  "releases.approve": "releases:publish:own",
+  "releases.approveAny": "releases:publish",
+  "automations.manage": "automations:manage",
+  "schedules.settings": "site:settings",
+  // RFC-0016: in-editor AI commands; the site's AI settings (Administrator).
+  "ai.invoke": "ai:invoke",
+  "ai.settings": "site:settings",
+  "ownership.transfer": "owner",
+}                                                   ;
+
+                                             
+
+/** The ability map for a person (`role` undefined: no membership source, everything allowed). */
+export function abilities(
+  role                  ,
+  scopes                  ,
+)                           {
+  return Object.fromEntries(
+    Object.entries(ABILITIES).map(([ability, need]) => [
+      ability,
+      need === "owner" ? role === undefined || role === "owner" : holds(scopes, need),
+    ]),
+  )                            ;
+}
+
+/** Invite expiry (RFC-0005 §7.1): 7 days by default, 1 hour to 14 days, Administrator ≤ 72 h. */
+export const INVITE_DEFAULT_HOURS = 7 * 24;
+export const INVITE_MIN_HOURS = 1;
+export const INVITE_MAX_HOURS = 14 * 24;
+export const INVITE_ADMIN_MAX_HOURS = 72;
+
+/** The longest an invite for `role` may last. */
+export function inviteMaxHours(role      )         {
+  return role === "administrator" ? INVITE_ADMIN_MAX_HOURS : INVITE_MAX_HOURS;
+}
+
+/** Why an expiry is refused for an invite as `role`, or undefined. */
+export function inviteExpiryProblem(role      , hours        )                     {
+  const max = inviteMaxHours(role);
+  if (!Number.isInteger(hours) || hours < INVITE_MIN_HOURS || hours > max)
+    return `expiresInHours must be a whole number between ${INVITE_MIN_HOURS} and ${max}${role === "administrator" ? " for Administrator invites" : ""}`;
+  return undefined;
+}
+
+/** The default expiry for an invite as `role` (Administrator invites are capped). */
+export function inviteDefaultHours(role      )         {
+  return Math.min(INVITE_DEFAULT_HOURS, inviteMaxHours(role));
+}

package/dist/src/site-access.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-site roles (RFC-0034 §2, phase A2; RFC-0005 open question 10). The Owner and Administrators
+ * act on every site of the installation. An Editor, Author or Contributor with site assignments
+ * works only on those sites, each with its own role (never above Editor); without assignments
+ * their installation role applies to every site, as before.
+ *
+ * REST and MCP resolve the principal once per request, before the site is known; `forSite` turns it
+ * into the principal for one site, so every later check (scopes, own-only limits, mode caps,
+ * approvals) sees that site's role.
+ */
+import type { PersonRef, Principal } from "./policy.js";
+import { type Role } from "./roles.js";
+/** Roles that may be limited to sites; Owner and Administrators always cover the installation. */
+export declare const SITE_ROLES: readonly Role[];
+export declare function isSiteRole(role: Role): boolean;
+/** True when the person works only on assigned sites. */
+export declare function isSiteLimited(person: PersonRef | undefined): boolean;
+/** The person's role on `siteId`, or undefined when they may not open it. */
+export declare function siteRoleOf(person: PersonRef, siteId: string): Role | undefined;
+/** The sites among `siteIds` the principal may open (all of them when it is not site-limited). */
+export declare function visibleSites<T extends string>(principal: Principal | undefined, siteIds: readonly T[]): T[];
+/**
+ * The principal as it acts on `siteId`: undefined when it may not open the site; otherwise its
+ * scopes and the person's role are that site's. An agent's own key scopes are narrowed to the
+ * site role again, and its mode is capped by it (I5, I6).
+ */
+export declare function forSite(principal: Principal, siteId: string): Principal | undefined;
+/**
+ * Scopes that act on the whole installation (its team, its activity, every agent): a site-limited
+ * person does not hold them outside a site, so they cannot invite people or read installation-wide
+ * activity. Inside one of their sites, `forSite` gives that site's role.
+ */
+export declare const INSTALLATION_SCOPES: readonly string[];
+/** The principal outside any one site: a site-limited person loses `INSTALLATION_SCOPES`. */
+export declare function forInstallation(principal: Principal): Principal;

package/dist/src/site-access.js

@@ -0,0 +1,81 @@
+/**
+ * Per-site roles (RFC-0034 §2, phase A2; RFC-0005 open question 10). The Owner and Administrators
+ * act on every site of the installation. An Editor, Author or Contributor with site assignments
+ * works only on those sites, each with its own role (never above Editor); without assignments
+ * their installation role applies to every site, as before.
+ *
+ * REST and MCP resolve the principal once per request, before the site is known; `forSite` turns it
+ * into the principal for one site, so every later check (scopes, own-only limits, mode caps,
+ * approvals) sees that site's role.
+ */
+                                                        
+import { clampMode, modeCap, narrow,            roleScopes } from "./roles.js";
+
+/** Roles that may be limited to sites; Owner and Administrators always cover the installation. */
+export const SITE_ROLES                  = ["editor", "author", "contributor"];
+
+export function isSiteRole(role      )          {
+  return SITE_ROLES.includes(role);
+}
+
+/** True when the person works only on assigned sites. */
+export function isSiteLimited(person                       )          {
+  return person?.sites !== undefined && isSiteRole(person.role);
+}
+
+/** The person's role on `siteId`, or undefined when they may not open it. */
+export function siteRoleOf(person           , siteId        )                   {
+  if (!isSiteLimited(person)) return person.role;
+  return person.sites?.[siteId];
+}
+
+/** The sites among `siteIds` the principal may open (all of them when it is not site-limited). */
+export function visibleSites                  (
+  principal                       ,
+  siteIds              ,
+)      {
+  const person = principal?.person;
+  if (!person || !isSiteLimited(person)) return [...siteIds];
+  return siteIds.filter((id) => person.sites?.[id] !== undefined);
+}
+
+/**
+ * The principal as it acts on `siteId`: undefined when it may not open the site; otherwise its
+ * scopes and the person's role are that site's. An agent's own key scopes are narrowed to the
+ * site role again, and its mode is capped by it (I5, I6).
+ */
+export function forSite(principal           , siteId        )                        {
+  const person = principal.person;
+  if (!person || !isSiteLimited(person)) return principal;
+  const role = person.sites?.[siteId];
+  if (!role) return undefined;
+  const sitePerson            = { ...person, role };
+  if (principal.actor.kind !== "agent")
+    return { ...principal, scopes: roleScopes(role), person: sitePerson };
+  const mode = principal.mode;
+  return {
+    ...principal,
+    scopes: narrow(principal.keyScopes ?? principal.scopes, roleScopes(role)),
+    person: sitePerson,
+    ...(mode ? { mode: clampMode(mode, modeCap(role)) } : {}),
+  };
+}
+
+/**
+ * Scopes that act on the whole installation (its team, its activity, every agent): a site-limited
+ * person does not hold them outside a site, so they cannot invite people or read installation-wide
+ * activity. Inside one of their sites, `forSite` gives that site's role.
+ */
+export const INSTALLATION_SCOPES                    = [
+  "members:invite",
+  "members:manage",
+  "agents:manage",
+  "audit:read",
+  "site:create",
+];
+
+/** The principal outside any one site: a site-limited person loses `INSTALLATION_SCOPES`. */
+export function forInstallation(principal           )            {
+  if (!isSiteLimited(principal.person)) return principal;
+  return { ...principal, scopes: principal.scopes.filter((s) => !INSTALLATION_SCOPES.includes(s)) };
+}

package/dist/src/skills.d.ts

@@ -0,0 +1,47 @@
+import { type SkillManifest } from "@cloudhal/core-contracts";
+export interface LoadedSkill {
+    manifest: SkillManifest;
+    /** Directory of the skill. */
+    dir: string;
+    /** Markdown body (after the frontmatter). Loaded lazily via `body()` for progressive disclosure. */
+    body: () => Promise<string>;
+    /** The full SKILL.md source (frontmatter included), as served over MCP resources. */
+    source: () => Promise<string>;
+    references: () => Promise<string[]>;
+    /** Reads one file from `references/` by name; throws for names outside that directory. */
+    reference: (name: string) => Promise<string>;
+    cloudhal: {
+        schemaVersion: number;
+        requiresCapabilities: string[];
+        scopes: string[];
+        approval: string[];
+    };
+}
+export declare class SkillError extends Error {
+    readonly name = "SkillError";
+}
+/** Minimal YAML frontmatter parser for the six spec fields (strings and a flat string map). */
+export declare function parseFrontmatter(markdown: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/** A skill as plain data (SKILL.md text + reference files), e.g. bundled into a Worker. */
+export interface SkillSource {
+    /** Directory name; must equal the manifest `name`. */
+    name: string;
+    markdown: string;
+    references: Record<string, string>;
+}
+/**
+ * Builds a `LoadedSkill` from data — no filesystem. Validates the manifest against the
+ * `SkillManifest` contract and the `cloudhal.*` metadata keys.
+ */
+export declare function skillFromSource(source: SkillSource, dir?: string): LoadedSkill;
+/** Reads one skill directory into a `SkillSource` (Node). */
+export declare function readSkillSource(dir: string): Promise<SkillSource>;
+/** Reads every skill under `root` (one directory per skill), sorted by name. */
+export declare function readSkillSources(root: string): Promise<SkillSource[]>;
+/** Loads one skill directory: validates the manifest against the `SkillManifest` contract and the `cloudhal.*` metadata keys. */
+export declare function loadSkill(dir: string): Promise<LoadedSkill>;
+/** Loads every skill under `root` (one directory per skill). Sorted by name for deterministic listings. */
+export declare function loadSkills(root: string): Promise<LoadedSkill[]>;

package/dist/src/skills.js

@@ -0,0 +1,151 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { assertValid,                    } from "@cloudhal/core-contracts";
+
+                              
+                          
+                                
+              
+                                                                                                      
+                              
+                                                                                       
+                                
+                                      
+                                                                                            
+                                               
+             
+                          
+                                   
+                     
+                       
+    
+ 
+
+export class SkillError extends Error {
+                    name = "SkillError";
+}
+
+/** Minimal YAML frontmatter parser for the six spec fields (strings and a flat string map). */
+export function parseFrontmatter(markdown        )   
+                                       
+               
+  {
+  const m = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) throw new SkillError("SKILL.md must start with YAML frontmatter");
+  const fm                          = {};
+  let currentMap                                    ;
+  for (const raw of (m[1]          ).split(/\r?\n/)) {
+    if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    const nested = raw.match(/^\s+([^:]+):\s*(.*)$/);
+    if (nested && currentMap) {
+      currentMap[nested[1]          ] = unquote((nested[2]          ).trim());
+      continue;
+    }
+    const top = raw.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (!top) throw new SkillError(`invalid frontmatter line: ${raw}`);
+    const [, key, value] = top                                       ;
+    if (value.trim() === "") {
+      currentMap = {};
+      fm[key] = currentMap;
+    } else {
+      currentMap = undefined;
+      fm[key] = unquote(value.trim());
+    }
+  }
+  return { frontmatter: fm, body: m[2]           };
+}
+
+function unquote(v        )         {
+  return (v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))
+    ? v.slice(1, -1)
+    : v;
+}
+
+function list(value                    )           {
+  return (value ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** A skill as plain data (SKILL.md text + reference files), e.g. bundled into a Worker. */
+                              
+                                                        
+               
+                   
+                                     
+ 
+
+/**
+ * Builds a `LoadedSkill` from data — no filesystem. Validates the manifest against the
+ * `SkillManifest` contract and the `cloudhal.*` metadata keys.
+ */
+export function skillFromSource(source             , dir = `skill:${source.name}`)              {
+  const { frontmatter, body } = parseFrontmatter(source.markdown);
+  assertValid("skill-manifest", frontmatter);
+  const manifest = frontmatter;
+  if (manifest.name !== source.name)
+    throw new SkillError(`skill name "${manifest.name}" must match directory "${source.name}"`);
+  const meta = manifest.metadata ?? {};
+  const schemaVersion = Number(meta["cloudhal.schemaVersion"] ?? "1");
+  if (schemaVersion !== 1)
+    throw new SkillError(`${manifest.name}: unsupported cloudhal.schemaVersion ${schemaVersion}`);
+  const refs = Object.keys(source.references)
+    .filter((f) => f.endsWith(".md"))
+    .sort();
+  return {
+    manifest,
+    dir,
+    body: async () => body,
+    source: async () => source.markdown,
+    reference: async (name) => {
+      if (!refs.includes(name)) throw new SkillError(`invalid reference name "${name}"`);
+      return source.references[name]          ;
+    },
+    references: async () => refs,
+    cloudhal: {
+      schemaVersion,
+      requiresCapabilities: list(meta["cloudhal.requiresCapabilities"]),
+      scopes: list(meta["cloudhal.scopes"]),
+      approval: list(meta["cloudhal.approval"]),
+    },
+  };
+}
+
+/** Reads one skill directory into a `SkillSource` (Node). */
+export async function readSkillSource(dir        )                       {
+  const markdown = await readFile(path.join(dir, "SKILL.md"), "utf8");
+  const references                         = {};
+  const refDir = path.join(dir, "references");
+  try {
+    if ((await stat(refDir)).isDirectory())
+      for (const f of (await readdir(refDir)).filter((x) => x.endsWith(".md")).sort())
+        references[f] = await readFile(path.join(refDir, f), "utf8");
+  } catch {
+    // no references
+  }
+  return { name: path.basename(dir), markdown, references };
+}
+
+/** Reads every skill under `root` (one directory per skill), sorted by name. */
+export async function readSkillSources(root        )                         {
+  const entries = await readdir(root, { withFileTypes: true });
+  const sources = await Promise.all(
+    entries.filter((e) => e.isDirectory()).map((e) => readSkillSource(path.join(root, e.name))),
+  );
+  return sources.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Loads one skill directory: validates the manifest against the `SkillManifest` contract and the `cloudhal.*` metadata keys. */
+export async function loadSkill(dir        )                       {
+  return skillFromSource(await readSkillSource(dir), dir);
+}
+
+/** Loads every skill under `root` (one directory per skill). Sorted by name for deterministic listings. */
+export async function loadSkills(root        )                         {
+  const entries = await readdir(root, { withFileTypes: true });
+  const skills = await Promise.all(
+    entries.filter((e) => e.isDirectory()).map((e) => loadSkill(path.join(root, e.name))),
+  );
+  return skills.sort((a, b) => a.manifest.name.localeCompare(b.manifest.name));
+}

package/dist/src/taxonomy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent-layer rules for taxonomies and redirects (RFC-0002 §6.4). Data invariants (limits, required
+ * terms, slugs) live in core-ts; what an *agent* may do — create terms, point redirects off-site,
+ * approve proposals — is decided here, the same for every transport.
+ */
+import type { Actor } from "@cloudhal/core-contracts";
+import { type Principal } from "./policy.js";
+/** `Taxonomy.allowNewTerms`. */
+export type AllowNewTerms = "none" | "propose" | "free";
+/** What a term created by an actor becomes, or why it may not be created. */
+export type TermCreation = {
+    readonly allowed: true;
+    readonly status: "active" | "proposed";
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/**
+ * Invariant 11 for an actor: people (and the system) create active terms; agents create proposed
+ * terms under `propose`, active ones under `free`, and none under `none` ("ask a person").
+ *
+ * Given a principal, a person whose role lacks `site:write` (Contributor, Author; RFC-0005 §2.2) is
+ * treated like an agent: they propose tags and never add categories.
+ */
+export declare function termCreation(who: Actor | Pick<Principal, "actor" | "scopes">, allowNewTerms: AllowNewTerms): TermCreation;
+/**
+ * Why an actor may not point a redirect at `to`, or undefined. Agents redirect to paths of the same
+ * site only; an external target (open-redirect risk) is a person's decision (RFC-0002, Security).
+ */
+export declare function redirectTargetProblem(actor: Actor, to: string): string | undefined;
+/** A review decision on a proposed term. */
+export type TermReviewDecision = "approve" | "reject" | "merge";
+/**
+ * Why an actor may not take a review decision on a term, or undefined. An agent never approves a
+ * term it proposed itself (the person's review is the point of `propose`).
+ */
+export declare function termReviewProblem(actor: Actor, term: {
+    readonly proposedBy?: Actor | undefined;
+}, decision: TermReviewDecision): string | undefined;
+/** Freeing an old slug (`reclaim`) deletes a redirect people may rely on: people only. */
+export declare function reclaimProblem(actor: Actor): string | undefined;