@agenticprimitives/ontology 1.0.0-alpha.17 → 1.0.0-alpha.19

package/README.md

@@ -21,6 +21,10 @@ src/index.ts     typed IRI constants + artifact paths
 
 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
 
 ```ts

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." .

package/cbox/consultation-shapes.shacl.ttl

@@ -0,0 +1,85 @@
+# C-box — SHACL shapes for the routed-consultation artifacts (spec 329 §6).
+# Shapes for the two DURABLE artifacts only: the ConsultationIntent (the org's routing
+# description, tbox/intents.ttl) and the ConsultAnswer (the member agent's structured
+# answer, tbox/messaging.ttl). Projections — pending-routing rings, candidate rankings —
+# get NO classes and therefore NO shapes: a derived view must never be mistaken for a fact.
+# Like the messaging shapes, these are declared here and ENFORCED by fabric's TS validators
+# (golden-vectored); they are graph/documentation shapes, never authority checks.
+
+@prefix ap:     <https://agenticprimitives.dev/ns/core#> .
+@prefix apint:  <https://agenticprimitives.dev/ns/intent#> .
+@prefix apmsg:  <https://agenticprimitives.dev/ns/messaging#> .
+@prefix apful:  <https://agenticprimitives.dev/ns/fulfillment#> .
+@prefix sh:     <http://www.w3.org/ns/shacl#> .
+@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
+
+apint:ConsultationIntentShape a sh:NodeShape ;
+  rdfs:label "ConsultationIntent shape" ;
+  sh:targetClass apint:ConsultationIntent ;
+  # A consultation is always the org RECEIVING an answer — exactly one direction, fixed.
+  sh:property [
+    sh:path apint:direction ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:hasValue "receive" ;
+    sh:message "ConsultationIntent.direction must be exactly 'receive'."
+  ] ;
+  sh:property [
+    sh:path apint:expressedBy ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:class ap:Agent ;
+    sh:message "ConsultationIntent must be expressed by exactly one org agent."
+  ] ;
+  # Depth-1 by construction (spec 329 §4.1): ONE member agent per consultation.
+  sh:property [
+    sh:path apint:addressedTo ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:class ap:Agent ;
+    sh:message "ConsultationIntent must be addressed to exactly one member agent."
+  ] ;
+  # The timeout/topic constraint set is REQUIRED — an unbounded consult is not expressible.
+  sh:property [
+    sh:path apint:hasConstraintSet ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "ConsultationIntent must carry exactly one constraint set (timeout + topic scope)."
+  ] ;
+  sh:property [
+    sh:path apint:status ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:in ( "drafted" "expressed" "fulfilled" "abandoned" ) ;
+    sh:message "ConsultationIntent.status must be one of drafted|expressed|fulfilled|abandoned (spine SKOS lifecycle)."
+  ] .
+
+apmsg:ConsultAnswerShape a sh:NodeShape ;
+  rdfs:label "ConsultAnswer shape" ;
+  sh:targetClass apmsg:ConsultAnswer ;
+  # Agent-authored by construction: exactly one actor (the member SA the answer is attributed to).
+  sh:property [
+    sh:path apmsg:actingAgent ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:class ap:Agent ;
+    sh:message "ConsultAnswer must carry exactly one acting agent (the member SA)."
+  ] ;
+  # Body integrity: the artifact's bodyHash binding — REUSED from the fulfillment layer
+  # (the answer rides the a2a task Artifact, whose runtime computes + records apful:bodyHash).
+  sh:property [
+    sh:path apful:bodyHash ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:datatype xsd:string ;
+    sh:pattern "^0x[0-9a-fA-F]{64}$" ;
+    sh:message "ConsultAnswer must carry exactly one apful:bodyHash bound to the artifact body."
+  ] ;
+  # answered XOR declined — a consult terminal is always exactly one of the two.
+  sh:xone (
+    [ sh:property [ sh:path apmsg:answerText ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:string ; sh:minLength 1 ] ;
+      sh:property [ sh:path apmsg:declined ; sh:maxCount 0 ] ]
+    [ sh:property [ sh:path apmsg:declined ; sh:minCount 1 ; sh:maxCount 1 ; sh:hasValue true ] ;
+      sh:property [ sh:path apmsg:answerText ; sh:maxCount 0 ] ]
+  ) .

package/cbox/discovery-graph-shapes.shacl.ttl

@@ -232,3 +232,53 @@ apsec:ExposureFindingShape a sh:NodeShape ;
     sh:class apdisc:EvidencePath ;
     sh:message "ExposureFinding must cite an evidence path."
   ] .
+
+# ── Offering (spec 286) ────────────────────────────────────────────────────────────────────────
+# `apdisc:OfferingShape` has been named by the indexer (`SHAPE.Offering`, recorded as the facet's
+# shapeIri on every crawl) since spec 286, and has never existed. This is it.
+#
+# WHAT IT CONSTRAINS, AND WHAT IT DELIBERATELY DOES NOT. Everything an Offering says about ITSELF —
+# effect, exposure, family, status, version, name, blurb — is the host's own claim about its own
+# service, so there is no codelist this repo could impose that would be more than a guess, and a
+# pinned value space would make an unrecognised value indistinguishable from an absent one. Those
+# properties are therefore unconstrained here ON PURPOSE.
+#
+# What IS constrained is the part the substrate itself produces and consumes: identity (skillId,
+# ofAgent), the two-valued lexical space the MCP reads with `=== 'true'`, and the three provenance
+# properties without which a crawled assertion cannot be aged, diffed or challenged.
+apdisc:OfferingShape a sh:NodeShape ;
+  rdfs:label "Offering shape" ;
+  sh:targetClass apdisc:Offering ;
+  sh:property [
+    sh:path apdisc:skillId ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:string ;
+    sh:message "Offering must carry exactly one skillId — it is the offering's identity component (the A-box IRI derives from it), and the projector drops any card entry without one."
+  ] ;
+  sh:property [
+    sh:path apdisc:ofAgent ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:class ap:Agent ;
+    sh:message "Offering must back-link to exactly one Agent. An offering advertising two agents' services is two offerings, and a single-tenant crawl already requires the card's self-reported agentId to equal the SA being crawled."
+  ] ;
+  sh:property [
+    sh:path apdisc:hasInputSchema ;
+    sh:maxCount 1 ; sh:in ( "true" "false" ) ;
+    sh:message "Offering.hasInputSchema, if present, is the lexical string 'true' or 'false'. The MCP reads it as `value === 'true'`, so ANY third value reads as false — a silent miss, which is exactly what ADR-0013 forbids. The set is pinned here rather than in the T-box because it is a fact about the live serialization, not about the concept."
+  ] ;
+  # ── Provenance of the crawl. A host-asserted fact with no observation point and no observation
+  #    time is a rumour with a subject IRI; these three are what make an Offering evidence.
+  sh:property [
+    sh:path apdisc:sourceEndpoint ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:string ;
+    sh:message "Offering must record the endpoint it was crawled from. Without it, 'who asserted this?' has no answer."
+  ] ;
+  sh:property [
+    sh:path apdisc:observedAt ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:integer ;
+    sh:message "Offering must record WHEN it was observed, in unix seconds (xsd:integer — the projector writes a bare Turtle integer). Without it nothing can decay, and a 2019 advertisement ranks as fresh."
+  ] ;
+  sh:property [
+    sh:path apdisc:cardDigest ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:string ;
+    sh:pattern "^sha256:[0-9a-f]{64}$" ;
+    sh:message "Offering.cardDigest must be sha256:<64 lowercase hex> over the raw card body. It is what makes 'which advertisements must be re-examined now this host's card changed?' answerable without having stored the card — the same role a pinned playbook content hash plays in a realization contract."
+  ] .