@agentproto/corpus-cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/specs/resources/aip-23/draft/IDENTITY.schema.json

@@ -0,0 +1,358 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-23/IDENTITY.schema.json",
+  "title": "agentidentity/v1 frontmatter (AIP-23)",
+  "description": "Validates the YAML frontmatter portion of an AIP-23 IDENTITY.md (workspace root or per-context view). The single doctype 'identity.workspace/v1' is used in both modes; the host distinguishes by checking whether `extends` is set. Per-layer-kind schemas are delegated to AIP-18 (COLLECTION.md / ITEM.md). Items in any layer collection MUST carry a `confidence` field in 0..1; that requirement is enforced at item-load time by the host, not by this schema (which validates the workspace manifest only).",
+  "type": "object",
+  "required": ["schema", "name", "title", "description", "version"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "identity.workspace/v1",
+      "description": "Discriminator for the AIP-23 workspace doctype."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 96,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "description": "Stable kebab-case identifier for the identity or view."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Human-readable title of the identity."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "One-paragraph statement of purpose: what this identity captures, who or what it is about."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9.-]+)?$",
+      "description": "Semantic version of the WORKSPACE shape. Bump on collection / artifact-tier / binding / lint / defaults changes. Independent of any individual layer item's version (AIP-18-side)."
+    },
+    "extends": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(\\.\\./|\\./)[^\\s]+/IDENTITY\\.md$",
+      "description": "OPTIONAL — relative path to a parent IDENTITY.md. Presence makes the manifest a VIEW; absence makes it a WORKSPACE ROOT. Recursive composition; maximum chain depth is 8."
+    },
+    "appliesTo": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(ws://(operators|companies|personas|skills)/[a-z][a-z0-9-]*|\\.\\./[^\\s]+)$",
+        "description": "Either a ws:// ref to an AIP-9 operator, AIP-22 company, AIP-25 persona, or AIP-3 skill, or a relative path to a consumer workspace folder."
+      },
+      "uniqueItems": true,
+      "description": "OPTIONAL — list of consumers this VIEW adapts the identity for. Hosts MUST refuse the view if any binding does not resolve. Not inherited; views declare their own scope."
+    },
+    "executor": {
+      "type": "string",
+      "pattern": "^ws://operators/[a-z][a-z0-9-]*$",
+      "description": "OPTIONAL — AIP-9 operator the identity is *about* or activates against. The host loads this operator when the identity is opened."
+    },
+    "governance": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "OPTIONAL — AIP-7 policy or audit binding. May be a path to an AIP-7 policy file or a ws:// ref. Identity-level approvals (layer mutations, confidence elevation, persona binding) flow through this ref."
+    },
+    "work": {
+      "type": "string",
+      "pattern": "^ws://workspaces/[a-z][a-z0-9-]*$",
+      "description": "OPTIONAL — AIP-20 work tracker the identity participates in (an operator's task queue, a company's program plan)."
+    },
+    "knowledge": {
+      "type": "string",
+      "pattern": "^ws://wikis/[a-z][a-z0-9-]*(/KNOWLEDGE\\.md)?$",
+      "description": "OPTIONAL — AIP-10 KNOWLEDGE.md ref. The identity's narrative wiki, dossier, exemplars."
+    },
+    "collections": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/collectionEntry"
+      },
+      "default": [],
+      "description": "Layer collections enabled by this identity. Each entry is one AIP-18 collection describing ONE layer kind. Three forms supported: inline (full COLLECTION.md frontmatter), file ref, or registry import. Merge-by-effective-name (alias if set, otherwise the collection's name) across the extends chain."
+    },
+    "layers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaultConfidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0,
+          "description": "OPTIONAL — minimum confidence (0..1) the workspace will store. New items below the floor are refused with identity_confidence_below_floor (HARD). Default is 0.0 (no floor). Workspaces with strict identity standards SHOULD set this to 0.5 or higher."
+        },
+        "versioning": {
+          "enum": ["enabled", "disabled"],
+          "default": "enabled",
+          "description": "Whether layer items carry an incrementing version on update. ONE-WAY SWITCH: once 'enabled' at any ancestor, descendants MUST NOT set 'disabled'. Refusal: identity_versioning_disable (HARD)."
+        },
+        "temporal": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "OPTIONAL — whether temporal-entry companion items are supported for layers marked temporal: true on their own collection."
+            },
+            "field": {
+              "type": "string",
+              "pattern": "^[a-z][a-zA-Z0-9_]*$",
+              "default": "validUntil",
+              "description": "OPTIONAL — field name on temporal-entry items carrying expiry. Hosts walk this field on read to exclude expired entries."
+            },
+            "sourceVocabulary": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              },
+              "uniqueItems": true,
+              "default": [
+                "configured",
+                "observed",
+                "inferred",
+                "self-reported"
+              ],
+              "description": "Controlled vocabulary for temporal-entry.source. APPEND-ONLY across ancestors: descendants MAY add new values but MUST NOT remove existing ones."
+            }
+          },
+          "description": "Temporal-layer behaviour at the workspace level."
+        }
+      },
+      "description": "Layer behaviour configuration. Confidence floor, versioning posture, temporal-entry contract."
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the host generates compression artifacts for layer items."
+        },
+        "tiers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "maxTokens"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Stable kebab-case tier id. Conventional values: short, medium, full. Merge key vs parent."
+              },
+              "maxTokens": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 32768,
+                "description": "Target maximum tokens for this tier's artifact. Tiers MUST be MONOTONIC: each tier's maxTokens MUST be strictly greater than the previous tier's. The host re-validates monotonicity after merge."
+              },
+              "strategy": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "OPTIONAL — compression algorithm id. Conventional values: aaak, bullet-list, markdown, or a host-defined string."
+              }
+            }
+          },
+          "default": [],
+          "description": "Compression tiers. Merge-by-id vs parent; child tier with same id overrides parent's. Monotonicity (strictly increasing maxTokens) is re-validated after merge."
+        },
+        "locales": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+          },
+          "uniqueItems": true,
+          "default": [],
+          "description": "Locales for which artifacts are generated. ISO 639-1 (e.g. 'en') with optional ISO 3166-1 region (e.g. 'en-US'). When non-empty, the host produces one artifact per (layer, tier, locale) triple."
+        },
+        "refreshPolicy": {
+          "enum": ["on-write", "scheduled", "manual"],
+          "default": "on-write",
+          "description": "When the host regenerates artifacts. on-write = immediately after layer item mutation (correctness); scheduled = host-defined cadence (cheap, eventually consistent); manual = no auto-refresh."
+        }
+      },
+      "description": "Compression artifact policy. AIP-23's first distinctive contribution."
+    },
+    "binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowedEntities": {
+          "type": "array",
+          "items": {
+            "enum": ["operator", "company", "persona", "user", "skill"]
+          },
+          "uniqueItems": true,
+          "default": ["operator"],
+          "description": "Bearer entity kinds allowed to bind layer items. Workspaces narrow to fit their domain (companion-style: [user, persona]; operator-fleet style: [operator, company]). Cross-references: operator → AIP-9, company → AIP-22, persona → AIP-25, skill → AIP-3, user → host-defined."
+        },
+        "exclusivity": {
+          "enum": ["per-entity-and-layer"],
+          "default": "per-entity-and-layer",
+          "description": "Binding exclusivity rule. ONE-WAY SWITCH on relaxation: once 'per-entity-and-layer' (or stricter, when added) at any ancestor, descendants MUST NOT replace with a more permissive value. Refusal: identity_binding_loosen (HARD). Currently only 'per-entity-and-layer' is defined; future values may add stricter forms."
+        },
+        "verifyExistence": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the host verifies the bearer entity exists before allowing the binding. ONE-WAY SWITCH on relaxation: once 'true' at any ancestor, descendants MUST NOT set false. Refusal: identity_binding_verify_relax (HARD). Setting false is permitted for ephemeral / sandbox deployments but SHOULD never be used in production."
+        }
+      },
+      "description": "Junction policy. Which bearer entity kinds may bind layer items as their identity, and how exclusively."
+    },
+    "lints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "severity"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Stable kebab-case lint id. Merge key when composing with extends parent."
+          },
+          "kind": {
+            "enum": [
+              "orphan-layer",
+              "low-confidence-pinned",
+              "stale-temporal",
+              "unbound-layer",
+              "missing-required-layer",
+              "custom"
+            ],
+            "description": "Workspace-spanning lint algorithm. AIP-18 per-collection lints (missing-owner, overdue, required-field, etc.) live on COLLECTION.md and are NOT redeclared here. 'custom' delegates to a host-defined check identified by `id`."
+          },
+          "severity": {
+            "enum": ["error", "warn", "info"],
+            "description": "Lint severity. Children may soften; governance policies MAY forbid softening below `error`."
+          },
+          "params": {
+            "type": "object",
+            "additionalProperties": true,
+            "default": {},
+            "description": "Kind-specific parameters. e.g. { layers: [soul, personality] } for missing-required-layer; { days: 30 } for stale-temporal; { threshold: 0.5 } for low-confidence-pinned."
+          }
+        }
+      },
+      "default": [],
+      "description": "Workspace-spanning lints. Merge-by-id vs parent."
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "approvalClass": {
+          "type": "string",
+          "pattern": "^(auto|always|on-mutate|policy:[A-Za-z0-9_./:-]+)$",
+          "description": "Approval class for layer mutations. 'auto' = no gate; 'always' = every mutation requires approval; 'on-mutate' = approval on field-level mutations; 'policy:<ref>' = delegate to an AIP-7 policy."
+        },
+        "auditMutations": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether layer mutations are audited. ONE-WAY SWITCH: once true at any ancestor, descendants MUST NOT set false. Refusal: identity_audit_downgrade (HARD)."
+        }
+      },
+      "description": "Default approval and audit posture."
+    },
+    "display": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "homePage": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$",
+          "description": "OPTIONAL — id of the layer or item to use as the identity landing page (e.g. SOUL-acme-founder)."
+        },
+        "defaultGrouping": {
+          "enum": ["layer", "entity"],
+          "description": "Default grouping for list views. 'layer' = one section per layer kind; 'entity' = one section per bearer entity."
+        }
+      },
+      "description": "Display hints for UIs that render the identity. Runtime-agnostic."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Vendor-specific extensions, namespaced under <vendor>. Deep-merged across the extends chain. MUST NOT change the meaning of any spec field."
+    }
+  },
+  "allOf": [
+    {
+      "description": "A view (any manifest with appliesTo set) MUST extend a parent. A workspace-root manifest has neither field.",
+      "if": {
+        "required": ["appliesTo"],
+        "properties": {
+          "appliesTo": { "type": "array", "minItems": 1 }
+        }
+      },
+      "then": {
+        "required": ["extends"]
+      }
+    }
+  ],
+  "$defs": {
+    "collectionEntry": {
+      "oneOf": [
+        { "$ref": "#/$defs/collectionInline" },
+        { "$ref": "#/$defs/collectionRef" }
+      ],
+      "description": "One layer-collection declaration. Either an inline AIP-18 collection schema, or a ref (path or ws:// URI) optionally aliased and version-pinned."
+    },
+    "collectionInline": {
+      "type": "object",
+      "required": ["inline"],
+      "additionalProperties": false,
+      "properties": {
+        "inline": {
+          "$ref": "https://agentproto.sh/schemas/aip-18/COLLECTION.schema.json#/$defs/schema",
+          "description": "Full AIP-18 collection.schema/v1 frontmatter, parsed in-place. The host registers the layer collection directly via AIP-18's defineCollection without loading a separate file."
+        }
+      },
+      "description": "Inline layer-collection declaration. Full AIP-18 schema embedded; hosts MUST validate it against the AIP-18 COLLECTION schema before registration."
+    },
+    "collectionRef": {
+      "type": "object",
+      "required": ["ref"],
+      "additionalProperties": false,
+      "properties": {
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^((\\.\\./|\\./)[^\\s]+/COLLECTION\\.md|ws://collections/[a-z][a-z0-9-]*)$",
+          "description": "Either a relative path to a COLLECTION.md (file ref) or a ws://collections/<slug> URI (registry import). The host loads the referenced collection via AIP-18 and registers it under its name (or the alias, if set)."
+        },
+        "alias": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "minLength": 2,
+          "maxLength": 96,
+          "description": "OPTIONAL — workspace-local name to expose the layer collection under. Two collections resolving to the same effective name (alias or upstream) is a HARD failure: identity_collection_alias_conflict."
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "OPTIONAL — semver range (e.g. \"1.x\", \"^1.2\", \"1.2.0\"). When set, schema bumps outside the range fail with collection_item_schema_pinned_drift (HARD, AIP-18 vocabulary) at item load time."
+        }
+      },
+      "description": "Layer-collection ref declaration. Either a file path (./.. /COLLECTION.md) or a registry URI (ws://collections/<slug>)."
+    }
+  }
+}