queries.md — Relational Discovery Operations

Overview

This document defines the eight relational discovery operations that form the query layer of the Indigenous Relational Ontology System. Unlike conventional database queries that extract data from stores, these operations discover relationships — they traverse the relational web to reveal connections, lineages, balances, and accountabilities.

Every query operation in this system is itself a relational act. Running a query creates a record in the accountability trail, checks consent chains, and updates reciprocity balances. There are no "read-only" operations in a relational ontology — every act of knowing changes the relational field.

Design Principles

1. Discovery, not extraction: Queries reveal relationships; they do not extract objects from containers
2. Consent-gated: Every query checks consent before returning results
3. Context-preserving: Results always include full relational context
4. Accountability-logged: Every query is recorded in the accountability trail
5. Reciprocity-aware: Queries update reciprocity balances
6. Ceremony-bound: Queries require an active ceremony to execute

Query Architecture

``` ┌─────────────────┐ │ Active Ceremony │ └────────┬────────┘ │ ┌────────┴────────┐ │ Consent Check │ └────────┬────────┘ │ ┌─────────────────────┼─────────────────────┐ │ │ │ │ │ ┌────┴───┐ ┌──┴───┐ ┌──┴───┐ ┌──┴───┐ ┌───┴────┐ │ find │ │trace │ │verify│ │ map │ │gather │ │relations│ │lineage│ │consent│ │territory│ │stories │ └────┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └───┬────┘ │ │ │ │ │ ┌────┴───┐ ┌──┴───┐ ┌──┴───────────┴──────┐ │ │assess │ │check │ │ affirm │ │ │recipr. │ │account│ │ sovereignty │ │ └────┬───┘ └──┬───┘ └──────────┬───────────┘ │ │ │ │ │ └─────────┴────────────────┴──────────────────┘ │ ┌────────┴────────┐ │ Accountability │ │ Logging │ └─────────────────┘ ```

Operation 1: find_relations

Purpose

Discover relational connections between entities in the ontology. This operation traverses the kinship web to reveal how entities are connected through various types of relationships.

Wilson Paradigm Alignment

• Ontology: Revealing what exists by discovering relationships
• Epistemology: Knowing through relational discovery
• Medicine Wheel: East — Vision Pattern (seeing the relational field)

Signature

```python def find_relations( entity_id: str, relation_types: list[str] = None, depth: int = 1, direction: str = "all", include_dormant: bool = False, territory_filter: str = None, ceremony_id: str = None ) -> RelationalDiscoveryResult: """ Discover relational connections for a given entity.

Parameters
----------
entity_id : str
    The entity whose relations to discover.
relation_types : list[str], optional
    Filter by relationship types (e.g., ["knowledge_sharing", "mentorship"]).
    If None, returns all relation types.
depth : int, default 1
    How many relational layers to traverse.
    - depth=1: Direct relations only
    - depth=2: Relations of relations
    - depth=3+: Extended relational web (requires elevated consent)
direction : str, default "all"
    - "outgoing": Relations where entity is the source
    - "incoming": Relations where entity is the target
    - "all": Both directions
include_dormant : bool, default False
    Whether to include dormant/inactive relationships.
territory_filter : str, optional
    Limit discovery to a specific knowledge territory.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
RelationalDiscoveryResult
    Contains discovered relations with full relational context.

Raises
------
CeremonyRequired
    If no active ceremony is provided.
ConsentDenied
    If consent chain is incomplete for the requested scope.
TerritoryViolation
    If the query crosses territorial boundaries without permission.
"""

```

Consent Requirements

Result Structure

```python @dataclass class RelationalDiscoveryResult: query_id: str # Unique query identifier ceremony_id: str # Ceremony under which query was run entity_id: str # Entity that was queried timestamp: datetime # When the query was executed depth_reached: int # Actual depth traversed consent_status: str # Status of consent verification

relations: list[DiscoveredRelation]  # Discovered relationships

# Each relation includes full context
# DiscoveredRelation:
#   - relationship_id: str
#   - type: str
#   - connected_entity: str
#   - role_in_relationship: str
#   - health_status: str
#   - reciprocity_balance: float
#   - territory: str
#   - consent_status: str
#   - last_ceremony: datetime
#   - relational_context: dict

accountability_record: str      # ID of accountability log entry
reciprocity_impact: str         # How this query affects reciprocity

```

Example

```python

Within an active ceremony

result = onto.find_relations( entity_id="community_001", relation_types=["knowledge_sharing", "mentorship"], depth=2, territory_filter="water_governance", ceremony_id=ceremony.id )

for relation in result.relations: print(f"Connection: {relation.connected_entity}") print(f" Type: {relation.type}") print(f" Role: {relation.role_in_relationship}") print(f" Health: {relation.health_status}") print(f" Reciprocity: {relation.reciprocity_balance}") print(f" Territory: {relation.territory}") print() ```

Extraction Detection

find_relations monitors for:

• Bulk relational mapping: Attempting to map entire relational networks without proportional kinship → triggers volume anomaly alert
• Cross-territory scanning: Traversing multiple territories without specific purpose → triggers territory alert
• Depth escalation: Repeatedly increasing depth → triggers pattern alert

Operation 2: trace_lineage

Purpose

Trace the knowledge lineage of a specific piece of knowledge, story, or protocol — following its path from origin through all transmissions to the present. This operation reveals the relational history of knowledge, showing who received it from whom, under what ceremony, and with what consent.

Wilson Paradigm Alignment

• Epistemology: Understanding how knowledge traveled through relationships
• Methodology: Research as ceremony — honoring the knowledge path
• Medicine Wheel: North — Wisdom Pattern (elder knowledge and lineage)

Signature

```python def trace_lineage( knowledge_id: str, direction: str = "backward", max_generations: int = None, include_ceremonies: bool = True, include_consent_history: bool = True, ceremony_id: str = None ) -> LineageTraceResult: """ Trace the lineage of a piece of knowledge.

Parameters
----------
knowledge_id : str
    The knowledge item whose lineage to trace.
direction : str, default "backward"
    - "backward": Trace toward origin (who did this come from?)
    - "forward": Trace toward present (where did this go?)
    - "both": Trace in both directions
max_generations : int, optional
    Maximum number of generations to trace. None means trace to
    the earliest/latest available record.
include_ceremonies : bool, default True
    Include ceremony records at each transmission point.
include_consent_history : bool, default True
    Include consent status at each transmission point.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
LineageTraceResult
    Contains the full lineage path with relational context.

Raises
------
CeremonyRequired
    If no active ceremony is provided.
ConsentDenied
    If consent does not permit lineage tracing.
SacredKnowledge
    If knowledge is marked as sacred and lineage is restricted.
"""

```

Result Structure

```python @dataclass class LineageTraceResult: query_id: str ceremony_id: str knowledge_id: str timestamp: datetime direction: str generations_traced: int

lineage_path: list[LineageNode]
# Each LineageNode:
#   - holder: str (who held the knowledge)
#   - received_from: str (who they received it from)
#   - received_date: datetime
#   - ceremony_id: str (ceremony of transmission)
#   - consent_status: str (consent at time of transmission)
#   - territory: str (where transmission occurred)
#   - context: dict (full relational context)
#   - modifications: list (any changes to knowledge)
#   - generation: int (how many transmissions from origin)

origin: LineageNode             # Earliest known origin
current_holders: list[str]      # Current knowledge holders
sacred_segments: list[str]      # Parts of lineage that are restricted
accountability_record: str

```

Example

```python lineage = onto.trace_lineage( knowledge_id="water_ceremony_protocol_001", direction="backward", include_ceremonies=True, ceremony_id=ceremony.id )

print(f"Knowledge: {lineage.knowledge_id}") print(f"Generations traced: {lineage.generations_traced}") print(f"Origin holder: {lineage.origin.holder}") print()

for node in lineage.lineage_path: indent = " " * node.generation print(f"{indent}Generation {node.generation}: {node.holder}") print(f"{indent} Received from: {node.received_from}") print(f"{indent} Ceremony: {node.ceremony_id}") print(f"{indent} Territory: {node.territory}") ```

Sacred Knowledge Handling

When lineage tracing encounters sacred knowledge:

1. The trace stops at the sacred boundary
2. A [SACRED — RESTRICTED] marker is placed in the lineage
3. The ceremony holder is notified that sacred knowledge was encountered
4. An accountability record notes the sacred boundary encounter
5. No attempt is made to trace beyond the sacred boundary

Operation 3: verify_consent

Purpose

Verify that a complete, valid consent chain exists for a specific knowledge operation. This operation checks every layer of consent — from community governance down to individual knowledge keeper permissions — ensuring that the operation has proper relational authorization.

Wilson Paradigm Alignment

• Axiology: Consent embodies respect and relational responsibility
• Methodology: Consent verification is a methodological requirement
• Medicine Wheel: South — Heart Pattern (heart-centered permission)

Signature

```python def verify_consent( knowledge_id: str, requester_id: str, operation: str, purpose: str, territory_id: str = None, ceremony_id: str = None ) -> ConsentVerificationResult: """ Verify that a complete consent chain exists for an operation.

Parameters
----------
knowledge_id : str
    The knowledge being accessed.
requester_id : str
    Who is requesting access.
operation : str
    What operation is being performed (read, share, retell, etc.).
purpose : str
    Why the operation is being performed.
territory_id : str, optional
    Territory in which the operation occurs.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
ConsentVerificationResult
    Contains the verification result and chain details.
"""

```

Consent Chain Verification Logic

``` Step 1: Identify required consent layers → What type of knowledge is this? → What operation is being requested? → What territory does this knowledge belong to? → What governance structure applies?

Step 2: Check each consent layer → Community governance consent: Active? Not expired? Not revoked? → Elder/knowledge keeper consent: Active? Scope includes this operation? → Individual consent: Active? Purpose matches? → Territorial consent: Active? Territory boundaries respected?

Step 3: Verify chain completeness → Are all required layers present? → Are all layers currently active? → Do all layers cover the requested scope? → Are there any conditions not met?

Step 4: Return result → Chain complete: Operation may proceed → Chain incomplete: Operation blocked, missing consents identified → Chain expired: Operation blocked, renewal needed → Chain violated: Operation blocked, violation reported ```

Result Structure

```python @dataclass class ConsentVerificationResult: query_id: str ceremony_id: str knowledge_id: str requester_id: str operation: str timestamp: datetime

# Verification result
verified: bool                  # True if consent chain is complete
status: str                     # "complete", "incomplete", "expired", "violated"

# Chain details
chain: list[ConsentLayerStatus]
# Each ConsentLayerStatus:
#   - layer: str (e.g., "community", "elder", "individual")
#   - consent_id: str (reference to consent record)
#   - status: str ("active", "expired", "missing", "revoked")
#   - grantor: str (who granted this consent)
#   - scope_match: bool (does consent scope cover this operation?)
#   - expiry: datetime (when this consent expires)
#   - conditions: list (any conditions attached)
#   - conditions_met: bool (are all conditions met?)

missing_consents: list[str]     # Which consents are missing
expired_consents: list[str]     # Which consents have expired
recommendations: list[str]      # What to do to complete the chain
accountability_record: str

```

Example

```python result = onto.verify_consent( knowledge_id="water_ceremony_protocol_001", requester_id="researcher_002", operation="read", purpose="educational_research", territory_id="great_lakes_territory", ceremony_id=ceremony.id )

if result.verified: print("✅ Consent chain complete — operation may proceed") for layer in result.chain: print(f" ✅ {layer.layer}: {layer.status} (granted by {layer.grantor})") else: print(f"❌ Consent chain {result.status}") for missing in result.missing_consents: print(f" ❌ Missing: {missing}") for rec in result.recommendations: print(f" → {rec}") ```

Operation 4: map_territory

Purpose

Map the knowledge territories relevant to a query, including boundaries, governance structures, access policies, and neighboring territories. This operation reveals the territorial landscape of knowledge — where knowledge lives, who governs it, and what protocols apply.

Wilson Paradigm Alignment

• Ontology: Territory defines where knowledge exists
• Epistemology: Place-based knowledge requires place-based understanding
• Medicine Wheel: North — Integration Pattern (understanding the whole landscape)

Signature

```python def map_territory( query: str = None, territory_id: str = None, include_neighbors: bool = True, include_governance: bool = True, include_access_policy: bool = True, depth: int = 1, ceremony_id: str = None ) -> TerritoryMapResult: """ Map knowledge territories relevant to a query or territory.

Parameters
----------
query : str, optional
    A knowledge query to find relevant territories for.
territory_id : str, optional
    A specific territory to map. At least one of query or territory_id
    must be provided.
include_neighbors : bool, default True
    Include neighboring territories in the map.
include_governance : bool, default True
    Include governance structures for each territory.
include_access_policy : bool, default True
    Include access policies for each territory.
depth : int, default 1
    How many layers of neighboring territories to include.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
TerritoryMapResult
    Contains the territory map with governance and access details.
"""

```

Result Structure

```python @dataclass class TerritoryMapResult: query_id: str ceremony_id: str timestamp: datetime

territories: list[TerritoryDetail]
# Each TerritoryDetail:
#   - territory_id: str
#   - name: str
#   - type: str
#   - sovereign_nation: str
#   - governance_body: str
#   - access_policy: str
#   - knowledge_domains: list[str]
#   - language_boundaries: list[str]
#   - neighbors: list[str]
#   - health_status: str
#   - sovereignty_status: str

# Territorial relationships
shared_territories: list[dict]
disputed_territories: list[dict]
allied_territories: list[dict]

# Access summary
accessible_territories: list[str]
restricted_territories: list[str]
closed_territories: list[str]

accountability_record: str

```

Example

```python territory_map = onto.map_territory( query="traditional water governance", include_neighbors=True, include_governance=True, ceremony_id=ceremony.id )

for t in territory_map.territories: print(f"Territory: {t.name}") print(f" Sovereign: {t.sovereign_nation}") print(f" Access: {t.access_policy}") print(f" Domains: {', '.join(t.knowledge_domains)}") print(f" Health: {t.health_status}") print()

print("Accessible territories:") for tid in territory_map.accessible_territories: print(f" ✅ {tid}") print("Restricted territories:") for tid in territory_map.restricted_territories: print(f" 🔒 {tid}") ```

Operation 5: gather_stories

Purpose

Gather stories related to a topic, entity, or territory — preserving their full relational context including teller, place, time, purpose, and lineage. This operation treats stories as living relational beings, not as data to be retrieved.

Wilson Paradigm Alignment

• Epistemology: Stories are ways of knowing
• Methodology: Gathering stories is a ceremonial act
• Medicine Wheel: East — Illumination Pattern (stories illuminate understanding)

Signature

```python def gather_stories( topic: str = None, territory_id: str = None, teller_id: str = None, story_type: str = None, season: str = None, include_related: bool = True, max_stories: int = 10, ceremony_id: str = None ) -> StoryGatheringResult: """ Gather stories related to a topic, territory, or teller.

Parameters
----------
topic : str, optional
    Topic to gather stories about.
territory_id : str, optional
    Gather stories from a specific territory.
teller_id : str, optional
    Gather stories from a specific teller.
story_type : str, optional
    Filter by story type (teaching, healing, origin, etc.).
season : str, optional
    Filter by seasonal stories.
include_related : bool, default True
    Include related/connected stories.
max_stories : int, default 10
    Maximum number of stories to gather.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
StoryGatheringResult
    Contains gathered stories with full relational context.

Notes
-----
Some stories may be seasonally restricted. If a story is
restricted for the current season, a placeholder will be
returned indicating its existence without its content.
Sacred stories will never be returned — only a marker
indicating that sacred knowledge exists in this area.
"""

```

Result Structure

```python @dataclass class StoryGatheringResult: query_id: str ceremony_id: str timestamp: datetime season: str # Current season (affects availability)

stories: list[GatheredStory]
# Each GatheredStory:
#   - story_id: str
#   - title: str
#   - type: str
#   - teller: str
#   - teller_authority: str
#   - lineage: list[str]
#   - territory: str
#   - place: str
#   - original_language: str
#   - season_context: str
#   - purpose: str
#   - content: str (if permitted) or "[RESTRICTED]"
#   - teachings: list[str]
#   - related_stories: list[str]
#   - permissions: dict

restricted_count: int           # Number of stories not returned
sacred_count: int               # Number of sacred stories (existence only)
seasonal_count: int             # Number of seasonally restricted stories
total_available: int            # Total stories matching query

accountability_record: str
reciprocity_impact: str

```

Example

```python stories = onto.gather_stories( topic="water governance", territory_id="great_lakes_territory", story_type="teaching_story", ceremony_id=ceremony.id )

print(f"Found {len(stories.stories)} stories") print(f"({stories.restricted_count} restricted, {stories.sacred_count} sacred)") print()

for story in stories.stories: print(f"📖 {story.title}") print(f" Teller: {story.teller} ({story.teller_authority})") print(f" Territory: {story.territory}") print(f" Language: {story.original_language}") if story.content != "[RESTRICTED]": print(f" Teachings: {', '.join(story.teachings)}") else: print(f" [Content restricted — ceremony or consent needed]") print() ```

Operation 6: assess_reciprocity

Purpose

Assess the reciprocity balance for a specific relationship, entity, or across all relationships within a ceremony. This operation reveals whether knowledge exchange is balanced, identifying imbalances that need attention and patterns that may indicate extraction.

Wilson Paradigm Alignment

• Axiology: Reciprocity is a core relational value
• Methodology: Assessing balance is a methodological step
• Medicine Wheel: South — Growth Pattern (nurturing balanced exchange)

Signature

```python def assess_reciprocity( relationship_id: str = None, entity_id: str = None, scope: str = "specific", timeframe: str = None, include_history: bool = True, ceremony_id: str = None ) -> ReciprocityAssessmentResult: """ Assess reciprocity balance for a relationship or entity.

Parameters
----------
relationship_id : str, optional
    Assess reciprocity for a specific relationship.
entity_id : str, optional
    Assess all reciprocity balances for an entity.
    At least one of relationship_id or entity_id must be provided.
scope : str, default "specific"
    - "specific": Assess one relationship
    - "all": Assess all relationships for the entity
    - "territory": Assess all reciprocity within a territory
timeframe : str, optional
    Limit assessment to a specific timeframe (e.g., "last_year").
include_history : bool, default True
    Include exchange history in the result.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
ReciprocityAssessmentResult
    Contains the reciprocity assessment with detailed balance info.
"""

```

Result Structure

```python @dataclass class ReciprocityAssessmentResult: query_id: str ceremony_id: str timestamp: datetime

assessments: list[ReciprocityBalance]
# Each ReciprocityBalance:
#   - relationship_id: str
#   - parties: list[str]
#   - status: str ("balanced", "slight_imbalance", "imbalanced",
#                   "critical", "exploitative")
#   - given: list[ExchangeRecord]
#   - received: list[ExchangeRecord]
#   - balance_ratio: float (-1.0 to 1.0)
#   - assessment_narrative: str
#   - recommendations: list[str]
#   - rebalancing_actions: list[str]

overall_status: str             # Aggregate status across all assessed
extraction_alerts: list[str]    # Any extraction patterns detected
recommendations: list[str]      # Overall recommendations
accountability_record: str

```

Example

```python assessment = onto.assess_reciprocity( entity_id="researcher_002", scope="all", timeframe="last_year", ceremony_id=ceremony.id )

print(f"Overall reciprocity status: {assessment.overall_status}") print()

for balance in assessment.assessments: status_icon = { "balanced": "✅", "slight_imbalance": "⚖️", "imbalanced": "⚠️", "critical": "🔴", "exploitative": "🚨" }.get(balance.status, "❓")

print(f"{status_icon} {balance.relationship_id}: {balance.status}")
print(f"   Given: {len(balance.given)} exchanges")
print(f"   Received: {len(balance.received)} exchanges")
print(f"   Balance: {balance.balance_ratio:.2f}")
if balance.recommendations:
    for rec in balance.recommendations:
        print(f"   → {rec}")
print()

if assessment.extraction_alerts: print("🚨 EXTRACTION ALERTS:") for alert in assessment.extraction_alerts: print(f" {alert}") ```

Operation 7: check_accountability

Purpose

Check the accountability status for an entity, ceremony, or relationship — reviewing obligations, compliance, violations, and audit trail. This operation is the relational equivalent of an audit, but framed as a check-in on relational responsibilities rather than a compliance review.

Wilson Paradigm Alignment

• Axiology: Relational accountability is the highest value
• Methodology: Accountability checking is a methodological requirement
• Medicine Wheel: West — Reflection Pattern (examining responsibilities)

Signature

```python def check_accountability( entity_id: str = None, ceremony_id_filter: str = None, relationship_id: str = None, scope: str = "entity", include_violations: bool = True, include_audit_trail: bool = True, timeframe: str = None, ceremony_id: str = None ) -> AccountabilityCheckResult: """ Check accountability status for an entity, ceremony, or relationship.

Parameters
----------
entity_id : str, optional
    Check accountability for a specific entity.
ceremony_id_filter : str, optional
    Check accountability for a specific ceremony.
relationship_id : str, optional
    Check accountability for a specific relationship.
scope : str, default "entity"
    - "entity": All obligations for an entity
    - "ceremony": All obligations from a ceremony
    - "relationship": All obligations in a relationship
    - "system": System-wide accountability check
include_violations : bool, default True
    Include violation records in the result.
include_audit_trail : bool, default True
    Include full audit trail.
timeframe : str, optional
    Limit check to a specific timeframe.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
AccountabilityCheckResult
    Contains accountability status with obligations and violations.
"""

```

Result Structure

```python @dataclass class AccountabilityCheckResult: query_id: str ceremony_id: str timestamp: datetime scope: str

obligations: list[ObligationStatus]
# Each ObligationStatus:
#   - obligation_id: str
#   - description: str
#   - source: str (where obligation comes from)
#   - responsible_entity: str
#   - deadline: datetime
#   - status: str ("pending", "in_progress", "fulfilled",
#                   "overdue", "violated", "waived")
#   - progress_notes: list[str]
#   - last_updated: datetime

violations: list[ViolationRecord]
# Each ViolationRecord:
#   - violation_id: str
#   - date: datetime
#   - description: str
#   - severity: str
#   - response: str
#   - resolution_status: str

audit_trail: list[AuditEntry]
# Each AuditEntry:
#   - timestamp: datetime
#   - action: str
#   - actor: str
#   - details: str

overall_status: str             # "compliant", "attention_needed",
                                # "violations_detected", "critical"
overdue_count: int
violated_count: int
fulfilled_count: int
pending_count: int
recommendations: list[str]
accountability_record: str

```

Example

```python check = onto.check_accountability( entity_id="researcher_002", scope="entity", include_violations=True, ceremony_id=ceremony.id )

print(f"Accountability status: {check.overall_status}") print(f" Fulfilled: {check.fulfilled_count}") print(f" Pending: {check.pending_count}") print(f" Overdue: {check.overdue_count}") print(f" Violated: {check.violated_count}") print()

for obligation in check.obligations: status_icon = { "fulfilled": "✅", "pending": "⏳", "in_progress": "🔄", "overdue": "⚠️", "violated": "🚨" }.get(obligation.status, "❓") print(f"{status_icon} {obligation.description}") print(f" Source: {obligation.source}") print(f" Deadline: {obligation.deadline}") print(f" Status: {obligation.status}") print()

if check.violations: print("🚨 VIOLATIONS:") for v in check.violations: print(f" [{v.severity}] {v.description}") print(f" Status: {v.resolution_status}") ```

Operation 8: affirm_sovereignty

Purpose

Affirm and verify the sovereignty status of knowledge, data, or territory. This operation checks that sovereignty assertions are in place, OCAP/CARE principles are being honored, and no sovereignty violations have occurred. It is both a verification and an affirmation — running this query strengthens the sovereignty record.

Wilson Paradigm Alignment

• Ontology: Sovereignty is inherent to Indigenous nationhood
• Axiology: Self-determination is a core value
• Medicine Wheel: North — Completion Pattern (ensuring the circle is protected)

Signature

```python def affirm_sovereignty( entity_id: str = None, territory_id: str = None, knowledge_id: str = None, scope: str = "territory", include_threats: bool = True, include_ocap_audit: bool = True, include_care_audit: bool = True, ceremony_id: str = None ) -> SovereigntyAffirmationResult: """ Affirm and verify sovereignty status.

Parameters
----------
entity_id : str, optional
    Affirm sovereignty for a specific sovereign entity.
territory_id : str, optional
    Affirm sovereignty for a specific territory.
knowledge_id : str, optional
    Affirm sovereignty for a specific knowledge item.
scope : str, default "territory"
    - "entity": Sovereignty of a sovereign nation
    - "territory": Sovereignty over a knowledge territory
    - "knowledge": Sovereignty over specific knowledge
    - "system": System-wide sovereignty audit
include_threats : bool, default True
    Include current threats to sovereignty.
include_ocap_audit : bool, default True
    Include OCAP compliance audit.
include_care_audit : bool, default True
    Include CARE compliance audit.
ceremony_id : str, required
    Active ceremony under which this query operates.

Returns
-------
SovereigntyAffirmationResult
    Contains sovereignty affirmation with audit details.
"""

```

Result Structure

```python @dataclass class SovereigntyAffirmationResult: query_id: str ceremony_id: str timestamp: datetime scope: str

sovereignty_status: str         # "affirmed", "threatened", "violated", "restored"
sovereign_entity: str
territory: str

# OCAP Audit
ocap_audit: dict
# {
#   "ownership": {"status": str, "details": str},
#   "control": {"status": str, "details": str},
#   "access": {"status": str, "details": str},
#   "possession": {"status": str, "details": str},
#   "overall": str  # "compliant", "partial", "non-compliant"
# }

# CARE Audit
care_audit: dict
# {
#   "collective_benefit": {"status": str, "details": str},
#   "authority": {"status": str, "details": str},
#   "responsibility": {"status": str, "details": str},
#   "ethics": {"status": str, "details": str},
#   "overall": str
# }

threats: list[SovereigntyThreat]
# Each SovereigntyThreat:
#   - threat_id: str
#   - type: str
#   - description: str
#   - severity: str
#   - source: str
#   - recommended_response: str

violations: list[dict]
enforcement_actions: list[dict]
recommendations: list[str]
accountability_record: str

# Affirmation strengthens the sovereignty record
affirmation_strength: float     # How much this affirmation strengthens
                                # the sovereignty record (0.0 to 1.0)

```

Example

```python affirmation = onto.affirm_sovereignty( territory_id="great_lakes_territory", scope="territory", include_threats=True, include_ocap_audit=True, include_care_audit=True, ceremony_id=ceremony.id )

print(f"Sovereignty status: {affirmation.sovereignty_status}") print(f"Sovereign entity: {affirmation.sovereign_entity}") print()

print("OCAP Compliance:") for principle, status in affirmation.ocap_audit.items(): if principle != "overall": icon = "✅" if status["status"] == "compliant" else "⚠️" print(f" {icon} {principle}: {status['status']}") print(f" Overall: {affirmation.ocap_audit['overall']}") print()

print("CARE Compliance:") for principle, status in affirmation.care_audit.items(): if principle != "overall": icon = "✅" if status["status"] == "compliant" else "⚠️" print(f" {icon} {principle}: {status['status']}") print(f" Overall: {affirmation.care_audit['overall']}") print()

if affirmation.threats: print("⚠️ Current Threats:") for threat in affirmation.threats: print(f" [{threat.severity}] {threat.description}") print(f" Recommended: {threat.recommended_response}")

print(f"\nAffirmation strength: {affirmation.affirmation_strength:.2f}") print("(This affirmation has been recorded in the sovereignty ledger)") ```

Cross-Operation Workflows

Workflow 1: Complete Knowledge Discovery

```python

Full relational discovery workflow

with ceremony: # 1. Map the territory territory = onto.map_territory(query="water governance", ceremony_id=cid)

# 2. Verify consent for accessible territories
for t in territory.accessible_territories:
    consent = onto.verify_consent(
        knowledge_id=f"territory:{t}",
        requester_id="researcher_002",
        operation="discover",
        purpose="educational_research",
        ceremony_id=cid
    )
    if consent.verified:
        # 3. Find relations within consented territory
        relations = onto.find_relations(
            entity_id="researcher_002",
            territory_filter=t,
            ceremony_id=cid
        )

        # 4. Gather stories from the territory
        stories = onto.gather_stories(
            territory_id=t,
            ceremony_id=cid
        )

        # 5. Trace lineage of interesting knowledge
        for story in stories.stories:
            lineage = onto.trace_lineage(
                knowledge_id=story.story_id,
                ceremony_id=cid
            )

# 6. Assess reciprocity after discovery
reciprocity = onto.assess_reciprocity(
    entity_id="researcher_002",
    scope="all",
    ceremony_id=cid
)

# 7. Check accountability
accountability = onto.check_accountability(
    entity_id="researcher_002",
    ceremony_id=cid
)

# 8. Affirm sovereignty
sovereignty = onto.affirm_sovereignty(
    territory_id="great_lakes_territory",
    ceremony_id=cid
)

```

Workflow 2: Extraction Detection Sweep

```python

System-wide extraction detection

with ceremony: # Check all relationships for reciprocity imbalance reciprocity = onto.assess_reciprocity( scope="system", timeframe="last_quarter", ceremony_id=cid )

# Check all entities for accountability violations
accountability = onto.check_accountability(
    scope="system",
    timeframe="last_quarter",
    ceremony_id=cid
)

# Affirm sovereignty across all territories
sovereignty = onto.affirm_sovereignty(
    scope="system",
    ceremony_id=cid
)

# Compile extraction report
extraction_alerts = []
extraction_alerts.extend(reciprocity.extraction_alerts)
for v in accountability.violations:
    if v.severity in ("major", "critical"):
        extraction_alerts.append(f"Accountability: {v.description}")
for t in sovereignty.threats:
    extraction_alerts.append(f"Sovereignty: {t.description}")

print(f"Extraction detection complete: {len(extraction_alerts)} alerts")

```

Operation Security Model

Consent-Gated Access

Every operation follows this security model:

``` Request → Ceremony Check → Consent Verification → Territory Check → Reciprocity Check → Execute → Accountability Log → Result ```

No shortcuts. No bypasses. No admin overrides for consent.

Rate Limiting (Relational, Not Technical)

Operations are rate-limited not by requests-per-second but by relational appropriateness:

• Ceremonies have a natural pace — you cannot rush relationship
• Consent verification takes the time it takes
• Reciprocity must be maintained — you cannot take faster than you give
• Accountability review happens at community pace

Audit Completeness

Every query operation generates:

1. An accountability log entry
2. A consent verification record
3. A reciprocity balance update
4. A territory access record

These records are immutable after ceremony closure.

References

• Wilson, S. (2008). Research Is Ceremony. Fernwood Publishing.
• Kovach, M. (2009). Indigenous Methodologies. University of Toronto Press.
• Smith, L. T. (2012). Decolonizing Methodologies. Zed Books.
• FNIGC. (2014). OCAP™ Principles.
• Carroll, S. R., et al. (2020). "CARE Principles." Data Science Journal.