# @medicine-wheel/relational-query

Query builder, graph traversal, and accountability audit for the Medicine Wheel relational web. Protocol-aware: respects ceremony boundaries and OCAP® compliance during traversal.

> [!WARNING]
> **Experimental alpha.** Part of the Medicine Wheel Developer Suite, which is
> under active development. APIs change between patch versions and all packages
> move in lockstep — pin exact versions. See
> [ALPHA.md](https://github.com/jgwill/medicine-wheel/blob/main/ALPHA.md).

## Install

```bash
npm install @medicine-wheel/relational-query
```

## Modules

### Query Builder
Filter, sort, and paginate nodes and edges.

```ts
import { filterNodes, sortNodes, paginate } from '@medicine-wheel/relational-query';

const elders = filterNodes(nodes, { type: 'human', direction: 'north' });
const sorted = sortNodes(elders, { field: 'name', order: 'asc' });
const page = paginate(sorted, { offset: 0, limit: 10 });
```

### Traversal
Context-aware graph traversal with ceremony and OCAP boundaries.

```ts
import { traverse, shortestPath, neighborhood } from '@medicine-wheel/relational-query';

const result = traverse('node-id', nodes, edges, relations, {
  maxDepth: 3,
  respectCeremonyBoundaries: true,
  ocapOnly: true,
});

const path = shortestPath('from-id', 'to-id', nodes, edges);
const neighbors = neighborhood('node-id', nodes, edges, 2);
```

### Protocol Guards (avoidance protocols)
Conditional edge filters evaluated **before** a crossing. A guard does not veto —
when a boundary is reached it returns an escalation directive (delegate to a
custodian). The legacy `respectCeremonyBoundaries`/`ocapOnly` booleans are now
built-in guards; `avoidanceProtocolGuard` reads a relation's `context`.

```ts
import { traverse, avoidanceProtocolGuard } from '@medicine-wheel/relational-query';

const result = traverse('node-id', nodes, edges, relations, {
  maxDepth: 3,
  guards: [avoidanceProtocolGuard],
  context: { identity: 'agent-mia', ceremonyState: 'open' },
});

// Crossings a guard refused, surfaced for delegation:
result.escalations; // [{ fromId, toId, guard, reason, escalateTo }]
```

### RDF → Flat Kinship-Graph Migration
Map RDF triples onto co-equal nodes + named relations. `rdfs:subClassOf` and
`rdf:type` flatten to the `co-emerges-with` edge — never a re-introduced hierarchy.

```ts
import { rdfToKinshipGraph, kinshipGraphToCypher, kinshipGraphToJsonl } from '@medicine-wheel/relational-query';

const graph = rdfToKinshipGraph(triples, { source: 'treaty-dataset' });
const cypher = kinshipGraphToCypher(graph); // MERGE statements for KuzuDB
const jsonl = kinshipGraphToJsonl(graph);   // newline-delimited node/relation records
```

### Accountability Audit
Relational health metrics and OCAP® compliance reports.

```ts
import { auditAccountability, relationsNeedingAttention } from '@medicine-wheel/relational-query';

const report = auditAccountability(nodes, edges, relations);
console.log(report.averageWilsonAlignment);
console.log(report.recommendations);

const needsWork = relationsNeedingAttention(relations, 0.5);
```

## Peer dependency

Requires `@medicine-wheel/ontology-core` ^0.1.0.

## License

MIT