@agenticprimitives/ontology 1.0.0-alpha.4 → 1.0.0-alpha.41

package/README.md

@@ -1,13 +1,12 @@
 # @agenticprimitives/ontology
 
-The **monorepo-wide formal vocabulary** for agentic primitives — the off-chain
-source of truth that the on-chain ontology ([ADR-0009](../../docs/architecture/decisions/0009-on-chain-ontology-shacl-naming.md))
-instantiates and that [`identity-directory`](../identity-directory) (spec 223)
-conforms to.
+**A trust substrate is only as coherent as its vocabulary.** When thirty packages, forty-two contracts, and a knowledge graph all talk about agents, credentials, custody, and delegation, "what exactly is a `CredentialFacet`" cannot have thirty answers. This package is the monorepo-wide formal vocabulary — the off-chain source of truth that the on-chain ontology ([ADR-0009](../../docs/architecture/decisions/0009-on-chain-ontology-shacl-naming.md)) instantiates and that [`identity-directory`](../identity-directory) (spec 223) conforms to.
 
-See [spec 225](../../specs/225-ontology.md) for the full contract and
-[ADR-0018](../../docs/architecture/decisions/0018-agenticprimitives-wide-formal-ontology.md)
-for the decision.
+It is deliberately declarative: it names and constrains, it never authorizes. The vocabulary root depends on nothing — not even `@agenticprimitives/types` — so every other package can reference the same IRIs without inverting the dependency graph.
+
+> Part of [agenticprimitives](../../README.md) — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
+
+See [spec 225](../../specs/225-ontology.md) for the full contract and [ADR-0018](../../docs/architecture/decisions/0018-agenticprimitives-wide-formal-ontology.md) for the decision.
 
 ## Layout (T-box / C-box / A-box)
 
@@ -16,12 +15,15 @@ context.jsonld   @context — namespace prefix → IRI bindings
 tbox/            RDFS/OWL schema (classes + properties), per domain
 cbox/            SHACL shapes + SKOS controlled vocabularies (codelists)
 abox/            example / fixture instances (tests + golden vectors only)
+mappings/        external-standard crosswalks (HCS / ERC-8004, spec 226)
 src/index.ts     typed IRI constants + artifact paths
 ```
 
-This mirrors the reference ontology work
-(`agentictrustlabs/smart-agent/docs/ontology`): T-box = terminology, C-box =
-constraints + controlled vocabularies, A-box = instances.
+T-box = terminology, C-box = constraints + controlled vocabularies, A-box = instances.
+
+UML class-diagram documentation of the T-box — inheritance + relationships per domain area —
+lives in [`docs/tbox/`](docs/tbox/README.md). For the plain-language version — the principles
+the vocabulary protects and why — start with [`docs/story.md`](docs/story.md).
 
 ## Usage
 
@@ -32,20 +34,56 @@ CLASS.CanonicalAgentId; // "https://agenticprimitives.dev/ns/core#CanonicalAgent
 artifactPath(ARTIFACTS.tbox[0]); // absolute path to tbox/core.ttl — load into a SPARQL store
 ```
 
-The package is **declarative**: it ships the vocabulary artifacts and exposes
-their IRIs/paths. It contains no runtime auth/policy logic. SHACL-engine
-validation over instances, and the live A-box knowledge graph (a SPARQL store —
-Ontotext GraphDB reference), are wired by consumers in Phase 2 (spec 225 §11).
+Two entry points, split on purpose:
+
+- **Main entry (browser-safe)** — pure IRI constants: `NS`, `CLASS`, `PREDICATE`, `SHAPE`, `ONTOLOGY_VERSION`. No Node builtins; this is what `identity-directory` (and through it, browser apps) imports.
+- **`/artifacts` subpath (Node-only)** — `ARTIFACTS` + `artifactPath(rel)` to resolve the shipped TTL/JSON-LD files for a SPARQL loader or SHACL engine. Server-side only.
+
+## How it's different
+
+Generic SKOS/SHACL toolchains manage vocabularies as documents — governed in an editor, detached from the systems that depend on them, drifting the moment runtime code changes. Here the vocabulary is load-bearing and lockstep-checked in three directions:
+
+1. **On chain** — a shape or predicate here must match its on-chain counterpart in `OntologyTermRegistry` / `ShapeRegistry` (spec 225 §8); drift is logged as a finding, not tolerated as skew.
+2. **In TypeScript** — the IRIs mirror the branded types in [`types`](../types) (`CanonicalAgentId`, `Assurance`, …). One brand; this package names the IRI, never redefines the type.
+3. **Across standards** — `mappings/*.ttl` carries explicit crosswalks to external agent-identity standards (HCS, ERC-8004, OASF) instead of informal "roughly corresponds to" prose.
+
+And it ships light: no heavy RDF/SHACL libraries in the published surface — consumers wire their own engines against the artifacts.
+
+## Scope
 
-## Scope (Phase 1)
+Bounded to generic AP primitives: identity, credential, custody, delegation, audit, naming, org, registry/discovery, trust, public exposure findings, and the substrate-spine T-box class definitions (spec 225 §11.5). Runtime SHACL shapes for product flows live in their owning packages; GraphDB A-box ingestion shapes for discovery live in `cbox/discovery-graph-shapes.shacl.ttl`; vertical vocabulary remains app-owned ([ADR-0021](../../docs/architecture/decisions/0021-generic-packages-vs-white-label-apps.md)).
 
-Bounded to the agent-trust core: identity, credential, custody, delegation,
-audit, naming, org. Marketplace / intents / geo are out of scope (spec 225 §11).
+The discovery ontology deliberately builds from the domain-derived vocabulary shape in Agent Explorer's `apps/ontology/ontology` modules — `core.ttl`, `discovery.ttl`, `descriptors.ttl`, `erc8004.ttl`, `hol.ttl`, `oasf.ttl`, and `trust.ttl` — while refining it into AP-native namespaces rooted in PROV-O and DOLCE+DnS/DUL.
+
+### Module map (additions by spec)
+
+| Concern | T-box | C-box |
+|---------|-------|-------|
+| Identity, kinds, derived types | `tbox/core.ttl`, `tbox/identity.ttl` | `cbox/controlled-vocabularies.ttl`, `cbox/canonical-agent-id-shape.shacl.ttl` |
+| Typed naming, registry core (spec 346) | `tbox/naming.ttl`, `tbox/registry.ttl` | `cbox/naming-registry-shapes.shacl.ttl`, `cbox/registry-vocabulary.ttl` |
+| Capabilities, claims, taxonomy mappings (specs 251/325/347 §5) | `tbox/skills.ttl` (`aps:SkillTaxonomyMapping` — `relation` = a SKOS mapping property) | `cbox/skill-vocabulary.ttl`, `cbox/capability-catalog-shapes.shacl.ttl` |
+| **Canonical profile → A2A Agent Card → projection → publication → external identity binding (spec 347 §11; ADR-0062)** | `tbox/card-projection.ttl` — a second module of the `ap:` core namespace; PROV-O-grounded (generation/publication ⊑ `prov:Activity`; artifact/releases ⊑ `prov:Entity`; publisher/adapter ⊑ `prov:SoftwareAgent`); "canonical agent" ≡ `ap:Agent`, no second class | `cbox/card-projection-shapes.shacl.ttl` — public card metadata; projection provenance (all **eight** digests as named sub-properties of `ap:hasDigest`); external binding; **public disclosure boundary** (SPARQL-targeted at `ap:disclosureScope "public"`: no loopback / private / link-local endpoint, no vault locator; absence of scope is private). Codelists `ap:lossCategoryScheme`, card-release / projection-instance / binding lifecycles, `ap:bindingVerificationStateScheme`, `ap:digestRoleScheme` in `cbox/controlled-vocabularies.ttl` |
+| Agentic interaction (spec 340) | `tbox/interaction.ttl` | `cbox/interaction-shapes.shacl.ttl`, `cbox/interaction-vocabulary.ttl` |
+| Coordination / engagement / execution (specs 332/336/330) | `tbox/coordination.ttl`, `tbox/engagement.ttl`, `tbox/execution.ttl`, `tbox/plan.ttl` | — |
 
 ## What this is NOT
 
-- Not the TS types — `@agenticprimitives/types` owns `CanonicalAgentId`,
-  `Assurance`, etc.; this package names the IRIs. One brand.
+- Not the TS types — `@agenticprimitives/types` owns `CanonicalAgentId`, `Assurance`, etc.; this package names the IRIs. One brand.
 - Not the runtime CAIP-10 builder — that is `@agenticprimitives/agent-profile`.
-- Not an authority — it names + validates; it never grants custody or mints
-  identity.
+- Not an authority — it names and validates; it never grants custody or mints identity.
+
+## Status
+
+**Phase 1 implemented** — the T/C/A-box artifacts, mappings, and the declarative TS surface ship today. SHACL-engine validation over instances and the live A-box knowledge graph (a SPARQL store — Ontotext GraphDB reference, projected by `identity-directory`) are Phase 2, wired by consumers per spec 225 §11 — and even then the ontology stays a validator, never an authority.
+
+> Testnet/pilot-ready. Production launch is gated on the public checklist in the root README — including third-party contract audit and governance key rotation. Track every security finding live in [`docs/audits/findings.yaml`](../../docs/audits/findings.yaml).
+
+**Authoritative spec:** [`specs/225-ontology.md`](../../specs/225-ontology.md). Bounded surface: `CLAUDE.md` + `capability.manifest.json`.
+
+## Build
+
+```bash
+pnpm --filter @agenticprimitives/ontology typecheck
+pnpm --filter @agenticprimitives/ontology test
+pnpm --filter @agenticprimitives/ontology build
+```

package/cbox/agent-facet-shapes.shacl.ttl

@@ -0,0 +1,130 @@
+# C-box — SHACL over the public agent PROFILE facet and the projected TRUST FABRIC (spec 331).
+#
+# Validates the A-box the discovery indexer writes: approf:* profile properties (including the
+# three facets registered by governor tx 0x53acec54…) and the aptrust:TrustGraphEdge /
+# apatt:Attestation nodes whose vocabulary tbox/trust.ttl now declares.
+#
+# Enforcement posture (spec 225 §11 / PD-19): these shapes are DECLARED here and enforced by the
+# indexer's TS validators at projection time and by a SHACL engine over graph snapshots. They are
+# never on a hot path and never an authorization input.
+#
+# WHAT A VIOLATION MEANS: a conformance failure here means the WRITER published a malformed facet
+# — it does not mean the agent is untrustworthy, and it must never silently drop the agent from a
+# result set. Fail LOUD to the indexer's audit, fail OPEN to fewer signals for the matcher
+# (ADR-0013 / spec 329 §4: degrade to fewer signals, never to fewer candidates).
+
+@prefix sh:     <http://www.w3.org/ns/shacl#> .
+@prefix approf: <https://agenticprimitives.dev/ns/profile#> .
+@prefix aptrust: <https://agenticprimitives.dev/ns/trust#> .
+@prefix apatt:  <https://agenticprimitives.dev/ns/attestation#> .
+@prefix ap:     <https://agenticprimitives.dev/ns/core#> .
+@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
+
+# ═══ The public profile facet ═══════════════════════════════════════════════
+
+approf:AgentProfileShape a sh:NodeShape ;
+    sh:targetClass approf:AgentProfile ;
+    rdfs:label "AgentProfileShape" ;
+    rdfs:comment "Every property is OPTIONAL. A public profile is opt-in in whole and in part (facet-registries invariant 3/4): an agent that publishes nothing is conformant, and absence is never a defect." ;
+
+    sh:property [
+        sh:path approf:displayName ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 128 ;
+    ] ;
+    sh:property [
+        sh:path approf:description ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 2048 ;
+        sh:description "SA-keyed. The node-keyed name-record description is apnam:description and MUST NOT be emitted under this IRI (facet-registries G8)." ;
+    ] ;
+    sh:property [
+        sh:path approf:skills ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 2048 ;
+        sh:description "Comma-joined declared capability projections. Spec 331 migrates the value space to canonical catalog ids; both are legal during the dual-publish window." ;
+    ] ;
+
+    # ── approf:declaresCapabilityId — one triple per parsed id (spec 331) ────
+    sh:property [
+        sh:path approf:declaresCapabilityId ;
+        sh:datatype xsd:string ;
+        sh:pattern "^[a-z][a-z0-9]*:[a-z0-9]+(-[a-z0-9]+)*$" ;
+        sh:message "A capability id is a lowercase CURIE: '<prefix>:<kebab-slug>', e.g. 'adv:succession-plan-design'. keccak256 of this exact string is the on-chain skillId, so spelling is identity — it is never normalized, corrected, or case-folded at read time." ;
+    ] ;
+
+    # ── G2: languages, BCP-47 ───────────────────────────────────────────────
+    sh:property [
+        sh:path approf:languages ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 256 ;
+        sh:pattern "^[a-z]{2,3}(-[a-z0-9]{2,8})*(,[a-z]{2,3}(-[a-z0-9]{2,8})*)*$" ;
+        sh:message "atl:languages must be comma-separated, lowercase, well-formed BCP-47 tags with no spaces: 'es,en,pt-br'. See cbox/profile-facet-vocabulary.ttl for the subtag-prefix matching rule — substring matching is forbidden." ;
+    ] ;
+
+    # ── G3: regions, GeoFeatureRegistry-drawn ───────────────────────────────
+    sh:property [
+        sh:path approf:regions ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 256 ;
+        sh:pattern "^[A-Z0-9]{2,8}(-[A-Z0-9]{1,3})?(,[A-Z0-9]{2,8}(-[A-Z0-9]{1,3})?)*$" ;
+        sh:message "atl:regions must be comma-separated UPPERCASE codes with no spaces: 'EU,ES,ES-CT'. Each code must resolve to an ISO 3166 entry or a registered GeoFeatureRegistry feature; a code that resolves to neither is a conformance failure, NOT a free-text fallback (spec 251 forward-compatibility)." ;
+    ] ;
+
+    # ── G4: focus areas, open but shaped ────────────────────────────────────
+    sh:property [
+        sh:path approf:focusAreas ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:maxLength 512 ;
+        sh:pattern "^[a-z0-9]+(-[a-z0-9]+)*(,[a-z0-9]+(-[a-z0-9]+)*)*$" ;
+        sh:message "atl:focusAreas must be comma-separated lowercase-hyphenated subject labels. A focus area is a subject domain (apctx:KnowledgeDomain), never a declared capability, and never a hard filter." ;
+    ] .
+
+# ── The encoding this migration removes, stated as a shape ──────────────────
+
+approf:NoEncodedFacetInSkillsShape a sh:NodeShape ;
+    sh:targetClass approf:AgentProfile ;
+    rdfs:label "NoEncodedFacetInSkillsShape" ;
+    rdfs:comment "Spec 331 §hack-1. Before the three facet predicates existed, languages, regions, jurisdictions and focus areas were stuffed into atl:skills as prefixed tokens (lang-es, region-eu, jurisdiction-spain, focus-*). The prefixes were deliberate and honest — they kept the encoding VISIBLE rather than silently conflating a language with a capability. Now that real predicates exist, the encoding is debt: a token matching these prefixes is a facet that belongs in atl:languages / atl:regions / atl:focusAreas. SEVERITY IS sh:Warning, not sh:Violation, and stays that way until the migration's dual-publish window closes — a live agent mid-migration is correct, not broken." ;
+    sh:property [
+        sh:path approf:skills ;
+        sh:severity sh:Warning ;
+        sh:not [ sh:pattern "(^|,\\s*)(lang|region|jurisdiction|focus)-" ] ;
+        sh:message "atl:skills carries an ENCODED facet token (lang-*/region-*/jurisdiction-*/focus-*). Publish it as atl:languages, atl:regions or atl:focusAreas instead — a subject domain, a place and a language are not declared capabilities (ADR-0051)." ;
+    ] .
+
+# ═══ The projected trust fabric ═════════════════════════════════════════════
+
+aptrust:TrustGraphEdgeShape a sh:NodeShape ;
+    sh:targetClass aptrust:TrustGraphEdge ;
+    rdfs:label "TrustGraphEdgeShape" ;
+    rdfs:comment "A projected AgentRelationship edge. Subject and object are ABSOLUTE and required: one on-chain record is shared by both endpoints under one derived IRI, so the node must state the edge without reference to who is reading it. The endpoint-relative views (ap:relatedAgent, ap:edgeDirection) hang on the agent and are validated by AgentTrustFabricShape below." ;
+    sh:property [ sh:path ap:edgeId ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:pattern "^0x[0-9a-f]{64}$" ;
+        sh:message "edgeId is the deterministic on-chain computeEdgeId(subject, object, type) as lowercase 0x-hex." ] ;
+    sh:property [ sh:path ap:edgeSubject ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "Every edge has exactly one proposing subject — proposeEdge requires msg.sender == subject." ] ;
+    sh:property [ sh:path ap:edgeObject ; sh:minCount 1 ; sh:maxCount 1 ] ;
+    sh:property [ sh:path ap:relationshipTypeId ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "The raw bytes32 type id is ALWAYS emitted, including for governor-registered types whose label does not resolve (ADR-0013: no silent gaps)." ] ;
+    sh:property [ sh:path ap:relationshipType ; sh:datatype xsd:string ; sh:maxCount 1 ;
+        sh:description "The resolved well-known label. Optional by design — an unresolved type is queryable via relationshipTypeId." ] ;
+    sh:property [ sh:path ap:edgeStatus ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:in ( "PROPOSED" "CONFIRMED" "ACTIVE" "REVOKED" ) ;
+        sh:message "Only ACTIVE edges may inform trust scoring: a PROPOSED edge is one party talking to itself, and REVOKED is terminal." ] ;
+    sh:property [ sh:path ap:edgeSubject ;
+        sh:disjoint ap:edgeObject ;
+        sh:message "An agent cannot relate to itself — the contract rejects subject == object, and a self-edge in the graph is a projection defect." ] .
+
+apatt:AttestationShape a sh:NodeShape ;
+    sh:targetClass apatt:Attestation ;
+    rdfs:label "AttestationShape" ;
+    rdfs:comment "A projected AttestationRegistry row. The chain holds a COMMITMENT (credentialHash); the body is off-chain and never reaches the knowledge graph (ADR-0040). Discovery may therefore learn THAT an attestation of type X from issuer Y exists — never what it says." ;
+    sh:property [ sh:path apatt:uid ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:pattern "^0x[0-9a-f]{64}$" ] ;
+    sh:property [ sh:path apatt:credentialType ; sh:datatype xsd:string ; sh:maxCount 1 ] ;
+    sh:property [ sh:path ap:attestationIssuer ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:description "The SIGNER, recomputed from the EIP-712 digest on chain — never msg.sender, which the registry leaves unconstrained. This is what lets an endorsement be relayed by a third party while the authority stays with the issuer." ] ;
+    sh:property [ sh:path ap:attestationValid ; sh:datatype xsd:boolean ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:description "isValid(uid) at index time. NOTE AR-06: there is no issuer-revoke entrypoint, so issuer-side revocation (offchainCredentialStatusList) is NOT reflected here. A consumer treating this as a full revocation check is wrong." ] ;
+    sh:property [ sh:path apatt:credentialHash ; sh:maxCount 1 ;
+        sh:description "A commitment. Never dereferenced by discovery, never a searchable field." ] .
+
+ap:AgentTrustFabricShape a sh:NodeShape ;
+    sh:targetClass ap:Agent ;
+    rdfs:label "AgentTrustFabricShape" ;
+    rdfs:comment "The endpoint-RELATIVE denormalizations and the counts trustScore reads." ;
+    sh:property [ sh:path ap:edgeDirection ; sh:datatype xsd:string ; sh:in ( "subject" "object" ) ] ;
+    sh:property [ sh:path ap:edgeCount ; sh:datatype xsd:integer ; sh:maxCount 1 ; sh:minInclusive 0 ] ;
+    sh:property [ sh:path ap:activeEdgeCount ; sh:datatype xsd:integer ; sh:maxCount 1 ; sh:minInclusive 0 ] ;
+    sh:property [ sh:path ap:attestationCount ; sh:datatype xsd:integer ; sh:maxCount 1 ; sh:minInclusive 0 ] ;
+    sh:property [ sh:path ap:validAttestationCount ; sh:datatype xsd:integer ; sh:maxCount 1 ; sh:minInclusive 0 ] .

package/cbox/capability-catalog-shapes.shacl.ttl

@@ -0,0 +1,284 @@
+# C-box — SHACL for capability CATALOGS and REALIZATION CONTRACTS
+# (spec 330 W0 §7, unparked by spec 331; capability-architecture.md §2 + §5).
+#
+# Three groups:
+#   1. What a well-formed capability + definition + catalog looks like.
+#   2. The ANTI-PATTERN AXIOMS from architecture §2, expressed as shapes rather than prose.
+#   3. The realization-contract META-SHAPE, plus the ONE contract this substrate can actually
+#      enforce today (spec 329's routed member consultation).
+#
+# On (3), the governing discipline: an unenforceable contract is worse than an absent one.
+# A capability whose realizations this substrate cannot observe declares
+# `aps:contractStatus "deferred"` with a rationale naming the missing evidence. The
+# DeferredContractShape below makes that declaration MANDATORY — you may omit a contract, but
+# you may not omit saying why.
+
+@prefix sh:      <http://www.w3.org/ns/shacl#> .
+@prefix aps:     <https://agenticprimitives.dev/ns/skill#> .
+@prefix apctx:   <https://agenticprimitives.dev/ns/context#> .
+@prefix apguide: <https://agenticprimitives.dev/ns/guidance#> .
+@prefix apexec:  <https://agenticprimitives.dev/ns/execution#> .
+@prefix aprole:  <https://agenticprimitives.dev/ns/role#> .
+@prefix apmsg:   <https://agenticprimitives.dev/ns/messaging#> .
+@prefix apint:   <https://agenticprimitives.dev/ns/intent#> .
+@prefix ap:      <https://agenticprimitives.dev/ns/core#> .
+@prefix prov:    <http://www.w3.org/ns/prov#> .
+@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
+
+# ═══ 1. Well-formedness ═════════════════════════════════════════════════════
+
+aps:CapabilityShape a sh:NodeShape ;
+    sh:targetClass aps:Capability ;
+    rdfs:label "CapabilityShape" ;
+    sh:property [ sh:path aps:capabilityId ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:pattern "^[a-z][a-z0-9]*:[a-z0-9]+(-[a-z0-9]+)*$" ;
+        sh:message "A capability id is a lowercase CURIE '<prefix>:<kebab-slug>'. keccak256 of this exact string is the on-chain skillId, so the spelling IS the identity: a rename is a new capability plus a skos:exactMatch, never an edit." ] ;
+    sh:property [ sh:path apctx:ownedByContext ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "Exactly ONE accountable owning bounded context (architecture invariant 2). A capability may PARTICIPATE in many contexts via apctx:classifiedBy — but 'everyone owns it' means nobody versions it." ] ;
+    sh:property [ sh:path apctx:levelInMap ; sh:maxCount 0 ;
+        sh:message "levelInMap belongs on an apctx:CapabilityMapEntry, never on a capability. A map is a VIEW projected from the graph; baking a presentation level into the capability is how a reporting hierarchy becomes an ontology (architecture §3)." ] ;
+    sh:property [ sh:path aps:specializesCapability ;
+        sh:disjoint aps:hasComponentCapability ;
+        sh:message "A capability cannot both BE a narrower form of X and HAVE X as a part. If both feel true, the relation is probably requiresCapability." ] .
+
+aps:CapabilityDefinitionShape a sh:NodeShape ;
+    sh:targetClass aps:CapabilityDefinition ;
+    rdfs:label "CapabilityDefinitionShape" ;
+    sh:property [ sh:path aps:definesCapability ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "A definition defines exactly one capability. Many definition VERSIONS may define the same identity — that is the point of separating them." ] ;
+    sh:property [ sh:path aps:outcomeStatement ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:minLength 20 ; sh:maxLength 400 ;
+        sh:message "Required, and required to be a sentence. An outcome statement that can only be phrased as an activity ('advises on X') is the tell that the term is a service or a subject domain, not a capability." ] ;
+    sh:property [ sh:path aps:contractStatus ; sh:datatype xsd:string ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:in ( "enforced" "deferred" ) ;
+        sh:message "Every definition states whether its realization contract is enforced or deferred. Silence is not an option: it would let a catalog imply verification it does not perform." ] .
+
+aps:DeferredContractShape a sh:NodeShape ;
+    sh:targetClass aps:CapabilityDefinition ;
+    rdfs:label "DeferredContractShape" ;
+    rdfs:comment "Deferral is first-class and honest — but it must be ARGUED. This shape is the whole reason the catalog can ship with two enforced contracts and forty-three deferred ones without that being a cop-out." ;
+    sh:sparql [
+        sh:message "aps:contractStatus 'deferred' requires aps:deferredContractRationale naming the evidence that would make a contract enforceable; 'enforced' requires an aps:hasRealizationContract." ;
+        sh:prefixes aps: ;
+        sh:select """
+            SELECT $this WHERE {
+              { $this <https://agenticprimitives.dev/ns/skill#contractStatus> "deferred" .
+                FILTER NOT EXISTS { $this <https://agenticprimitives.dev/ns/skill#deferredContractRationale> ?r } }
+              UNION
+              { $this <https://agenticprimitives.dev/ns/skill#contractStatus> "enforced" .
+                FILTER NOT EXISTS { $this <https://agenticprimitives.dev/ns/skill#hasRealizationContract> ?c } }
+            }
+        """ ;
+    ] .
+
+aps:CapabilityCatalogShape a sh:NodeShape ;
+    sh:targetClass aps:CapabilityCatalog ;
+    sh:property [ sh:path aps:catalogSteward ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "One steward per catalog — the account SkillDefinitionRegistry will require as msg.sender to publish or version any definition in it." ] .
+
+# ═══ 2. The anti-pattern axioms as shapes (architecture §2) ═════════════════
+
+aps:CapabilityProtocolProjectionShape a sh:NodeShape ;
+    sh:targetClass aps:CapabilityProtocolProjection ;
+    rdfs:label "CapabilityProtocolProjectionShape" ;
+    rdfs:comment "AXIOM 1 + INVARIANT 6. A card AgentSkill / atl:skills token / offering declares exactly ONE primary capability and NEVER identifies an internal plan. The forbidden shape is `implementedBy exactly-1` between a projection and a SKILL.md: a descriptor is fulfilled through a realization whose execution plan may use zero, one, or several playbooks, plus tools, delegated agents and human steps." ;
+    sh:property [ sh:path aps:declaresCapability ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "Exactly one primary declared capability per projection. An advertisement that declares three outcomes is three advertisements." ] ;
+    sh:property [ sh:path apguide:supportsCapability ; sh:maxCount 0 ;
+        sh:message "A projection must not reference a playbook. supportsCapability runs from the PACKAGE to the capability, never from the advertisement — a card skill is not 'the SKILL.md's public face' (axiom 1)." ] .
+
+aps:NoDeclarationOnProtocolFeaturesShape a sh:NodeShape ;
+    rdfs:label "NoDeclarationOnProtocolFeaturesShape" ;
+    rdfs:comment "AXIOM 2. A2A AgentCapabilities (streaming, pushNotifications, extensions) are PROTOCOL FEATURES. `streaming: true` declares transport behaviour, not an outcome." ;
+    sh:targetObjectsOf aps:declaresCapability ;
+    sh:not [ sh:class <https://a2aproject.github.io/A2A/ns#AgentCapabilities> ] ;
+    sh:message "An A2A AgentCapabilities node may never be the subject of declaresCapability — protocol features are not business capabilities." .
+
+aps:NoAuthorityFromClassificationShape a sh:NodeShape ;
+    rdfs:label "NoAuthorityFromClassificationShape" ;
+    rdfs:comment "AXIOM 4 + 5, stated for readers rather than validators: bearing a taxon, a declared label, a claim credential, or a demonstrated edge grants NOTHING. Authorization is delegation ∩ entitlement ∩ policy, evaluated at the gate at the moment of use. No shape can enforce this — it is enforced by the gate never reading any of these predicates — so it is recorded here as doctrine at the point where a reader would otherwise be tempted." ;
+    sh:targetNode aps:assertsCapability ;
+    sh:deactivated true .
+
+# ═══ 3. Realization contracts ═══════════════════════════════════════════════
+
+aps:CapabilityRealizationContractShape a sh:NodeShape ;
+    sh:targetClass aps:CapabilityRealizationContract ;
+    rdfs:label "CapabilityRealizationContractShape (the META-SHAPE)" ;
+    rdfs:comment "What every realization contract must itself contain. A contract is a SHACL shape over PROV; this shape validates the contracts, not the executions. THE PATTERN, in five required parts: (a) sh:targetClass — the activity type; (b) prov:used — required input entity types; (c) prov:generated — required output entity types; (d) prov:qualifiedAssociation — an association carrying BOTH a prov:agent with a prov:hadRole AND a prov:hadPlan; (e) completion conditions — an end time and a terminal state. Part (e) is what makes a contract about REALIZATION rather than about attempt." ;
+    sh:property [ sh:path sh:targetClass ; sh:minCount 1 ;
+        sh:message "A contract targets an activity class. A contract with no target validates nothing and is the exact failure mode this meta-shape exists to catch." ] ;
+    sh:property [ sh:path aps:definesCapability ; sh:minCount 1 ; sh:maxCount 1 ;
+        sh:message "A contract states which capability a conforming activity realizes." ] ;
+    sh:sparql [
+        sh:message "A realization contract must constrain all five parts: prov:used, prov:generated, prov:qualifiedAssociation, prov:endedAtTime, and a terminal completion state." ;
+        sh:select """
+            SELECT $this WHERE {
+              FILTER NOT EXISTS {
+                $this <http://www.w3.org/ns/shacl#property> ?u . ?u <http://www.w3.org/ns/shacl#path> <http://www.w3.org/ns/prov#used> .
+                $this <http://www.w3.org/ns/shacl#property> ?g . ?g <http://www.w3.org/ns/shacl#path> <http://www.w3.org/ns/prov#generated> .
+                $this <http://www.w3.org/ns/shacl#property> ?a . ?a <http://www.w3.org/ns/shacl#path> <http://www.w3.org/ns/prov#qualifiedAssociation> .
+                $this <http://www.w3.org/ns/shacl#property> ?e . ?e <http://www.w3.org/ns/shacl#path> <http://www.w3.org/ns/prov#endedAtTime> .
+                $this <http://www.w3.org/ns/shacl#property> ?c . ?c <http://www.w3.org/ns/shacl#path> <https://agenticprimitives.dev/ns/execution#completionState> .
+              }
+            }
+        """ ;
+    ] .
+
+# ── The one contract this substrate can enforce TODAY ───────────────────────
+#
+# The spec-329 routed member consultation is the substrate's only capability whose realizations
+# are already fully observable: the harness pre-reads a vault playbook (activation pins its
+# content hash), the turn consumes a signed ConsultRequestV1 and emits an answered-XOR-declined
+# ConsultAnswerV1 with the actor pinned to the member, and the org-side synthesis derives from
+# each contributing answer. Every clause below cites something the live code already produces.
+
+aps:MemberConsultationRealizationContract
+    a sh:NodeShape , aps:CapabilityRealizationContract ;
+    rdfs:label "MemberConsultationRealizationContract" ;
+    aps:definesCapability aps:MemberConsultationCapability ;
+    sh:targetClass apexec:MemberConsultationActivity ;
+    rdfs:comment "Realization contract for aps:MemberConsultationCapability — one member agent answering one routed consultation under its own playbook. A DECLINE IS A CONFORMING REALIZATION: the contract governs shape, not outcome, and buildConsultAnswer makes answered-xor-declined structural. Treating a decline as non-realization would create an incentive to answer outside one's documented positions, which is the opposite of what the consult path is for." ;
+
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apmsg:ConsultRequest ] ; sh:qualifiedMinCount 1 ;
+        sh:message "The turn must have consumed the ConsultRequestV1 it is answering." ] ;
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apguide:AgentSkillPackage ] ; sh:qualifiedMinCount 1 ;
+        sh:message "The turn must have consumed the member's playbook — guidance, never authority (ADR-0050)." ] ;
+    sh:property [ sh:path prov:generated ;
+        sh:qualifiedValueShape [ sh:class apmsg:ConsultAnswer ] ; sh:qualifiedMinCount 1 ; sh:qualifiedMaxCount 1 ] ;
+    sh:property [ sh:path prov:qualifiedAssociation ;
+        sh:qualifiedValueShape [
+            sh:class prov:Association ;
+            sh:property [ sh:path prov:agent ; sh:class apexec:AgentRuntime ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadRole ; sh:hasValue aprole:ConsultResponder ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadPlan ; sh:class apguide:AgentSkillPackage ; sh:minCount 1 ] ;
+        ] ;
+        sh:qualifiedMinCount 1 ;
+        sh:message "One qualified association carrying the runtime that bore responsibility, the capacity it acted in, and the plan that guided it." ] ;
+    sh:property [ sh:path apexec:usedPlanContentHash ; sh:minCount 1 ; sh:datatype xsd:string ;
+        sh:message "The playbook's content hash AT ACTIVATION. Without it the record cannot answer 'which executions must repeat after this playbook changed?' — and a demonstrated-capability signal computed over unpinned plans is unfalsifiable." ] ;
+    sh:property [ sh:path prov:endedAtTime ; sh:minCount 1 ; sh:datatype xsd:dateTime ] ;
+    sh:property [ sh:path apexec:completionState ; sh:minCount 1 ;
+        sh:in ( apexec:Answered apexec:Declined ) ] .
+
+aps:OrgConsultationSynthesisRealizationContract
+    a sh:NodeShape , aps:CapabilityRealizationContract ;
+    rdfs:label "OrgConsultationSynthesisRealizationContract" ;
+    aps:definesCapability aps:ConsultationRoutingCapability ;
+    sh:targetClass apexec:ConsultationSynthesisActivity ;
+    rdfs:comment "Realization contract for aps:ConsultationRoutingCapability — the ORG side: selecting the right members and synthesizing their attributed answers. Enforced today because spec 329 already produces every part: an eligibility set derived structurally, a ranked candidate set with evidence paths, and a synthesis post whose attribution names each contributing member. This is the capability whose demonstrated-signal the advisor catalog's routing quality actually rides on." ;
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apint:ConsultationIntent ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apmsg:ConsultAnswer ] ; sh:qualifiedMinCount 1 ;
+        sh:message "A synthesis with no contributing answer is not a realization of routing — it is the org agent talking to itself." ] ;
+    sh:property [ sh:path prov:generated ;
+        sh:qualifiedValueShape [ sh:class apmsg:MessageEvent ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path prov:qualifiedAssociation ;
+        sh:qualifiedValueShape [
+            sh:class prov:Association ;
+            sh:property [ sh:path prov:agent ; sh:class apexec:AgentRuntime ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadRole ; sh:hasValue aprole:ConsultRouter ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadPlan ; sh:class apguide:AgentSkillPackage ; sh:minCount 1 ] ;
+        ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path prov:endedAtTime ; sh:minCount 1 ; sh:datatype xsd:dateTime ] ;
+    sh:property [ sh:path apexec:completionState ; sh:minCount 1 ;
+        sh:in ( apexec:Answered apexec:Declined apexec:NoEligibleMember ) ] .
+
+# ═══ 4. The parameterised ADVISORY realization contract ═════════════════════════════════════════
+#
+# THE INSIGHT THIS SECTION TESTS (the owner's item-3 question, stated precisely):
+#   A spec-329 consult answer, where the answering member DECLARED the advisory capability the
+#   question was routed on, IS a realization of that advisory capability. The substrate already
+#   emits every part of the proof — the request, the pinned playbook, the attributed answer, the
+#   terminal state — for `aps:MemberConsultationCapability`. An advisory realization is the SAME
+#   activity graph plus ONE more edge: which advisory id the routing selected the responder on.
+#
+# WHY ONE PARAMETERISED CONTRACT, NOT 43 SHAPES. Every consult-realizable advisory capability has
+# the identical execution shape — they differ ONLY in the capability id on the routed-on edge.
+# Authoring 43 near-identical NodeShapes would be repetition mistaken for rigour (the owner's
+# words), and worse: 43 shapes drift, this one cannot. The capability id is DATA on the activity
+# (`apexec:routedOnCapability`), matched against DATA on the definition, by SPARQL — so the contract
+# is written once and every advisory definition that opts in is validated by it. This is the direct
+# application of architecture §5's "the contract is a shape over PROV": the shape is over the shape
+# of the graph, and the capability identity rides in the graph, not in the shape's name.
+#
+# ── WHY IT IS NOT ENFORCED TODAY, AND EXACTLY WHAT WOULD FLIP IT ────────────────────────────────
+# One edge is missing from live PROV: `apexec:routedOnCapability`. The org's `rankConsultCandidates`
+# ALREADY computes the routed-on id (the exact-match intersection of resolved need and declared ids,
+# `capabilityHits`), and then discards it into a free-text evidence line. Spec 330 W1 has to emit it
+# as a triple on the responder's turn. Until it does, this contract's target set is empty and it
+# would pass by vacuity — so every advisory definition keeps `contractStatus "deferred"`, and this
+# shape ships DEACTIVATED, as an executable specification of the one datum that is missing rather
+# than as a live check pretending to observe something it cannot. `sh:deactivated true` is the
+# honest state: the shape is correct, its input does not exist yet, and the test in §3's validation
+# path drives it against a FIXTURE that supplies the missing edge — so the day W1 emits the edge,
+# flipping `sh:deactivated` to false is the whole change, and the fixture proves it will validate.
+#
+# The evidence needed, in one line (this is the mandatory deferredContractRationale for all 43):
+#   a spec-330-W1 `apexec:routedOnCapability` edge on the member's consult turn, naming the
+#   advisory capability id the org's ranking selected the responder on.
+
+aps:AdvisoryConsultRealizationContract
+    a sh:NodeShape , aps:CapabilityRealizationContract ;
+    rdfs:label "AdvisoryConsultRealizationContract (parameterised — ONE shape, every consult-realizable adv:*)" ;
+    aps:definesCapability aps:AdvisoryConsultRealizationParameter ;
+    sh:targetClass apexec:MemberConsultationActivity ;
+    sh:deactivated true ;   # ← the one edit that flips it live, once W1 emits apexec:routedOnCapability
+    rdfs:comment "Parameterised realization contract for any advisory capability whose realization the consult path can carry. It is aps:MemberConsultationRealizationContract PLUS one clause: the turn must carry an apexec:routedOnCapability edge, and that capability must be one the responder actually declared (aps:declaresCapability). The capability identity is a PARAMETER read from the graph, not baked into 43 shape names. DEACTIVATED until spec 330 W1 emits the routed-on edge — see the header block for why an active-but-unobservable contract is the exact failure mode the catalog forbids." ;
+
+    # Everything aps:MemberConsultationRealizationContract requires, unchanged — an advisory
+    # realization is a member consultation, so it inherits the member consultation's whole shape.
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apmsg:ConsultRequest ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path prov:used ;
+        sh:qualifiedValueShape [ sh:class apguide:AgentSkillPackage ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path prov:generated ;
+        sh:qualifiedValueShape [ sh:class apmsg:ConsultAnswer ] ; sh:qualifiedMinCount 1 ; sh:qualifiedMaxCount 1 ] ;
+    sh:property [ sh:path prov:qualifiedAssociation ;
+        sh:qualifiedValueShape [
+            sh:class prov:Association ;
+            sh:property [ sh:path prov:agent ; sh:class apexec:AgentRuntime ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadRole ; sh:hasValue aprole:ConsultResponder ; sh:minCount 1 ] ;
+            sh:property [ sh:path prov:hadPlan ; sh:class apguide:AgentSkillPackage ; sh:minCount 1 ] ;
+        ] ; sh:qualifiedMinCount 1 ] ;
+    sh:property [ sh:path apexec:usedPlanContentHash ; sh:minCount 1 ; sh:datatype xsd:string ] ;
+    sh:property [ sh:path prov:endedAtTime ; sh:minCount 1 ; sh:datatype xsd:dateTime ] ;
+    sh:property [ sh:path apexec:completionState ; sh:minCount 1 ;
+        sh:in ( apexec:Answered apexec:Declined ) ] ;
+
+    # THE ONE ADDED CLAUSE (parts a): the turn names the advisory capability it was routed on.
+    sh:property [ sh:path apexec:routedOnCapability ; sh:minCount 1 ; sh:class aps:Capability ;
+        sh:message "An advisory realization must name the capability the org's routing selected the responder on — the parameter that says WHICH adv:* id this turn realizes. Without it the turn is a member consultation but not an advisory realization." ] ;
+
+    # THE ONE ADDED CLAUSE (part b): routed-on ⊆ declared. The realization only counts for a
+    # capability the responder actually put its name behind. This is the whole anti-inflation guard,
+    # in one FILTER: a member cannot earn a demonstrated edge for a capability it never declared, so
+    # routing an unrelated question at someone does not manufacture evidence they can do the thing.
+    sh:sparql [
+        sh:message "The routed-on advisory capability must be one the responding member DECLARED (aps:declaresCapability). Crediting a realization for an undeclared capability would let routing manufacture demonstrated-capability evidence the member never asserted — inverting the one signal that is supposed to be unfakeable." ;
+        sh:select """
+            SELECT $this ?cap WHERE {
+              $this <https://agenticprimitives.dev/ns/execution#routedOnCapability> ?cap .
+              $this <http://www.w3.org/ns/prov#qualifiedAssociation> ?assoc .
+              ?assoc <http://www.w3.org/ns/prov#agent> ?runtime .
+              ?runtime <http://www.w3.org/ns/prov#actedOnBehalfOf> ?member .
+              FILTER NOT EXISTS { ?member <https://agenticprimitives.dev/ns/skill#declaresCapability> ?cap }
+            }
+        """ ;
+    ] .
+
+# The PARAMETER capability the contract "defines". Not an advisory capability itself — it is the
+# substrate-owned identity that says "a conforming activity realizes WHICHEVER adv:* its routed-on
+# edge names". This keeps the meta-shape's `aps:definesCapability minCount 1` satisfied (a contract
+# states which capability a conforming activity realizes) while being honest that the specific
+# advisory id is late-bound from the graph. The 43 advisory definitions point their
+# aps:hasRealizationContract here ONCE W1 lands; today they stay deferred.
+aps:AdvisoryConsultRealizationParameter a aps:Capability ;
+    aps:capabilityId "aps:advisory-consult-realization-parameter" ;
+    apctx:ownedByContext apctx:SubstrateContext ;
+    rdfs:label "Advisory-consult realization parameter" ;
+    rdfs:comment "A substrate-owned meta-capability standing for 'the advisory capability this consult turn was routed on'. It exists so one parameterised contract can serve 43 advisory definitions without either baking 43 names into 43 shapes or leaving the meta-shape's definesCapability unsatisfied." .