@agentproto/role 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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/README.md

@@ -0,0 +1,23 @@
+# @agentproto/role
+
+AIP-47 `ROLE.md` reference implementation. A single-doc markdown + frontmatter format for portable organizational roles — mission, responsibilities, capabilities, tools, KPIs, seniority, reporting line, lifecycle hooks. Sibling to AIP-25 PERSONA (face) and AIP-23 IDENTITY (substance); referenced by AIP-9 OPERATOR (`role:` field) and AIP-6 COMPANY (`roles/<slug>/ROLE.md` doctype). Roles describe what a job is — independent of who holds it (persona/identity) and which instance is hired (operator).
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-47>
+
+## Usage
+
+```ts
+import { defineRole } from "@agentproto/role"
+
+const x = defineRole({
+  id: "my-role",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-U2HQWFCN.mjs

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/role v0.1.0-alpha
+ * AIP-47 ROLE.md `defineRole` reference implementation.
+ */
+
+var roleFrontmatterSchema = z.object({ "schema": z.literal("role/v1").describe("Schema dispatch tag. MUST be 'role/v1' for this version of AIP-47."), "name": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(2).max(64).describe("Machine identifier. Lowercase, digits, dashes. Must start with a letter, end with a letter or digit. Unique within the registry that hosts the role."), "title": z.string().min(1).max(120).describe("Human-readable display title, sentence case."), "description": z.string().min(1).max(2e3).describe("One-paragraph job description. The role's purpose, audience, and shape."), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][a-zA-Z0-9.-]+)?$")).describe("Semver. Bump on breaking change to responsibilities, KPIs, tools, or seniority."), "extends": z.string().min(1).describe("Reference to a parent ROLE. Triggers composition. Accepts any ref form in AIP-47 \xA7Reference syntax: bare slug, scoped slug (builtin/<slug>, file/<path>, db/<id>), ws:// URI, or fully-qualified URL. Path-form refs SHOULD end in 'ROLE.md'.").optional(), "department": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(1).max(80).describe("Department slug. Lowercase kebab-case. Recommended values listed in AIP-47 \xA7Departments; free-form to accept domain-specific values.").optional(), "reports_to": z.string().min(1).describe("Role-to-role reporting link. Conventionally a 'ws://roles/<slug>' ref. Schema does not validate scheme; the loader resolves.").optional(), "seniority": z.enum(["intern", "junior", "mid", "senior", "lead", "principal", "executive"]).describe("Seniority level of the job. Operator instances inherit this; a promotion is re-binding the operator to a higher-seniority role."), "mission": z.string().min(1).max(2e3).describe("One-paragraph mission, markdown. The reason the role exists."), "responsibilities": z.array(z.string().min(1).max(280)).min(1).describe("Ordered imperative clauses. At least one. Lineage accumulates under 'extends' (append-and-dedupe)."), "capabilities": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Competences this role is expected to have. Append-and-dedupe across 'extends'.").default([]), "tools": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("AIP-14 tool refs the role declares as intended. Append-and-dedupe across 'extends'. Governance (AIP-7) gates effect.").default([]), "skills": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("AIP-3 skill refs the role expects to load. Append-and-dedupe across 'extends'.").default([]), "kpis": z.array(z.string().min(1).max(120)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Scorer slugs (forward AIP) \u2014 KPIs evaluated against operators in this role. Append-and-dedupe across 'extends'.").default([]), "strengths": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Job-side strengths in prose. Append-and-dedupe across 'extends'.").default([]), "antiPatterns": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("What the role explicitly does NOT do. Append-and-dedupe across 'extends'.").default([]), "onPromotion": z.string().min(1).describe("AIP-39 action ref fired on promotion INTO this role.").optional(), "onDemotion": z.string().min(1).describe("AIP-39 action ref fired on demotion OUT of this role.").optional(), "onAssign": z.string().min(1).describe("AIP-39 action ref fired on first assignment of this role.").optional(), "appliesTo": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Cross-AIP bindings \u2014 restrict the role to specific operators. Local-only under 'extends' (NOT inherited).").default([]), "defaultPersona": z.string().min(1).describe("AIP-25 PERSONA ref recommended for operators adopting this role. Advisory; the operator's own 'persona' field overrides.").optional(), "defaultIdentity": z.string().min(1).describe("AIP-23 IDENTITY ref recommended for operators adopting this role. Advisory; the operator's own 'identity' field overrides.").optional(), "defaultPolicy": z.string().min(1).describe("AIP-38 POLICY ref recommended for operators adopting this role. ADVISORY ONLY \u2014 role declares intent, policy decides effect. The runtime MUST NOT apply defaultPolicy to an operator without the operator's own 'policy:' field or a governance signature attesting the binding. See AIP-47 \xA7Role vs Policy vs Governance.").optional(), "knowledge": z.object({ "packs": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("AIP-10 knowledge-pack refs this role mounts as its generic corpus floor. The host resolves each ref to a pack and mounts it read-only UNDER the operator's own editable corpus (the host overlays them). Append-and-dedupe across 'extends'. Absent = the host's convention (e.g. a pack named after the role slug). Operator-level packs layer ABOVE these.").default([]) }).strict().describe("Generic knowledge this role consults \u2014 AIP-10 corpus packs mounted read-only as a floor beneath the operator's own corpus. Distinct from 'skills' (what the role knows how to DO): knowledge is what it CONSULTS. The host unions these with any operator-level packs.").optional(), "tags": z.array(z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$"))).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Catalog tags. Lowercase kebab-case. Append-and-dedupe across 'extends'.").default([]), "metadata": z.record(z.string(), z.any()).describe("Vendor extensions, namespaced under '<vendor>'. Hosts MUST tolerate unknown vendor namespaces; they MUST NOT honour metadata that overrides AIP-defined fields.").default({}) }).strict().describe("Validates the YAML frontmatter portion of an AIP-47 ROLE.md manifest. Single-doc, no oneOf \u2014 every role is the same shape. The body is markdown and not validated by this schema.");
+var defineRole = createDoctype({
+  aip: 47,
+  name: "role",
+  readIdentity: (def) => def.name,
+  validate(def) {
+    const result = roleFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `defineRole (AIP-47): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+export { defineRole, roleFrontmatterSchema };
+//# sourceMappingURL=chunk-U2HQWFCN.mjs.map
+//# sourceMappingURL=chunk-U2HQWFCN.mjs.map

package/dist/chunk-U2HQWFCN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-role.ts"],"names":[],"mappings":"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","file":"chunk-U2HQWFCN.mjs","sourcesContent":["/**\n * AIP-47 ROLE.md frontmatter zod schema.\n *\n * Generated from `resources/aip-47/draft/ROLE.schema.json` via\n * json-schema-to-zod. Imported by both `define-role.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-role.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const roleFrontmatterSchema = z.object({ \"schema\": z.literal(\"role/v1\").describe(\"Schema dispatch tag. MUST be 'role/v1' for this version of AIP-47.\"), \"name\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\")).min(2).max(64).describe(\"Machine identifier. Lowercase, digits, dashes. Must start with a letter, end with a letter or digit. Unique within the registry that hosts the role.\"), \"title\": z.string().min(1).max(120).describe(\"Human-readable display title, sentence case.\"), \"description\": z.string().min(1).max(2000).describe(\"One-paragraph job description. The role's purpose, audience, and shape.\"), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][a-zA-Z0-9.-]+)?$\")).describe(\"Semver. Bump on breaking change to responsibilities, KPIs, tools, or seniority.\"), \"extends\": z.string().min(1).describe(\"Reference to a parent ROLE. Triggers composition. Accepts any ref form in AIP-47 §Reference syntax: bare slug, scoped slug (builtin/<slug>, file/<path>, db/<id>), ws:// URI, or fully-qualified URL. Path-form refs SHOULD end in 'ROLE.md'.\").optional(), \"department\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\")).min(1).max(80).describe(\"Department slug. Lowercase kebab-case. Recommended values listed in AIP-47 §Departments; free-form to accept domain-specific values.\").optional(), \"reports_to\": z.string().min(1).describe(\"Role-to-role reporting link. Conventionally a 'ws://roles/<slug>' ref. Schema does not validate scheme; the loader resolves.\").optional(), \"seniority\": z.enum([\"intern\",\"junior\",\"mid\",\"senior\",\"lead\",\"principal\",\"executive\"]).describe(\"Seniority level of the job. Operator instances inherit this; a promotion is re-binding the operator to a higher-seniority role.\"), \"mission\": z.string().min(1).max(2000).describe(\"One-paragraph mission, markdown. The reason the role exists.\"), \"responsibilities\": z.array(z.string().min(1).max(280)).min(1).describe(\"Ordered imperative clauses. At least one. Lineage accumulates under 'extends' (append-and-dedupe).\"), \"capabilities\": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Competences this role is expected to have. Append-and-dedupe across 'extends'.\").default([] as never), \"tools\": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"AIP-14 tool refs the role declares as intended. Append-and-dedupe across 'extends'. Governance (AIP-7) gates effect.\").default([] as never), \"skills\": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"AIP-3 skill refs the role expects to load. Append-and-dedupe across 'extends'.\").default([] as never), \"kpis\": z.array(z.string().min(1).max(120)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Scorer slugs (forward AIP) — KPIs evaluated against operators in this role. Append-and-dedupe across 'extends'.\").default([] as never), \"strengths\": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Job-side strengths in prose. Append-and-dedupe across 'extends'.\").default([] as never), \"antiPatterns\": z.array(z.string().min(1).max(200)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"What the role explicitly does NOT do. Append-and-dedupe across 'extends'.\").default([] as never), \"onPromotion\": z.string().min(1).describe(\"AIP-39 action ref fired on promotion INTO this role.\").optional(), \"onDemotion\": z.string().min(1).describe(\"AIP-39 action ref fired on demotion OUT of this role.\").optional(), \"onAssign\": z.string().min(1).describe(\"AIP-39 action ref fired on first assignment of this role.\").optional(), \"appliesTo\": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Cross-AIP bindings — restrict the role to specific operators. Local-only under 'extends' (NOT inherited).\").default([] as never), \"defaultPersona\": z.string().min(1).describe(\"AIP-25 PERSONA ref recommended for operators adopting this role. Advisory; the operator's own 'persona' field overrides.\").optional(), \"defaultIdentity\": z.string().min(1).describe(\"AIP-23 IDENTITY ref recommended for operators adopting this role. Advisory; the operator's own 'identity' field overrides.\").optional(), \"defaultPolicy\": z.string().min(1).describe(\"AIP-38 POLICY ref recommended for operators adopting this role. ADVISORY ONLY — role declares intent, policy decides effect. The runtime MUST NOT apply defaultPolicy to an operator without the operator's own 'policy:' field or a governance signature attesting the binding. See AIP-47 §Role vs Policy vs Governance.\").optional(), \"knowledge\": z.object({ \"packs\": z.array(z.string().min(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"AIP-10 knowledge-pack refs this role mounts as its generic corpus floor. The host resolves each ref to a pack and mounts it read-only UNDER the operator's own editable corpus (the host overlays them). Append-and-dedupe across 'extends'. Absent = the host's convention (e.g. a pack named after the role slug). Operator-level packs layer ABOVE these.\").default([] as never) }).strict().describe(\"Generic knowledge this role consults — AIP-10 corpus packs mounted read-only as a floor beneath the operator's own corpus. Distinct from 'skills' (what the role knows how to DO): knowledge is what it CONSULTS. The host unions these with any operator-level packs.\").optional(), \"tags\": z.array(z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\"))).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Catalog tags. Lowercase kebab-case. Append-and-dedupe across 'extends'.\").default([] as never), \"metadata\": z.record(z.string(), z.any()).describe(\"Vendor extensions, namespaced under '<vendor>'. Hosts MUST tolerate unknown vendor namespaces; they MUST NOT honour metadata that overrides AIP-defined fields.\").default({} as never) }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-47 ROLE.md manifest. Single-doc, no oneOf — every role is the same shape. The body is markdown and not validated by this schema.\")\n\nexport type RoleFrontmatter = z.infer<typeof roleFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { roleFrontmatterSchema } from \"./schema.js\"\nimport type { RoleDefinition, RoleHandle } from \"./types.js\"\n\n/**\n * AIP-47 reference implementation of `defineRole`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineRole (AIP-47): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parseRoleManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n * Cross-field rules go in `validate(def)` after the zod check.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.name\n *   readDescription: def.description.\n */\nexport const defineRole = createDoctype<RoleDefinition, RoleHandle>({\n  aip: 47,\n  name: \"role\",\n  readIdentity: (def) => def.name,\n  validate(def) {\n    const result = roleFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineRole (AIP-47): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-47-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Default build: spread the validated definition into a fresh object.\n    // Hand-tune for nested freezing (Object.freeze on arrays/objects) and\n    // for fields that need defaults applied — see @agentproto/operator\n    // for a reference shape.\n    return { ...def } as RoleHandle\n  },\n})\n"]}

package/dist/index.d.ts

@@ -0,0 +1,385 @@
+import { R as RoleDefinition, a as RoleHandle } from './types-CohqAgUN.js';
+import { Registry } from '@agentproto/registry';
+
+/**
+ * AIP-47 reference implementation of `defineRole`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "defineRole (AIP-47): …"
+ * error prefix) run uniformly with every other AIP defineX.
+ *
+ * Field-level validation runs the schema-derived zod from
+ * `./schema.ts` against the input. Same source of truth as the .md
+ * path uses (`parseRoleManifest`), so a malformed TS-authored
+ * definition fails with the same diagnostic as a malformed manifest.
+ * Cross-field rules go in `validate(def)` after the zod check.
+ *
+ * Identity / description extractors detected from the JSON Schema:
+ *   readIdentity: def.name
+ *   readDescription: def.description.
+ */
+declare const defineRole: (def: RoleDefinition) => Readonly<RoleDefinition>;
+
+/**
+ * AIP-47 strategic merge for role inheritance.
+ *
+ * Pure function: parent + child → merged. No I/O.
+ *
+ * Merge strategy per AIP-47 §Merge strategy table:
+ *   - scalars (name/title/description/version/department/reports_to/
+ *     seniority/mission/onPromotion/onDemotion/onAssign/defaultPersona/
+ *     defaultIdentity/defaultPolicy): override (child wins)
+ *   - list-strategy fields (responsibilities/capabilities/tools/skills/
+ *     kpis/strengths/antiPatterns/tags): append-and-dedupe, OR
+ *     `{ add, remove }` patch form
+ *   - extends + appliesTo: local-only (never inherited)
+ *   - metadata: deep-merge
+ *
+ * Body merge is handled by `mergeBodies` (separate concern — handles
+ * `metadata['aip-47'].bodyMerge` switch).
+ */
+
+/**
+ * A child role's input may carry a list patch on a list-strategy field
+ * instead of a plain list. The patch is applied against the inherited
+ * accumulator at merge time.
+ *
+ * See AIP-47 §Merge strategy →
+ * "Explicit remove of inherited entries".
+ */
+type ListPatch<T> = readonly T[] | {
+    add?: readonly T[];
+    remove?: readonly T[];
+};
+/**
+ * The set of list-strategy field names per AIP-47 §Merge strategy.
+ * Every entry here is an `append-and-dedupe` field that admits the
+ * `{ add, remove }` patch form.
+ */
+declare const LIST_FIELDS: readonly ["responsibilities", "capabilities", "tools", "skills", "kpis", "strengths", "antiPatterns", "tags"];
+type ListField = (typeof LIST_FIELDS)[number];
+/**
+ * The set of fields that are NEVER inherited from a parent role.
+ * Used by the resolver to strip them before merging into the
+ * accumulator.
+ */
+declare const LOCAL_ONLY_FIELDS: readonly ["extends", "appliesTo"];
+/**
+ * A child role's raw input. Same shape as `RoleDefinition` except
+ * that list-strategy fields admit the `{ add, remove }` patch form.
+ * The merger normalises patches into plain lists; the resolved output
+ * is always `RoleHandle` (plain lists only).
+ */
+type RoleChildInput = Omit<Partial<RoleDefinition>, ListField> & {
+    [K in ListField]?: K extends "responsibilities" ? ListPatch<string> | [string, ...string[]] : ListPatch<string>;
+};
+type MergeWarning = {
+    code: "role_merge_form_conflict";
+    message: string;
+    field: ListField;
+} | {
+    code: "role_merge_remove_missed";
+    message: string;
+    field: ListField;
+    missing: string;
+};
+interface MergeResult {
+    /** The merged role frontmatter, always plain lists. */
+    role: RoleHandle;
+    /** Diagnostics emitted during merge. */
+    warnings: MergeWarning[];
+}
+/**
+ * Strategic-merge a parent role (already resolved, plain handle) with
+ * a child role's raw input. Returns a fully-typed `RoleHandle` and any
+ * merge-time warnings.
+ *
+ * The merger does NOT validate against the canonical schema — that is
+ * the caller's responsibility (typically `resolveRole` validates the
+ * final merged role at the end of chain walking).
+ *
+ * Override fields (scalars + non-list maps + single bindings) follow
+ * `child wins if defined`. Local-only fields are NEVER inherited from
+ * the parent: the resolved role carries the local-only fields of the
+ * leaf (current) child, never of any ancestor.
+ */
+declare function mergeRoles(parent: RoleHandle, child: RoleChildInput): MergeResult;
+/**
+ * Body merge for ROLE.md body markdown. The parent's body comes from
+ * the resolved parent manifest; the child's body comes from the
+ * current frontmatter parse. The default is `append-with-separator`;
+ * `metadata['aip-47'].bodyMerge === 'replace'` switches to replace.
+ */
+declare function mergeBodies(parentBody: string | undefined, childBody: string | undefined, mode?: "append-with-separator" | "replace"): string;
+
+/**
+ * AIP-47 source loader interface.
+ *
+ * A `RoleSource` resolves a role ref (slug, ws:// ref, file path, http
+ * URL) to a raw manifest (frontmatter + body). The resolver assembles
+ * the `extends` chain by querying a list of sources in order, first
+ * match wins.
+ *
+ * The interface is intentionally minimal:
+ *   - `scheme` — the scheme this source claims (used by the chain to
+ *     dispatch by `<scheme>://...` refs)
+ *   - `load(ref)` — return the parsed manifest, or `null` if not found
+ *
+ * Sources MUST enforce their own visibility / authorisation. The
+ * resolver does NOT inspect `metadata.guilde.visibility` — it trusts
+ * the source to only return manifests the caller may see.
+ */
+
+/**
+ * The raw manifest a source returns. Frontmatter is the parsed
+ * (NOT yet schema-validated) object; body is the markdown body
+ * verbatim. The resolver validates and merges; the source loads.
+ */
+interface RoleManifestRaw {
+    /** The role ref this manifest resolves (canonical / source-scoped). */
+    readonly ref: string;
+    /** Parsed YAML frontmatter — shape is per AIP-47 (may include patches). */
+    readonly frontmatter: unknown;
+    /** Markdown body — verbatim. */
+    readonly body: string;
+    /**
+     * The scheme that loaded this manifest. Useful for the resolution
+     * chain debug surface ("`role:builtin → role:file → role:db`").
+     */
+    readonly scheme: string;
+}
+/**
+ * A role ref that has already been narrowed to a single source. The
+ * resolver MAY normalise bare slugs to a scoped form ("`builtin/seo-
+ * specialist`") when it walks the chain.
+ */
+type RoleRef = string;
+interface RoleSource {
+    /**
+     * The scheme this source serves. Conventional values:
+     *   - `builtin` — TS registry shipped by a runtime
+     *   - `file`    — file-system layout per AIP-47 §File location
+     *   - `db`      — a database table (typically the runtime's role
+     *                 table; see resources/aip-47/draft/ADAPTER.md)
+     *   - `http`    — remote registry (optional in v1)
+     *
+     * Custom schemes are welcome — the resolver dispatches on the
+     * `<scheme>://` prefix of a ref.
+     */
+    readonly scheme: string;
+    /**
+     * Resolve a ref to a raw manifest. Returns `null` if the source
+     * does not have this ref — the resolver will continue down the
+     * chain. Throws on transport / corruption errors.
+     */
+    load(ref: RoleRef): Promise<RoleManifestRaw | null>;
+    /**
+     * Enumerate ref ids this source can resolve. Optional — the
+     * resolver does not require enumeration to work, but UI surfaces
+     * (catalog browsing, "hire" flows) consume this.
+     */
+    list?(): Promise<readonly RoleRef[]>;
+}
+/**
+ * Helper: a `BuiltinRoleSource` ships a TS map of `slug → RoleHandle`
+ * (already-resolved, already-validated). Loaded directly from a
+ * runtime package like `@agentproto/role-catalog`.
+ */
+interface BuiltinRoleEntry {
+    readonly slug: string;
+    readonly handle: RoleHandle;
+    readonly body?: string;
+}
+
+/**
+ * AIP-47 role resolver — walks the `extends` chain, merges, validates.
+ *
+ * Pipeline:
+ *   1. dispatch the ref through the source chain — first match wins
+ *   2. if the loaded manifest has `extends`, recurse to resolve the
+ *      parent (cycle-detected, depth-capped, warnings on missing)
+ *   3. apply strategic merge (parent + child) per AIP-47 §Merge
+ *      strategy via `merge.ts`
+ *   4. validate the merged frontmatter against the canonical zod
+ *      schema (defensive — sources MAY ship raw / patch-form input)
+ *   5. return `{ role, body, chain, warnings }`
+ *
+ * Cycle detection: tracks visited refs during chain walk.
+ * Depth limit: max 8 (per spec recommendation).
+ * Missing parent: warning, fallback to the local manifest.
+ */
+
+type ResolveWarning = MergeWarning | {
+    code: "role_unresolvable";
+    message: string;
+    ref: string;
+} | {
+    code: "role_extends_cycle";
+    message: string;
+    cycle: readonly string[];
+} | {
+    code: "role_extends_depth_exceeded";
+    message: string;
+    depth: number;
+    ref: string;
+} | {
+    code: "role_extends_missing";
+    message: string;
+    parent: string;
+} | {
+    code: "role_validation_failed";
+    message: string;
+    ref: string;
+    issues: readonly string[];
+};
+interface ResolveOptions {
+    /** Source chain — consulted in order, first match wins. */
+    readonly sources: readonly RoleSource[];
+    /** Maximum `extends` chain depth. Default 8. */
+    readonly maxDepth?: number;
+}
+interface ResolvedRole {
+    /** Effective role after `extends`-chain merge. Always plain lists. */
+    readonly role: RoleHandle;
+    /** Merged body markdown — parent appended with `\n\n---\n\n` separator. */
+    readonly body: string;
+    /**
+     * Ordered list of refs walked, from leaf to root.
+     * `chain[0]` is the requested ref; the last entry is the root parent.
+     */
+    readonly chain: readonly string[];
+    /** Diagnostics emitted during resolution + merge. */
+    readonly warnings: readonly ResolveWarning[];
+}
+/**
+ * Resolve a role ref through the source chain and merge any
+ * `extends` lineage. Throws iff the leaf ref cannot be loaded AND no
+ * partial result is recoverable (i.e. the top-level lookup fails).
+ *
+ * Intermediate failures (cycle, depth, missing parent) MUST NOT
+ * throw — they emit warnings and the resolver falls back to the
+ * local manifest. This is the AIP-47 spec contract:
+ *
+ *   "Treat depth overflow and cycle detection as warnings, not
+ *    errors. A role whose chain is malformed MUST still load — the
+ *    runtime falls back to the local manifest only."
+ */
+declare function resolveRole(ref: RoleRef, opts: ResolveOptions): Promise<ResolvedRole>;
+
+/**
+ * AIP-47 built-in role source.
+ *
+ * Wraps an AIP-43 `@agentproto/registry` instance keyed by role slug.
+ * Intended primarily for runtime-shipped catalogues
+ * (`@agentproto/role-catalog`, vendor-specific registries) where the
+ * roles are authored in TS and validated at module load time. The
+ * registry is mutable post-construction — `register` / `unregister` /
+ * `replace` let downstream apps extend the catalogue without forking
+ * the OSS package.
+ *
+ * Refs are matched in three forms:
+ *   - bare slug:          `seo-specialist`
+ *   - scoped slug:        `builtin/seo-specialist`
+ *   - ws:// ref:          `ws://roles/seo-specialist`
+ *
+ * All three resolve to the same entry. The `scheme` is `builtin`.
+ */
+
+declare class BuiltinRoleSource implements RoleSource {
+    readonly scheme = "builtin";
+    /**
+     * Underlying AIP-43 registry. Exposed for advanced consumers that
+     * want to use `lookup(predicate)`, `entries()`, or other registry
+     * primitives. The common operations are mirrored on the source
+     * itself for ergonomics.
+     */
+    readonly registry: Registry<BuiltinRoleEntry>;
+    constructor(entries?: Iterable<BuiltinRoleEntry>);
+    load(ref: RoleRef): Promise<RoleManifestRaw | null>;
+    list(): Promise<readonly RoleRef[]>;
+    /**
+     * Register a new builtin entry. Throws `RegistryDuplicateError`
+     * if a handle with the same slug is already registered — use
+     * `replace` to swap atomically when a hot-reload picks up a
+     * redefined role.
+     */
+    register(entry: BuiltinRoleEntry): void;
+    /**
+     * Replace an existing entry. Throws `RegistryNotFoundError` if no
+     * entry exists at the resolved slug. Use `register` for new slugs.
+     */
+    replace(entry: BuiltinRoleEntry): void;
+    /**
+     * Remove a slug from the registry. Returns true if an entry was
+     * removed. Use sparingly — the registry is intended to be
+     * boot-time-stable.
+     */
+    unregister(slug: string): boolean;
+    /** Returns true if the slug (any ref form) is registered. */
+    has(slug: string): boolean;
+    /** Number of entries currently registered. */
+    count(): number;
+    /**
+     * Filter entries by an arbitrary predicate. Runs in registration
+     * order. Useful for capability lookups like "every role with
+     * `metadata.aip-47.audience === 'ai-worker'`".
+     */
+    lookup(predicate: (entry: BuiltinRoleEntry) => boolean): readonly BuiltinRoleEntry[];
+}
+/**
+ * Convenience: assemble a `BuiltinRoleSource` from a record map.
+ * Each entry's key becomes the slug.
+ */
+declare function builtinSourceFromRecord(record: Record<string, Omit<BuiltinRoleEntry, "slug">>): BuiltinRoleSource;
+
+/**
+ * @agentproto/role — AIP-47 ROLE.md `defineRole` reference impl.
+ *
+ * A single-doc markdown + frontmatter format for portable organizational roles — mission, responsibilities, capabilities, tools, KPIs, seniority, reporting line, lifecycle hooks. Sibling to AIP-25 PERSONA (face) and AIP-23 IDENTITY (substance); referenced by AIP-9 OPERATOR (`role:` field) and AIP-6 COMPANY (`roles/<slug>/ROLE.md` doctype). Roles describe what a job is — independent of who holds it (persona/identity) and which instance is hired (operator).
+ *
+ * Spec: https://agentproto.sh/docs/aip-47
+ *
+ * Authoring paths:
+ *   - TS:  `defineRole({...})` → `RoleHandle`
+ *   - MD:  `parseRoleManifest(src) → roleFromManifest({...})` → `RoleHandle`
+ *
+ * Resolution:
+ *   - `resolveRole(ref, { sources })` walks the `extends` chain, applies
+ *     strategic merge per the spec, and returns the effective `RoleHandle`
+ *     plus the merged body, the resolution chain, and any warnings.
+ *
+ * Composition (advisory, never grants access):
+ *   - Operators consume the resolved role via AIP-9 OPERATOR `role:`
+ *     field. Effective permissions come from AIP-38 POLICY, NOT from
+ *     the role — see AIP-47 §Role vs Policy vs Governance.
+ */
+declare const SPEC_NAME: "agentrole/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+/**
+ * Seniority levels per AIP-47 §Optional fields. Const tuple exported
+ * so consumers can derive zod / openapi enum schemas from the single
+ * source of truth — keep this in sync with `ROLE.schema.json`.
+ */
+declare const ROLE_SENIORITIES: readonly ["intern", "junior", "mid", "senior", "lead", "principal", "executive"];
+type RoleSeniority = (typeof ROLE_SENIORITIES)[number];
+/**
+ * Recommended departments per AIP-47 §Departments (informative).
+ * `department` on a ROLE.md is a free string — these values are
+ * suggested for cross-runtime alignment. Runtimes that group / chart
+ * roles by department SHOULD render this list as the default
+ * taxonomy and treat any out-of-list value as a domain-specific
+ * extension (legal, R&D, clinical, …).
+ *
+ * Order is significant: the array order is the recommended display
+ * order for org charts and "hire" UIs.
+ */
+declare const RECOMMENDED_DEPARTMENTS: readonly ["executive", "operations", "engineering", "product", "marketing", "sales", "customer", "finance", "people"];
+type RecommendedDepartment = (typeof RECOMMENDED_DEPARTMENTS)[number];
+/**
+ * Human-readable label for a department slug. Falls back to a
+ * Title-Case-ified version of the slug for departments outside the
+ * recommended list (custom org taxonomies).
+ */
+declare function departmentLabel(slug: string): string;
+
+export { type BuiltinRoleEntry, BuiltinRoleSource, LIST_FIELDS, LOCAL_ONLY_FIELDS, type ListField, type ListPatch, type MergeResult, type MergeWarning, RECOMMENDED_DEPARTMENTS, ROLE_SENIORITIES, type RecommendedDepartment, type ResolveOptions, type ResolveWarning, type ResolvedRole, type RoleChildInput, RoleDefinition, RoleHandle, type RoleManifestRaw, type RoleRef, type RoleSeniority, type RoleSource, SPEC_NAME, SPEC_VERSION, builtinSourceFromRecord, defineRole, departmentLabel, mergeBodies, mergeRoles, resolveRole };

package/dist/index.mjs

@@ -0,0 +1,363 @@
+import { roleFrontmatterSchema } from './chunk-U2HQWFCN.mjs';
+export { defineRole } from './chunk-U2HQWFCN.mjs';
+import { createRegistry } from '@agentproto/registry';
+
+/**
+ * @agentproto/role v0.1.0-alpha
+ * AIP-47 ROLE.md `defineRole` reference implementation.
+ */
+
+// src/merge.ts
+var LIST_FIELDS = [
+  "responsibilities",
+  "capabilities",
+  "tools",
+  "skills",
+  "kpis",
+  "strengths",
+  "antiPatterns",
+  "tags"
+];
+var LOCAL_ONLY_FIELDS = ["extends", "appliesTo"];
+function applyListPatch(field, inherited, child) {
+  if (child === void 0) {
+    return { value: [...inherited], warnings: [] };
+  }
+  if (Array.isArray(child)) {
+    return { value: [...child], warnings: [] };
+  }
+  const warnings = [];
+  const patch = child;
+  const removeSet = new Set(patch.remove ?? []);
+  const matched = /* @__PURE__ */ new Set();
+  const filtered = inherited.filter((item) => {
+    const should = !removeSet.has(item);
+    if (!should) matched.add(item);
+    return should;
+  });
+  for (const r of removeSet) {
+    if (!matched.has(r)) {
+      warnings.push({
+        code: "role_merge_remove_missed",
+        message: `${field}: remove entry not found in inherited list`,
+        field,
+        missing: String(r)
+      });
+    }
+  }
+  const out = [...filtered];
+  for (const a of patch.add ?? []) {
+    if (!out.includes(a)) out.push(a);
+  }
+  return { value: out, warnings };
+}
+function deepMerge(parent, child) {
+  if (child === void 0) return parent;
+  if (typeof parent !== "object" || parent === null || Array.isArray(parent)) {
+    return child;
+  }
+  if (typeof child !== "object" || child === null || Array.isArray(child)) {
+    return child;
+  }
+  const out = { ...parent };
+  for (const [k, v] of Object.entries(child)) {
+    out[k] = deepMerge(parent[k], v);
+  }
+  return out;
+}
+function mergeRoles(parent, child) {
+  const warnings = [];
+  const pick = (key) => {
+    const c = child[key];
+    return c !== void 0 ? c : parent[key];
+  };
+  const lists = {};
+  for (const field of LIST_FIELDS) {
+    const inherited = field === "responsibilities" ? parent.responsibilities : parent[field] ?? [];
+    const childField = child[field];
+    const result = applyListPatch(field, inherited, childField);
+    warnings.push(...result.warnings);
+    lists[field] = result.value;
+  }
+  if (lists.responsibilities.length === 0) {
+    lists.responsibilities = [...parent.responsibilities];
+  }
+  const mergedPacks = [
+    ...parent.knowledge?.packs ?? [],
+    ...child.knowledge?.packs ?? []
+  ].filter((p, i, a) => a.indexOf(p) === i);
+  const knowledge = parent.knowledge || child.knowledge ? { packs: mergedPacks } : void 0;
+  const merged = {
+    // Doctype identity — child wins if set.
+    schema: "role/v1",
+    name: pick("name"),
+    title: pick("title"),
+    description: pick("description"),
+    version: pick("version"),
+    seniority: pick("seniority"),
+    mission: pick("mission"),
+    // Org placement — overrides.
+    department: pick("department"),
+    reports_to: pick("reports_to"),
+    // Lifecycle hooks — overrides.
+    onPromotion: pick("onPromotion"),
+    onDemotion: pick("onDemotion"),
+    onAssign: pick("onAssign"),
+    // Single bindings — overrides.
+    defaultPersona: pick("defaultPersona"),
+    defaultIdentity: pick("defaultIdentity"),
+    defaultPolicy: pick("defaultPolicy"),
+    // Nested knowledge binding — append-and-dedupe union (computed above).
+    ...knowledge ? { knowledge } : {},
+    // Local-only fields — child's value carries; parent's is dropped.
+    extends: child.extends,
+    appliesTo: child.appliesTo,
+    // List-strategy.
+    responsibilities: lists.responsibilities,
+    capabilities: lists.capabilities,
+    tools: lists.tools,
+    skills: lists.skills,
+    kpis: lists.kpis,
+    strengths: lists.strengths,
+    antiPatterns: lists.antiPatterns,
+    tags: lists.tags,
+    // Deep-merged maps.
+    metadata: deepMerge(parent.metadata ?? {}, child.metadata)
+  };
+  if (child.extends === void 0) delete merged.extends;
+  if (child.appliesTo === void 0)
+    delete merged.appliesTo;
+  return { role: merged, warnings };
+}
+function mergeBodies(parentBody, childBody, mode = "append-with-separator") {
+  if (!parentBody) return childBody ?? "";
+  if (!childBody) return parentBody;
+  if (mode === "replace") return childBody;
+  return `${parentBody.trimEnd()}
+
+---
+
+${childBody.trimStart()}`;
+}
+
+// src/resolve.ts
+var DEFAULT_MAX_DEPTH = 8;
+async function resolveRole(ref, opts) {
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const visited = /* @__PURE__ */ new Set();
+  const warnings = [];
+  const chain = [];
+  const load = async (current) => {
+    for (const src of opts.sources) {
+      const m = await src.load(current);
+      if (m !== null) return m;
+    }
+    return null;
+  };
+  const walk = async (current, depth, isParentRef) => {
+    if (depth > maxDepth) {
+      warnings.push({
+        code: "role_extends_depth_exceeded",
+        message: `extends chain depth exceeded ${maxDepth} at '${current}'`,
+        depth,
+        ref: current
+      });
+      return null;
+    }
+    if (visited.has(current)) {
+      warnings.push({
+        code: "role_extends_cycle",
+        message: `extends cycle detected at '${current}'`,
+        cycle: [...visited, current]
+      });
+      return null;
+    }
+    visited.add(current);
+    const manifest = await load(current);
+    if (!manifest) {
+      if (isParentRef) {
+        warnings.push({
+          code: "role_extends_missing",
+          message: `parent ref '${current}' did not resolve`,
+          parent: current
+        });
+      }
+      return null;
+    }
+    chain.push(manifest.ref);
+    const fm = manifest.frontmatter;
+    const extendsRef = fm.extends;
+    if (!extendsRef) {
+      return { role: fm, body: manifest.body };
+    }
+    const parent = await walk(extendsRef, depth + 1, true);
+    if (!parent) {
+      return { role: fm, body: manifest.body };
+    }
+    const merged = mergeRoles(parent.role, fm);
+    warnings.push(...merged.warnings);
+    const bodyMode = fm.metadata?.["aip-47"]?.bodyMerge ?? "append-with-separator";
+    const body = mergeBodies(parent.body, manifest.body, bodyMode);
+    return { role: merged.role, body };
+  };
+  const result = await walk(ref, 0, false);
+  if (!result) {
+    const w = {
+      code: "role_unresolvable",
+      message: `role ref '${ref}' did not resolve in any source`,
+      ref
+    };
+    warnings.push(w);
+    throw Object.assign(new Error(w.message), { warnings, chain });
+  }
+  const validated = roleFrontmatterSchema.safeParse(result.role);
+  if (!validated.success) {
+    const issues = validated.error.issues.map(
+      (i) => `${i.path.join(".")}: ${i.message}`
+    );
+    warnings.push({
+      code: "role_validation_failed",
+      message: `merged role failed schema validation`,
+      ref,
+      issues
+    });
+  }
+  return {
+    role: validated.success ? validated.data : result.role,
+    body: result.body,
+    chain,
+    warnings
+  };
+}
+var WS_REF_PREFIX = "ws://roles/";
+var BUILTIN_PREFIX = "builtin/";
+var REGISTRY_FAMILY = "role-builtin";
+function normaliseSlug(ref) {
+  if (ref.startsWith(WS_REF_PREFIX)) return ref.slice(WS_REF_PREFIX.length);
+  if (ref.startsWith(BUILTIN_PREFIX)) return ref.slice(BUILTIN_PREFIX.length);
+  return ref;
+}
+var BuiltinRoleSource = class {
+  scheme = "builtin";
+  /**
+   * Underlying AIP-43 registry. Exposed for advanced consumers that
+   * want to use `lookup(predicate)`, `entries()`, or other registry
+   * primitives. The common operations are mirrored on the source
+   * itself for ergonomics.
+   */
+  registry;
+  constructor(entries = []) {
+    this.registry = createRegistry({
+      family: REGISTRY_FAMILY,
+      keyBy: (e) => e.slug
+    });
+    for (const e of entries) {
+      this.registry.register(e);
+    }
+  }
+  async load(ref) {
+    const slug = normaliseSlug(ref);
+    const entry = this.registry.get(slug);
+    if (!entry) return null;
+    return {
+      ref: `builtin/${slug}`,
+      frontmatter: entry.handle,
+      body: entry.body ?? "",
+      scheme: "builtin"
+    };
+  }
+  async list() {
+    return this.registry.list().map((e) => `builtin/${e.slug}`);
+  }
+  /* ─── mutation surface (AIP-43 primitive operations) ─────────── */
+  /**
+   * Register a new builtin entry. Throws `RegistryDuplicateError`
+   * if a handle with the same slug is already registered — use
+   * `replace` to swap atomically when a hot-reload picks up a
+   * redefined role.
+   */
+  register(entry) {
+    this.registry.register(entry);
+  }
+  /**
+   * Replace an existing entry. Throws `RegistryNotFoundError` if no
+   * entry exists at the resolved slug. Use `register` for new slugs.
+   */
+  replace(entry) {
+    this.registry.replace(entry);
+  }
+  /**
+   * Remove a slug from the registry. Returns true if an entry was
+   * removed. Use sparingly — the registry is intended to be
+   * boot-time-stable.
+   */
+  unregister(slug) {
+    return this.registry.unregister(normaliseSlug(slug));
+  }
+  /** Returns true if the slug (any ref form) is registered. */
+  has(slug) {
+    return this.registry.has(normaliseSlug(slug));
+  }
+  /** Number of entries currently registered. */
+  count() {
+    return this.registry.count();
+  }
+  /**
+   * Filter entries by an arbitrary predicate. Runs in registration
+   * order. Useful for capability lookups like "every role with
+   * `metadata.aip-47.audience === 'ai-worker'`".
+   */
+  lookup(predicate) {
+    return this.registry.lookup(predicate);
+  }
+};
+function builtinSourceFromRecord(record) {
+  return new BuiltinRoleSource(
+    Object.entries(record).map(([slug, rest]) => ({ slug, ...rest }))
+  );
+}
+
+// src/index.ts
+var SPEC_NAME = "agentrole/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+var ROLE_SENIORITIES = [
+  "intern",
+  "junior",
+  "mid",
+  "senior",
+  "lead",
+  "principal",
+  "executive"
+];
+var RECOMMENDED_DEPARTMENTS = [
+  "executive",
+  "operations",
+  "engineering",
+  "product",
+  "marketing",
+  "sales",
+  "customer",
+  "finance",
+  "people"
+];
+function departmentLabel(slug) {
+  const labels = {
+    executive: "Executive",
+    operations: "Operations",
+    engineering: "Engineering",
+    product: "Product",
+    marketing: "Marketing",
+    sales: "Sales",
+    customer: "Customer",
+    finance: "Finance",
+    people: "People"
+  };
+  if (labels[slug] !== void 0) {
+    return labels[slug];
+  }
+  return slug.split("-").map((s) => s.length === 0 ? s : s[0].toUpperCase() + s.slice(1)).join(" ");
+}
+
+export { BuiltinRoleSource, LIST_FIELDS, LOCAL_ONLY_FIELDS, RECOMMENDED_DEPARTMENTS, ROLE_SENIORITIES, SPEC_NAME, SPEC_VERSION, builtinSourceFromRecord, departmentLabel, mergeBodies, mergeRoles, resolveRole };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/merge.ts","../src/resolve.ts","../src/sources/builtin.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * AIP-47 strategic merge for role inheritance.\n *\n * Pure function: parent + child → merged. No I/O.\n *\n * Merge strategy per AIP-47 §Merge strategy table:\n *   - scalars (name/title/description/version/department/reports_to/\n *     seniority/mission/onPromotion/onDemotion/onAssign/defaultPersona/\n *     defaultIdentity/defaultPolicy): override (child wins)\n *   - list-strategy fields (responsibilities/capabilities/tools/skills/\n *     kpis/strengths/antiPatterns/tags): append-and-dedupe, OR\n *     `{ add, remove }` patch form\n *   - extends + appliesTo: local-only (never inherited)\n *   - metadata: deep-merge\n *\n * Body merge is handled by `mergeBodies` (separate concern — handles\n * `metadata['aip-47'].bodyMerge` switch).\n */\n\nimport type { RoleDefinition, RoleHandle } from \"./types.js\"\n\n/**\n * A child role's input may carry a list patch on a list-strategy field\n * instead of a plain list. The patch is applied against the inherited\n * accumulator at merge time.\n *\n * See AIP-47 §Merge strategy →\n * \"Explicit remove of inherited entries\".\n */\nexport type ListPatch<T> = readonly T[] | { add?: readonly T[]; remove?: readonly T[] }\n\n/**\n * The set of list-strategy field names per AIP-47 §Merge strategy.\n * Every entry here is an `append-and-dedupe` field that admits the\n * `{ add, remove }` patch form.\n */\nexport const LIST_FIELDS = [\n  \"responsibilities\",\n  \"capabilities\",\n  \"tools\",\n  \"skills\",\n  \"kpis\",\n  \"strengths\",\n  \"antiPatterns\",\n  \"tags\",\n] as const\n\nexport type ListField = (typeof LIST_FIELDS)[number]\n\n/**\n * The set of fields that are NEVER inherited from a parent role.\n * Used by the resolver to strip them before merging into the\n * accumulator.\n */\nexport const LOCAL_ONLY_FIELDS = [\"extends\", \"appliesTo\"] as const\n\n/**\n * A child role's raw input. Same shape as `RoleDefinition` except\n * that list-strategy fields admit the `{ add, remove }` patch form.\n * The merger normalises patches into plain lists; the resolved output\n * is always `RoleHandle` (plain lists only).\n */\nexport type RoleChildInput = Omit<Partial<RoleDefinition>, ListField> & {\n  [K in ListField]?: K extends \"responsibilities\"\n    ? ListPatch<string> | [string, ...string[]]\n    : ListPatch<string>\n}\n\nexport type MergeWarning =\n  | {\n      code: \"role_merge_form_conflict\"\n      message: string\n      field: ListField\n    }\n  | {\n      code: \"role_merge_remove_missed\"\n      message: string\n      field: ListField\n      missing: string\n    }\n\nexport interface MergeResult {\n  /** The merged role frontmatter, always plain lists. */\n  role: RoleHandle\n  /** Diagnostics emitted during merge. */\n  warnings: MergeWarning[]\n}\n\n/**\n * Apply a list patch onto an inherited accumulator.\n *\n * - If `child` is a plain array → REPLACE the inherited list entirely.\n * - If `child` is `{ add, remove }` → APPEND-AND-DEDUPE additions and\n *   exact-string-REMOVE inherited entries.\n * - If `child` is `undefined` → return the inherited accumulator as-is.\n *\n * The \"replace\" semantics for the plain-array form matches the\n * AIP-47 spec exactly: a child author writing the field in long form\n * (plain list) overrides the lineage; the `{ add, remove }` form is\n * the only way to patch.\n *\n * Returns the resolved list AND any warnings (e.g. `remove` entries\n * that did not match anything in the accumulator).\n */\nfunction applyListPatch<T>(\n  field: ListField,\n  inherited: readonly T[],\n  child: ListPatch<T> | undefined,\n): { value: T[]; warnings: MergeWarning[] } {\n  if (child === undefined) {\n    return { value: [...inherited], warnings: [] }\n  }\n\n  // Plain array → replace.\n  if (Array.isArray(child)) {\n    return { value: [...child], warnings: [] }\n  }\n\n  // Patch form.\n  const warnings: MergeWarning[] = []\n  const patch = child as { add?: readonly T[]; remove?: readonly T[] }\n  const removeSet = new Set(patch.remove ?? [])\n\n  // Track which `remove` entries actually matched something inherited.\n  const matched = new Set<T>()\n  const filtered = inherited.filter((item) => {\n    const should = !removeSet.has(item)\n    if (!should) matched.add(item)\n    return should\n  })\n\n  for (const r of removeSet) {\n    if (!matched.has(r)) {\n      warnings.push({\n        code: \"role_merge_remove_missed\",\n        message: `${field}: remove entry not found in inherited list`,\n        field,\n        missing: String(r),\n      })\n    }\n  }\n\n  // Append additions (dedupe against the already-filtered accumulator).\n  const out = [...filtered]\n  for (const a of patch.add ?? []) {\n    if (!out.includes(a)) out.push(a)\n  }\n\n  return { value: out, warnings }\n}\n\n/**\n * Deep-merge two plain objects (used for `metadata`). Arrays at any\n * depth are replaced by the child's array (NOT concatenated) — same\n * semantics as Helm strategic merge for non-list-strategy maps.\n */\nfunction deepMerge(parent: unknown, child: unknown): unknown {\n  if (child === undefined) return parent\n  if (typeof parent !== \"object\" || parent === null || Array.isArray(parent)) {\n    return child\n  }\n  if (typeof child !== \"object\" || child === null || Array.isArray(child)) {\n    return child\n  }\n  const out: Record<string, unknown> = { ...(parent as Record<string, unknown>) }\n  for (const [k, v] of Object.entries(child as Record<string, unknown>)) {\n    out[k] = deepMerge((parent as Record<string, unknown>)[k], v)\n  }\n  return out\n}\n\n/**\n * Strategic-merge a parent role (already resolved, plain handle) with\n * a child role's raw input. Returns a fully-typed `RoleHandle` and any\n * merge-time warnings.\n *\n * The merger does NOT validate against the canonical schema — that is\n * the caller's responsibility (typically `resolveRole` validates the\n * final merged role at the end of chain walking).\n *\n * Override fields (scalars + non-list maps + single bindings) follow\n * `child wins if defined`. Local-only fields are NEVER inherited from\n * the parent: the resolved role carries the local-only fields of the\n * leaf (current) child, never of any ancestor.\n */\nexport function mergeRoles(parent: RoleHandle, child: RoleChildInput): MergeResult {\n  const warnings: MergeWarning[] = []\n\n  // Helper: apply a child override (scalar / single ref) using\n  // `child wins if defined` semantics.\n  const pick = <K extends keyof RoleDefinition>(key: K): RoleDefinition[K] => {\n    const c = (child as Partial<RoleDefinition>)[key]\n    return c !== undefined ? c : parent[key]\n  }\n\n  // List-strategy fields — patch or replace per spec.\n  const lists: { [K in ListField]: string[] } = {} as never\n  for (const field of LIST_FIELDS) {\n    const inherited =\n      field === \"responsibilities\"\n        ? (parent.responsibilities as readonly string[])\n        : (parent[field] as readonly string[] | undefined) ?? []\n    const childField = (child as RoleChildInput)[field] as\n      | ListPatch<string>\n      | undefined\n    const result = applyListPatch(field, inherited, childField)\n    warnings.push(...result.warnings)\n    lists[field] = result.value\n  }\n\n  // `responsibilities` is `[string, ...string[]]` in the canonical\n  // schema. The merger preserves the constraint by typing the output.\n  if (lists.responsibilities.length === 0) {\n    // Should never happen — parent.responsibilities is required ≥ 1,\n    // and append-and-dedupe never empties it. A plain-array override\n    // with an empty list would; we defensively keep the parent's.\n    lists.responsibilities = [...parent.responsibilities]\n  }\n\n  // knowledge.packs — append-and-dedupe across lineage (nested, so not a\n  // LIST_FIELD; child packs append onto the inherited floor). Only emit a\n  // `knowledge` block when some layer declared one, so packless roles stay\n  // clean (and the host's slug convention still applies).\n  const mergedPacks = [\n    ...(parent.knowledge?.packs ?? []),\n    ...(child.knowledge?.packs ?? []),\n  ].filter((p, i, a) => a.indexOf(p) === i)\n  const knowledge =\n    parent.knowledge || child.knowledge ? { packs: mergedPacks } : undefined\n\n  const merged: RoleDefinition = {\n    // Doctype identity — child wins if set.\n    schema: \"role/v1\",\n    name: pick(\"name\") as string,\n    title: pick(\"title\") as string,\n    description: pick(\"description\") as string,\n    version: pick(\"version\") as string,\n    seniority: pick(\"seniority\") as RoleDefinition[\"seniority\"],\n    mission: pick(\"mission\") as string,\n\n    // Org placement — overrides.\n    department: pick(\"department\") as string | undefined,\n    reports_to: pick(\"reports_to\") as string | undefined,\n\n    // Lifecycle hooks — overrides.\n    onPromotion: pick(\"onPromotion\") as string | undefined,\n    onDemotion: pick(\"onDemotion\") as string | undefined,\n    onAssign: pick(\"onAssign\") as string | undefined,\n\n    // Single bindings — overrides.\n    defaultPersona: pick(\"defaultPersona\") as string | undefined,\n    defaultIdentity: pick(\"defaultIdentity\") as string | undefined,\n    defaultPolicy: pick(\"defaultPolicy\") as string | undefined,\n\n    // Nested knowledge binding — append-and-dedupe union (computed above).\n    ...(knowledge ? { knowledge } : {}),\n\n    // Local-only fields — child's value carries; parent's is dropped.\n    extends: child.extends,\n    appliesTo: child.appliesTo as string[] | undefined,\n\n    // List-strategy.\n    responsibilities: lists.responsibilities as [string, ...string[]],\n    capabilities: lists.capabilities,\n    tools: lists.tools,\n    skills: lists.skills,\n    kpis: lists.kpis,\n    strengths: lists.strengths,\n    antiPatterns: lists.antiPatterns,\n    tags: lists.tags,\n\n    // Deep-merged maps.\n    metadata: deepMerge(parent.metadata ?? {}, child.metadata) as Record<\n      string,\n      unknown\n    >,\n  }\n\n  // Strip the local-only fields if the child didn't set them — we\n  // never want them to leak from the parent into the merged role.\n  if (child.extends === undefined) delete (merged as Partial<RoleDefinition>).extends\n  if (child.appliesTo === undefined)\n    delete (merged as Partial<RoleDefinition>).appliesTo\n\n  return { role: merged as RoleHandle, warnings }\n}\n\n/**\n * Body merge for ROLE.md body markdown. The parent's body comes from\n * the resolved parent manifest; the child's body comes from the\n * current frontmatter parse. The default is `append-with-separator`;\n * `metadata['aip-47'].bodyMerge === 'replace'` switches to replace.\n */\nexport function mergeBodies(\n  parentBody: string | undefined,\n  childBody: string | undefined,\n  mode: \"append-with-separator\" | \"replace\" = \"append-with-separator\",\n): string {\n  if (!parentBody) return childBody ?? \"\"\n  if (!childBody) return parentBody\n  if (mode === \"replace\") return childBody\n  return `${parentBody.trimEnd()}\\n\\n---\\n\\n${childBody.trimStart()}`\n}\n","/**\n * AIP-47 role resolver — walks the `extends` chain, merges, validates.\n *\n * Pipeline:\n *   1. dispatch the ref through the source chain — first match wins\n *   2. if the loaded manifest has `extends`, recurse to resolve the\n *      parent (cycle-detected, depth-capped, warnings on missing)\n *   3. apply strategic merge (parent + child) per AIP-47 §Merge\n *      strategy via `merge.ts`\n *   4. validate the merged frontmatter against the canonical zod\n *      schema (defensive — sources MAY ship raw / patch-form input)\n *   5. return `{ role, body, chain, warnings }`\n *\n * Cycle detection: tracks visited refs during chain walk.\n * Depth limit: max 8 (per spec recommendation).\n * Missing parent: warning, fallback to the local manifest.\n */\n\nimport { roleFrontmatterSchema } from \"./schema.js\"\nimport { mergeBodies, mergeRoles, type MergeWarning } from \"./merge.js\"\nimport type { RoleDefinition, RoleHandle } from \"./types.js\"\nimport type { RoleManifestRaw, RoleRef, RoleSource } from \"./sources/types.js\"\n\nconst DEFAULT_MAX_DEPTH = 8\n\nexport type ResolveWarning =\n  | MergeWarning\n  | {\n      code: \"role_unresolvable\"\n      message: string\n      ref: string\n    }\n  | {\n      code: \"role_extends_cycle\"\n      message: string\n      cycle: readonly string[]\n    }\n  | {\n      code: \"role_extends_depth_exceeded\"\n      message: string\n      depth: number\n      ref: string\n    }\n  | {\n      code: \"role_extends_missing\"\n      message: string\n      parent: string\n    }\n  | {\n      code: \"role_validation_failed\"\n      message: string\n      ref: string\n      issues: readonly string[]\n    }\n\nexport interface ResolveOptions {\n  /** Source chain — consulted in order, first match wins. */\n  readonly sources: readonly RoleSource[]\n  /** Maximum `extends` chain depth. Default 8. */\n  readonly maxDepth?: number\n}\n\nexport interface ResolvedRole {\n  /** Effective role after `extends`-chain merge. Always plain lists. */\n  readonly role: RoleHandle\n  /** Merged body markdown — parent appended with `\\n\\n---\\n\\n` separator. */\n  readonly body: string\n  /**\n   * Ordered list of refs walked, from leaf to root.\n   * `chain[0]` is the requested ref; the last entry is the root parent.\n   */\n  readonly chain: readonly string[]\n  /** Diagnostics emitted during resolution + merge. */\n  readonly warnings: readonly ResolveWarning[]\n}\n\n/**\n * Resolve a role ref through the source chain and merge any\n * `extends` lineage. Throws iff the leaf ref cannot be loaded AND no\n * partial result is recoverable (i.e. the top-level lookup fails).\n *\n * Intermediate failures (cycle, depth, missing parent) MUST NOT\n * throw — they emit warnings and the resolver falls back to the\n * local manifest. This is the AIP-47 spec contract:\n *\n *   \"Treat depth overflow and cycle detection as warnings, not\n *    errors. A role whose chain is malformed MUST still load — the\n *    runtime falls back to the local manifest only.\"\n */\nexport async function resolveRole(\n  ref: RoleRef,\n  opts: ResolveOptions,\n): Promise<ResolvedRole> {\n  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH\n  const visited = new Set<string>()\n  const warnings: ResolveWarning[] = []\n  const chain: string[] = []\n\n  const load = async (current: RoleRef): Promise<RoleManifestRaw | null> => {\n    for (const src of opts.sources) {\n      const m = await src.load(current)\n      if (m !== null) return m\n    }\n    return null\n  }\n\n  // Recursive walker. Returns the merged role (or null on hard failure).\n  // The leaf is loaded first; the parent chain is walked top-down so\n  // we merge child onto parent (parent is the accumulator base).\n  //\n  // `isParentRef` discriminates leaf-miss (caller throws role_unresolvable)\n  // from parent-miss (we warn role_extends_missing and the caller falls\n  // back to its local manifest).\n  const walk = async (\n    current: RoleRef,\n    depth: number,\n    isParentRef: boolean,\n  ): Promise<{ role: RoleHandle; body: string } | null> => {\n    if (depth > maxDepth) {\n      warnings.push({\n        code: \"role_extends_depth_exceeded\",\n        message: `extends chain depth exceeded ${maxDepth} at '${current}'`,\n        depth,\n        ref: current,\n      })\n      return null\n    }\n    if (visited.has(current)) {\n      warnings.push({\n        code: \"role_extends_cycle\",\n        message: `extends cycle detected at '${current}'`,\n        cycle: [...visited, current],\n      })\n      return null\n    }\n    visited.add(current)\n\n    const manifest = await load(current)\n    if (!manifest) {\n      // Parent-miss is a warning (caller falls back); leaf-miss is\n      // surfaced by the top-level caller as role_unresolvable.\n      if (isParentRef) {\n        warnings.push({\n          code: \"role_extends_missing\",\n          message: `parent ref '${current}' did not resolve`,\n          parent: current,\n        })\n      }\n      return null\n    }\n    chain.push(manifest.ref)\n\n    const fm = manifest.frontmatter as Partial<RoleDefinition>\n    const extendsRef = fm.extends\n\n    if (!extendsRef) {\n      return { role: fm as RoleHandle, body: manifest.body }\n    }\n\n    const parent = await walk(extendsRef, depth + 1, true)\n    if (!parent) {\n      // Parent chain broken — fall back to the local manifest only.\n      // The warning was already pushed by the recursive call.\n      return { role: fm as RoleHandle, body: manifest.body }\n    }\n\n    // Apply strategic merge.\n    const merged = mergeRoles(parent.role, fm)\n    warnings.push(...merged.warnings)\n\n    // Body merge — read bodyMerge mode from child metadata.\n    const bodyMode =\n      ((fm.metadata as Record<string, unknown> | undefined)?.[\"aip-47\"] as\n        | { bodyMerge?: \"append-with-separator\" | \"replace\" }\n        | undefined)?.bodyMerge ?? \"append-with-separator\"\n    const body = mergeBodies(parent.body, manifest.body, bodyMode)\n\n    return { role: merged.role, body }\n  }\n\n  const result = await walk(ref, 0, false)\n  if (!result) {\n    // Leaf miss (or hard chain failure with no fallback). Per AIP-47,\n    // the resolver MUST surface `role_unresolvable` and throw — the\n    // caller cannot proceed without a role.\n    const w: ResolveWarning = {\n      code: \"role_unresolvable\",\n      message: `role ref '${ref}' did not resolve in any source`,\n      ref,\n    }\n    warnings.push(w)\n    throw Object.assign(new Error(w.message), { warnings, chain })\n  }\n\n  // Defensive validation of the merged frontmatter.\n  const validated = roleFrontmatterSchema.safeParse(result.role)\n  if (!validated.success) {\n    const issues = validated.error.issues.map(\n      (i) => `${i.path.join(\".\")}: ${i.message}`,\n    )\n    warnings.push({\n      code: \"role_validation_failed\",\n      message: `merged role failed schema validation`,\n      ref,\n      issues,\n    })\n    // Still return the merged role — validators downstream may want\n    // to surface it. The warning makes the failure observable.\n  }\n\n  return {\n    role: validated.success ? (validated.data as RoleHandle) : result.role,\n    body: result.body,\n    chain,\n    warnings,\n  }\n}\n","/**\n * AIP-47 built-in role source.\n *\n * Wraps an AIP-43 `@agentproto/registry` instance keyed by role slug.\n * Intended primarily for runtime-shipped catalogues\n * (`@agentproto/role-catalog`, vendor-specific registries) where the\n * roles are authored in TS and validated at module load time. The\n * registry is mutable post-construction — `register` / `unregister` /\n * `replace` let downstream apps extend the catalogue without forking\n * the OSS package.\n *\n * Refs are matched in three forms:\n *   - bare slug:          `seo-specialist`\n *   - scoped slug:        `builtin/seo-specialist`\n *   - ws:// ref:          `ws://roles/seo-specialist`\n *\n * All three resolve to the same entry. The `scheme` is `builtin`.\n */\n\nimport { createRegistry, type Registry } from \"@agentproto/registry\"\nimport type {\n  BuiltinRoleEntry,\n  RoleManifestRaw,\n  RoleRef,\n  RoleSource,\n} from \"./types.js\"\n\nconst WS_REF_PREFIX = \"ws://roles/\"\nconst BUILTIN_PREFIX = \"builtin/\"\nconst REGISTRY_FAMILY = \"role-builtin\"\n\nfunction normaliseSlug(ref: RoleRef): string {\n  if (ref.startsWith(WS_REF_PREFIX)) return ref.slice(WS_REF_PREFIX.length)\n  if (ref.startsWith(BUILTIN_PREFIX)) return ref.slice(BUILTIN_PREFIX.length)\n  return ref\n}\n\nexport class BuiltinRoleSource implements RoleSource {\n  readonly scheme = \"builtin\"\n\n  /**\n   * Underlying AIP-43 registry. Exposed for advanced consumers that\n   * want to use `lookup(predicate)`, `entries()`, or other registry\n   * primitives. The common operations are mirrored on the source\n   * itself for ergonomics.\n   */\n  readonly registry: Registry<BuiltinRoleEntry>\n\n  constructor(entries: Iterable<BuiltinRoleEntry> = []) {\n    this.registry = createRegistry<BuiltinRoleEntry>({\n      family: REGISTRY_FAMILY,\n      keyBy: (e) => e.slug,\n    })\n    for (const e of entries) {\n      this.registry.register(e)\n    }\n  }\n\n  async load(ref: RoleRef): Promise<RoleManifestRaw | null> {\n    const slug = normaliseSlug(ref)\n    const entry = this.registry.get(slug)\n    if (!entry) return null\n    return {\n      ref: `builtin/${slug}`,\n      frontmatter: entry.handle,\n      body: entry.body ?? \"\",\n      scheme: \"builtin\",\n    }\n  }\n\n  async list(): Promise<readonly RoleRef[]> {\n    return this.registry.list().map((e) => `builtin/${e.slug}`)\n  }\n\n  /* ─── mutation surface (AIP-43 primitive operations) ─────────── */\n\n  /**\n   * Register a new builtin entry. Throws `RegistryDuplicateError`\n   * if a handle with the same slug is already registered — use\n   * `replace` to swap atomically when a hot-reload picks up a\n   * redefined role.\n   */\n  register(entry: BuiltinRoleEntry): void {\n    this.registry.register(entry)\n  }\n\n  /**\n   * Replace an existing entry. Throws `RegistryNotFoundError` if no\n   * entry exists at the resolved slug. Use `register` for new slugs.\n   */\n  replace(entry: BuiltinRoleEntry): void {\n    this.registry.replace(entry)\n  }\n\n  /**\n   * Remove a slug from the registry. Returns true if an entry was\n   * removed. Use sparingly — the registry is intended to be\n   * boot-time-stable.\n   */\n  unregister(slug: string): boolean {\n    return this.registry.unregister(normaliseSlug(slug))\n  }\n\n  /** Returns true if the slug (any ref form) is registered. */\n  has(slug: string): boolean {\n    return this.registry.has(normaliseSlug(slug))\n  }\n\n  /** Number of entries currently registered. */\n  count(): number {\n    return this.registry.count()\n  }\n\n  /**\n   * Filter entries by an arbitrary predicate. Runs in registration\n   * order. Useful for capability lookups like \"every role with\n   * `metadata.aip-47.audience === 'ai-worker'`\".\n   */\n  lookup(\n    predicate: (entry: BuiltinRoleEntry) => boolean,\n  ): readonly BuiltinRoleEntry[] {\n    return this.registry.lookup(predicate)\n  }\n}\n\n/**\n * Convenience: assemble a `BuiltinRoleSource` from a record map.\n * Each entry's key becomes the slug.\n */\nexport function builtinSourceFromRecord(\n  record: Record<string, Omit<BuiltinRoleEntry, \"slug\">>,\n): BuiltinRoleSource {\n  return new BuiltinRoleSource(\n    Object.entries(record).map(([slug, rest]) => ({ slug, ...rest })),\n  )\n}\n","/**\n * @agentproto/role — AIP-47 ROLE.md `defineRole` reference impl.\n *\n * A single-doc markdown + frontmatter format for portable organizational roles — mission, responsibilities, capabilities, tools, KPIs, seniority, reporting line, lifecycle hooks. Sibling to AIP-25 PERSONA (face) and AIP-23 IDENTITY (substance); referenced by AIP-9 OPERATOR (`role:` field) and AIP-6 COMPANY (`roles/<slug>/ROLE.md` doctype). Roles describe what a job is — independent of who holds it (persona/identity) and which instance is hired (operator).\n *\n * Spec: https://agentproto.sh/docs/aip-47\n *\n * Authoring paths:\n *   - TS:  `defineRole({...})` → `RoleHandle`\n *   - MD:  `parseRoleManifest(src) → roleFromManifest({...})` → `RoleHandle`\n *\n * Resolution:\n *   - `resolveRole(ref, { sources })` walks the `extends` chain, applies\n *     strategic merge per the spec, and returns the effective `RoleHandle`\n *     plus the merged body, the resolution chain, and any warnings.\n *\n * Composition (advisory, never grants access):\n *   - Operators consume the resolved role via AIP-9 OPERATOR `role:`\n *     field. Effective permissions come from AIP-38 POLICY, NOT from\n *     the role — see AIP-47 §Role vs Policy vs Governance.\n */\n\nexport const SPEC_NAME = \"agentrole/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\n/**\n * Seniority levels per AIP-47 §Optional fields. Const tuple exported\n * so consumers can derive zod / openapi enum schemas from the single\n * source of truth — keep this in sync with `ROLE.schema.json`.\n */\nexport const ROLE_SENIORITIES = [\n  \"intern\",\n  \"junior\",\n  \"mid\",\n  \"senior\",\n  \"lead\",\n  \"principal\",\n  \"executive\",\n] as const\nexport type RoleSeniority = (typeof ROLE_SENIORITIES)[number]\n\n/**\n * Recommended departments per AIP-47 §Departments (informative).\n * `department` on a ROLE.md is a free string — these values are\n * suggested for cross-runtime alignment. Runtimes that group / chart\n * roles by department SHOULD render this list as the default\n * taxonomy and treat any out-of-list value as a domain-specific\n * extension (legal, R&D, clinical, …).\n *\n * Order is significant: the array order is the recommended display\n * order for org charts and \"hire\" UIs.\n */\nexport const RECOMMENDED_DEPARTMENTS = [\n  \"executive\",\n  \"operations\",\n  \"engineering\",\n  \"product\",\n  \"marketing\",\n  \"sales\",\n  \"customer\",\n  \"finance\",\n  \"people\",\n] as const\nexport type RecommendedDepartment = (typeof RECOMMENDED_DEPARTMENTS)[number]\n\n/**\n * Human-readable label for a department slug. Falls back to a\n * Title-Case-ified version of the slug for departments outside the\n * recommended list (custom org taxonomies).\n */\nexport function departmentLabel(slug: string): string {\n  const labels: Readonly<Record<RecommendedDepartment, string>> = {\n    executive: \"Executive\",\n    operations: \"Operations\",\n    engineering: \"Engineering\",\n    product: \"Product\",\n    marketing: \"Marketing\",\n    sales: \"Sales\",\n    customer: \"Customer\",\n    finance: \"Finance\",\n    people: \"People\",\n  }\n  if ((labels as Record<string, string>)[slug] !== undefined) {\n    return (labels as Record<string, string>)[slug]!\n  }\n  return slug\n    .split(\"-\")\n    .map((s) => (s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1)))\n    .join(\" \")\n}\n\nexport { defineRole } from \"./define-role.js\"\nexport type { RoleDefinition, RoleHandle } from \"./types.js\"\n\n// Resolution / merge — the heart of role composition.\nexport { resolveRole } from \"./resolve.js\"\nexport type {\n  ResolveOptions,\n  ResolveWarning,\n  ResolvedRole,\n} from \"./resolve.js\"\n\nexport {\n  mergeRoles,\n  mergeBodies,\n  LIST_FIELDS,\n  LOCAL_ONLY_FIELDS,\n} from \"./merge.js\"\nexport type {\n  ListField,\n  ListPatch,\n  MergeResult,\n  MergeWarning,\n  RoleChildInput,\n} from \"./merge.js\"\n\n// Source loaders (in-memory builtin shipped here; fs/db live in adapters).\nexport {\n  BuiltinRoleSource,\n  builtinSourceFromRecord,\n} from \"./sources/builtin.js\"\nexport type {\n  BuiltinRoleEntry,\n  RoleManifestRaw,\n  RoleRef,\n  RoleSource,\n} from \"./sources/types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { a as RoleHandle } from '../types-CohqAgUN.js';
+
+/**
+ * AIP-47 ROLE.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-47/draft/ROLE.schema.json` via
+ * json-schema-to-zod. Imported by both `define-role.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-role.ts`'s `validate(def)` instead.
+ */
+
+declare const roleFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"role/v1">;
+    name: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    extends: z.ZodOptional<z.ZodString>;
+    department: z.ZodOptional<z.ZodString>;
+    reports_to: z.ZodOptional<z.ZodString>;
+    seniority: z.ZodEnum<{
+        intern: "intern";
+        junior: "junior";
+        mid: "mid";
+        senior: "senior";
+        lead: "lead";
+        principal: "principal";
+        executive: "executive";
+    }>;
+    mission: z.ZodString;
+    responsibilities: z.ZodArray<z.ZodString>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    kpis: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    strengths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    antiPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    onPromotion: z.ZodOptional<z.ZodString>;
+    onDemotion: z.ZodOptional<z.ZodString>;
+    onAssign: z.ZodOptional<z.ZodString>;
+    appliesTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    defaultPersona: z.ZodOptional<z.ZodString>;
+    defaultIdentity: z.ZodOptional<z.ZodString>;
+    defaultPolicy: z.ZodOptional<z.ZodString>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        packs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type RoleFrontmatter = z.infer<typeof roleFrontmatterSchema>;
+
+/**
+ * AIP-47 ROLE.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `defineRole` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-47/draft/ROLE.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface RoleManifest {
+    frontmatter: RoleFrontmatter;
+    body: string;
+}
+declare function parseRoleManifest(source: string): RoleManifest;
+declare function roleFromManifest(manifest: RoleManifest): RoleHandle;
+
+export { type RoleFrontmatter, type RoleManifest, parseRoleManifest, roleFromManifest, roleFrontmatterSchema };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { roleFrontmatterSchema, defineRole } from '../chunk-U2HQWFCN.mjs';
+export { roleFrontmatterSchema } from '../chunk-U2HQWFCN.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/role v0.1.0-alpha
+ * AIP-47 ROLE.md `defineRole` reference implementation.
+ */
+function parseRoleManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseRoleManifest: missing or empty frontmatter");
+  }
+  const result = roleFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseRoleManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function roleFromManifest(manifest) {
+  return defineRole(manifest.frontmatter);
+}
+
+export { parseRoleManifest, roleFromManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,kBAAkB,MAAA,EAA8B;AAC9D,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,iDAAiD,CAAA;AAAA,EACnE;AACA,EAAA,MAAM,MAAA,GAAS,qBAAA,CAAsB,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC1D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,8CAAA,EAA4C,OAAO,KAAA,CAAM,MAAA,CACtD,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,iBAAiB,QAAA,EAAoC;AAKnE,EAAA,OAAO,UAAA,CAAW,SAAS,WAAwC,CAAA;AACrE","file":"index.mjs","sourcesContent":["/**\n * AIP-47 ROLE.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `defineRole` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-47/draft/ROLE.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { roleFrontmatterSchema, type RoleFrontmatter } from \"../schema.js\"\nimport { defineRole } from \"../define-role.js\"\nimport type { RoleDefinition, RoleHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/role/manifest\" or directly from \"@@agentproto/role/schema\".\nexport { roleFrontmatterSchema, type RoleFrontmatter }\n\nexport interface RoleManifest {\n  frontmatter: RoleFrontmatter\n  body: string\n}\n\nexport function parseRoleManifest(source: string): RoleManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseRoleManifest: missing or empty frontmatter\")\n  }\n  const result = roleFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseRoleManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function roleFromManifest(manifest: RoleManifest): RoleHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // RoleDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return defineRole(manifest.frontmatter as unknown as RoleDefinition)\n}\n"]}

package/dist/types-CohqAgUN.d.ts

@@ -0,0 +1,139 @@
+/**
+ * AIP-47 RoleDefinition + RoleHandle.
+ *
+ * `RoleDefinition` was generated from
+ * `resources/aip-47/draft/ROLE.schema.json` via json-schema-to-typescript.
+ * `RoleHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+/**
+ * Validates the YAML frontmatter portion of an AIP-47 ROLE.md manifest. Single-doc, no oneOf — every role is the same shape. The body is markdown and not validated by this schema.
+ */
+interface RoleDefinition {
+    /**
+     * Schema dispatch tag. MUST be 'role/v1' for this version of AIP-47.
+     */
+    schema: "role/v1";
+    /**
+     * Machine identifier. Lowercase, digits, dashes. Must start with a letter, end with a letter or digit. Unique within the registry that hosts the role.
+     */
+    name: string;
+    /**
+     * Human-readable display title, sentence case.
+     */
+    title: string;
+    /**
+     * One-paragraph job description. The role's purpose, audience, and shape.
+     */
+    description: string;
+    /**
+     * Semver. Bump on breaking change to responsibilities, KPIs, tools, or seniority.
+     */
+    version: string;
+    /**
+     * Relative path to a parent ROLE.md. Triggers composition. Path MUST end in 'ROLE.md'.
+     */
+    extends?: string;
+    /**
+     * Department slug. Lowercase kebab-case. Recommended values listed in AIP-47 §Departments; free-form to accept domain-specific values.
+     */
+    department?: string;
+    /**
+     * Role-to-role reporting link. Conventionally a 'ws://roles/<slug>' ref. Schema does not validate scheme; the loader resolves.
+     */
+    reports_to?: string;
+    /**
+     * Seniority level of the job. Operator instances inherit this; a promotion is re-binding the operator to a higher-seniority role.
+     */
+    seniority: "intern" | "junior" | "mid" | "senior" | "lead" | "principal" | "executive";
+    /**
+     * One-paragraph mission, markdown. The reason the role exists.
+     */
+    mission: string;
+    /**
+     * Ordered imperative clauses. At least one. Lineage accumulates under 'extends' (append-and-dedupe).
+     *
+     * @minItems 1
+     */
+    responsibilities: [string, ...string[]];
+    /**
+     * Competences this role is expected to have. Append-and-dedupe across 'extends'.
+     */
+    capabilities?: string[];
+    /**
+     * AIP-14 tool refs the role declares as intended. Append-and-dedupe across 'extends'. Governance (AIP-7) gates effect.
+     */
+    tools?: string[];
+    /**
+     * AIP-3 skill refs the role expects to load. Append-and-dedupe across 'extends'.
+     */
+    skills?: string[];
+    /**
+     * Scorer slugs (forward AIP) — KPIs evaluated against operators in this role. Append-and-dedupe across 'extends'.
+     */
+    kpis?: string[];
+    /**
+     * Job-side strengths in prose. Append-and-dedupe across 'extends'.
+     */
+    strengths?: string[];
+    /**
+     * What the role explicitly does NOT do. Append-and-dedupe across 'extends'.
+     */
+    antiPatterns?: string[];
+    /**
+     * AIP-39 action ref fired on promotion INTO this role.
+     */
+    onPromotion?: string;
+    /**
+     * AIP-39 action ref fired on demotion OUT of this role.
+     */
+    onDemotion?: string;
+    /**
+     * AIP-39 action ref fired on first assignment of this role.
+     */
+    onAssign?: string;
+    /**
+     * Cross-AIP bindings — restrict the role to specific operators. Local-only under 'extends' (NOT inherited).
+     */
+    appliesTo?: string[];
+    /**
+     * AIP-25 PERSONA ref recommended for operators adopting this role. Advisory; the operator's own 'persona' field overrides.
+     */
+    defaultPersona?: string;
+    /**
+     * AIP-23 IDENTITY ref recommended for operators adopting this role. Advisory; the operator's own 'identity' field overrides.
+     */
+    defaultIdentity?: string;
+    /**
+     * AIP-38 POLICY ref recommended for operators adopting this role. ADVISORY ONLY — role declares intent, policy decides effect. The runtime MUST NOT apply defaultPolicy to an operator without the operator's own 'policy:' field or a governance signature attesting the binding. See AIP-47 §Role vs Policy vs Governance.
+     */
+    defaultPolicy?: string;
+    /**
+     * Generic knowledge this role consults — AIP-10 corpus packs mounted
+     * read-only as a floor beneath the operator's own corpus. Distinct from
+     * 'skills' (what the role knows how to DO): knowledge is what it CONSULTS.
+     * The host unions these with any operator-level packs.
+     */
+    knowledge?: {
+        /**
+         * AIP-10 knowledge-pack refs this role mounts as its generic corpus
+         * floor. The host resolves each ref to a pack and mounts it read-only
+         * UNDER the operator's own editable corpus (the host overlays them).
+         * Append-and-dedupe across 'extends'. Absent = the host's convention
+         * (e.g. a pack named after the role slug). Operator-level packs layer
+         * ABOVE these.
+         */
+        packs?: string[];
+    };
+    /**
+     * Catalog tags. Lowercase kebab-case. Append-and-dedupe across 'extends'.
+     */
+    tags?: string[];
+    /**
+     * Vendor extensions, namespaced under '<vendor>'. Hosts MUST tolerate unknown vendor namespaces; they MUST NOT honour metadata that overrides AIP-defined fields.
+     */
+    metadata?: Record<string, unknown>;
+}
+type RoleHandle = Readonly<RoleDefinition>;
+
+export type { RoleDefinition as R, RoleHandle as a };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@agentproto/role",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/role — AIP-47 ROLE.md reference implementation. A single-doc markdown + frontmatter format for portable organizational roles — mission, responsibilities, capabilities, tools, KPIs, seniority, reporting line, lifecycle hooks. Sibling to AIP-25 PERSONA (face) and AIP-23 IDENTITY (substance); referenced by AIP-9 OPERATOR (`role:` field) and AIP-6 COMPANY (`roles/<slug>/ROLE.md` doctype). Roles describe what a job is — independent of who holds it (persona/identity) and which instance is hired (operator).",
+  "keywords": [
+    "agentproto",
+    "aip-47",
+    "role",
+    "defineRole",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-47",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/role"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.6",
+    "@agentproto/define-doctype": "0.1.0",
+    "@agentproto/registry": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}