@agentproto/role-catalog 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy André and agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import { BuiltinRoleEntry, BuiltinRoleSource } from '@agentproto/role';
+import { PolicyHandle } from '@agentproto/policy';
+
+/**
+ * AIP-47 builtin role catalogue.
+ *
+ * Twenty starter role manifests covering common positions across the
+ * nine recommended departments. Each entry pairs a validated
+ * `RoleHandle` (per AIP-47 ROLE.schema.json) with a body markdown
+ * (background / working principles / escalation rules).
+ *
+ * Doctype-agnostic: a role describes a job, not who holds it. Any
+ * AIP-9 OPERATOR or human member can wear any role in this catalogue.
+ * Consumers wanting to bias their UI toward common patterns
+ * (e.g. surfacing manager-level roles before C-suite in a "hire AI
+ * worker" flow) do that through curation / tags / sort order, not
+ * through a typed `audience` field on the manifest.
+ *
+ * Consumers compose this catalogue into a resolver chain through
+ * `builtinRoleSource()` (re-exported from the package index).
+ */
+
+declare const BUILTIN_ROLE_ENTRIES: readonly BuiltinRoleEntry[];
+/** Slugs of every builtin shipped in this catalogue, in display order. */
+declare const BUILTIN_ROLE_SLUGS: readonly string[];
+/**
+ * Mapping from Guilde's legacy `OperatorRole` enum to a builtin slug
+ * in this catalogue. Used by migration scripts to backfill
+ * `operators.role_slug` from the existing `operators.role` text.
+ *
+ * Renames per Prakash 2026-05-11 — no CXO branding for AI workers
+ * (those titles are reserved for the human executive).
+ */
+declare const LEGACY_GUILDE_ROLE_MAP: Readonly<Record<string, string>>;
+
+/**
+ * Companion baseline policies for builtin roles (AIP-38).
+ *
+ * A role's `defaultPolicy` is ADVISORY per AIP-47 — the runtime MUST NOT
+ * auto-apply it without the operator's own `policy:` field or a
+ * governance signature attesting the binding. These manifests are the
+ * portable declaration of intent that travels with the role; binding
+ * them to an operator (and compiling grants into a host's enforcement
+ * surface) is a governed, host-side step.
+ *
+ * Authored as validated TS `definePolicy` objects — same shipping shape
+ * as the role seeds — so every field-level constraint runs at module
+ * load and the policy is bundleable alongside the catalogue.
+ */
+
+/**
+ * Baseline policy for `talent-acquisition-specialist`.
+ *
+ * `default: deny` — the operator may only perform the recruiting actions
+ * explicitly granted (sourcing, screening, candidate messaging, document
+ * generation, scheduling, KPI computation). The hire DECISION actions
+ * (`hiring:extend-offer`, `hiring:reject-candidate`) are gated behind a
+ * human approval requirement rather than granted — the hiring manager
+ * decides. Finance / payroll and sensitive-data actions are never granted,
+ * so `default: deny` denies them.
+ */
+declare const talentAcquisitionBaselinePolicy: PolicyHandle;
+/** Baseline policies shipped alongside the builtin role catalogue. */
+declare const BUILTIN_POLICY_HANDLES: readonly PolicyHandle[];
+
+/**
+ * @agentproto/role-catalog — AIP-47 reference catalogue of builtin roles.
+ *
+ * Ships twenty starter ROLE.md manifests spanning the nine recommended
+ * departments. Each entry is a validated `RoleHandle` (per
+ * `@agentproto/role`'s `ROLE.schema.json`) paired with body markdown
+ * covering background, working principles, and escalation.
+ *
+ * Roles are **doctype-agnostic**: any AIP-9 OPERATOR or human member
+ * can wear any of these manifests. Curation / sort order / soft tags
+ * in consumer UIs handle positioning concerns (e.g. "manager-level
+ * roles are more typical for AI workers than C-suite ones in 2026"),
+ * not a typed `audience` field on the manifest.
+ *
+ * Process-wide singleton — `builtinRoleSource()` returns the SAME
+ * `BuiltinRoleSource` on every call (backed by an AIP-43 registry).
+ * Downstream apps may extend the catalogue via `registerBuiltinRoles`
+ * without forking the OSS package:
+ *
+ *   import { registerBuiltinRoles } from "@agentproto/role-catalog"
+ *   registerBuiltinRoles([
+ *     { slug: "guild-admin", handle: {...}, body: "..." },
+ *   ])
+ *
+ * Composing the catalogue into a resolver chain:
+ *
+ *   import { resolveRole } from "@agentproto/role"
+ *   import { builtinRoleSource } from "@agentproto/role-catalog"
+ *
+ *   const result = await resolveRole("marketing-manager", {
+ *     sources: [builtinRoleSource()],
+ *   })
+ *
+ * Spec: https://agentproto.sh/docs/aip-47
+ */
+
+/**
+ * Return the process-wide singleton `BuiltinRoleSource`. Wraps the
+ * OSS catalogue (20 starters) plus any entries registered through
+ * `registerBuiltinRoles`. Safe to call from any module at any time —
+ * the registry is lazily bootstrapped on first access.
+ */
+declare function builtinRoleSource(): BuiltinRoleSource;
+/**
+ * Register additional builtin roles into the process-wide registry.
+ * Use this when a downstream package (a vendor runtime, a host app)
+ * ships its own builtin roles ALONGSIDE the OSS catalogue without
+ * forking `@agentproto/role-catalog`.
+ *
+ * Throws `RegistryDuplicateError` from `@agentproto/registry` if a
+ * slug already exists — the catalogue is intended to be additive,
+ * not overwriting. Call `replaceBuiltinRole(entry)` if a slug rev
+ * needs to swap atomically.
+ *
+ * Boot-time call site is the right pattern — every consumer of
+ * `builtinRoleSource()` after `registerBuiltinRoles` sees the
+ * additions.
+ */
+declare function registerBuiltinRoles(entries: Iterable<BuiltinRoleEntry>): void;
+/**
+ * Replace an existing builtin role with a new version of the same
+ * slug. Throws `RegistryNotFoundError` if no entry exists at the
+ * slug — use `registerBuiltinRoles` for new slugs.
+ */
+declare function replaceBuiltinRole(entry: BuiltinRoleEntry): void;
+/**
+ * Remove a builtin role from the registry. Returns true if the slug
+ * was present. Use sparingly — the registry is intended to be
+ * boot-time-stable; mid-flight unregister of an OSS starter risks
+ * resolver fall-through to file/db sources mid-conversation.
+ */
+declare function unregisterBuiltinRole(slug: string): boolean;
+
+export { BUILTIN_POLICY_HANDLES, BUILTIN_ROLE_ENTRIES, BUILTIN_ROLE_SLUGS, LEGACY_GUILDE_ROLE_MAP, builtinRoleSource, registerBuiltinRoles, replaceBuiltinRole, talentAcquisitionBaselinePolicy, unregisterBuiltinRole };