@medicine-wheel/importance-unit 0.2.2

package/README.md

@@ -0,0 +1,105 @@
+# @medicine-wheel/importance-unit
+
+The ImportanceUnit is the relational unit of knowledge in Wilson's epistemology — a relationally-accountable piece of meaning that carries epistemic weight, source dimensions, accountability links, and circle depth tracking.
+
+## Overview
+
+In Wilson's framework, not all knowledge is equal. Dream-state and embodied knowledge may carry more epistemic authority than rational analysis. ImportanceUnits make this explicit.
+
+### What it provides
+
+| Module | Description |
+|--------|-------------|
+| `types` | TypeScript types for ImportanceUnit, AccountabilityLink, CircleRefinement, and related structures |
+| `schemas` | Zod validation schemas for runtime data integrity |
+| `unit` | Core CRUD: `createUnit()`, `updateUnit()`, `circleBack()`, `archive()` |
+| `epistemic-weight` | Weight computation: `computeWeight()`, `adjustForSource()`, `adjustForDepth()` |
+| `accountability` | Link management: `linkAccountability()`, `resolveLinks()`, `findGaps()` |
+| `circle-tracking` | Spiral tracking: `incrementCircle()`, `recordRefinement()`, `detectDeepening()`, `detectStagnation()` |
+
+## Installation
+
+```bash
+npm install @medicine-wheel/importance-unit
+```
+
+Or link locally:
+```bash
+npm link ../medicine-wheel/src/importance-unit
+```
+
+## Usage
+
+```typescript
+import {
+  // Types
+  type ImportanceUnit, type EpistemicSource, type AccountabilityLink,
+
+  // CRUD
+  createUnit, circleBack, archive,
+
+  // Weight
+  computeWeight, BASE_WEIGHTS,
+
+  // Accountability
+  linkAccountability, findGaps,
+
+  // Circle tracking
+  incrementCircle, detectDeepening, detectStagnation,
+
+  // Schemas
+  ImportanceUnitSchema,
+} from '@medicine-wheel/importance-unit';
+
+// Create a new unit from dream-state knowing
+const unit = createUnit({
+  direction: 'east',
+  source: 'dream',
+  summary: 'The river teaches patience through its refusal to hurry',
+  createdBy: 'firekeeper-agent',
+  axiologicalPillar: 'epistemology',
+});
+
+// unit.epistemicWeight === 0.85 (dream-state base)
+// unit.circleDepth === 1
+
+// Circle back with a refinement
+const deepened = circleBack(unit, 'Patience is not waiting — it is attending');
+// deepened.circleDepth === 2
+// deepened.epistemicWeight > 0.85 (depth bonus applied)
+```
+
+## Epistemic Weight Model
+
+| Source | Base Weight | Rationale |
+|--------|-------------|-----------|
+| `dream` | 0.85 | Liminal/spirit-state knowing has highest authority |
+| `land` | 0.75 | Place-grounded/embodied knowing |
+| `vision` | 0.65 | Intentional/architectural knowing |
+| `code` | 0.50 | Technical/implementation knowing |
+
+Weight increases with `circleDepth` using diminishing returns (logarithmic scaling). The first return yields more insight than the tenth, though all returns matter. Weight never exceeds 1.0.
+
+## Key Concepts
+
+### Circle Depth
+
+Repetition is ceremony and deepening, not redundancy. Each time a topic is revisited (`circleBack()`), the circle depth increments and a refinement is recorded capturing "the subtle difference between the 3rd and 4th circling."
+
+### Accountability Links
+
+Every ImportanceUnit must be accountable to something. Links carry responsibility, not just reference. The `findGaps()` function identifies relationally isolated units.
+
+### Ceremony State
+
+Tracks progression through the four directions. When all four quadrants have been visited, the circle is complete and the unit becomes eligible for archival.
+
+## Dependencies
+
+- `@medicine-wheel/ontology-core` — Foundational types (`DirectionName`, etc.)
+- `zod` — Runtime validation
+
+## License
+
+MIT — IAIP Collaborative, Shawinigan, QC
+

package/dist/accountability.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @medicine-wheel/importance-unit — Accountability Link Management
+ *
+ * Manages the relational strings connecting ImportanceUnits to what
+ * they are accountable to. The question is "To what is this accountable?"
+ * not "What is this about?"
+ *
+ * Wilson's relational accountability requires that every piece of
+ * knowledge be tethered to its responsibilities.
+ */
+import type { ImportanceUnit, AccountabilityLink, AccountabilityLinkType } from './types.js';
+/**
+ * Result of analyzing accountability gaps in a set of ImportanceUnits.
+ */
+export interface AccountabilityGap {
+    /** ID of the unit with a gap */
+    unitId: string;
+    /** Description of the gap */
+    description: string;
+    /** Suggested link type to address the gap */
+    suggestedLinkType: AccountabilityLinkType;
+}
+/**
+ * Add an accountability link to an ImportanceUnit.
+ *
+ * Returns a new unit with the link appended. Does not add
+ * duplicate links (same targetId and relationType).
+ *
+ * @param unit - The unit to link from
+ * @param link - The accountability link to add
+ * @returns The unit with the new link
+ */
+export declare function linkAccountability(unit: ImportanceUnit, link: AccountabilityLink): ImportanceUnit;
+/**
+ * Resolve all accountability links for a unit against a collection
+ * of known ImportanceUnits. Returns the links that point to valid
+ * existing units.
+ *
+ * @param unit - The unit whose links to resolve
+ * @param allUnits - Map of all known units by ID
+ * @returns Object with resolved (found) and unresolved (dangling) links
+ */
+export declare function resolveLinks(unit: ImportanceUnit, allUnits: Map<string, ImportanceUnit>): {
+    resolved: AccountabilityLink[];
+    unresolved: AccountabilityLink[];
+};
+/**
+ * Find accountability gaps across a set of ImportanceUnits.
+ *
+ * Identifies units that lack key relational connections:
+ * - Units with no accountability links at all
+ * - Units with no 'accountable-to' link
+ * - Units with high epistemic weight but no 'deepens' or 'circles-back-to' links
+ *
+ * @param units - Collection of ImportanceUnits to analyze
+ * @returns Array of identified gaps
+ */
+export declare function findGaps(units: ImportanceUnit[]): AccountabilityGap[];
+//# sourceMappingURL=accountability.d.ts.map

package/dist/accountability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.d.ts","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,iBAAiB,EAAE,sBAAsB,CAAC;CAC3C;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,kBAAkB,GACvB,cAAc,CAUhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACpC;IAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAAC,UAAU,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAatE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CA0CrE"}

package/dist/accountability.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * @medicine-wheel/importance-unit — Accountability Link Management
+ *
+ * Manages the relational strings connecting ImportanceUnits to what
+ * they are accountable to. The question is "To what is this accountable?"
+ * not "What is this about?"
+ *
+ * Wilson's relational accountability requires that every piece of
+ * knowledge be tethered to its responsibilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkAccountability = linkAccountability;
+exports.resolveLinks = resolveLinks;
+exports.findGaps = findGaps;
+// ── Link Management ─────────────────────────────────────────────────────────
+/**
+ * Add an accountability link to an ImportanceUnit.
+ *
+ * Returns a new unit with the link appended. Does not add
+ * duplicate links (same targetId and relationType).
+ *
+ * @param unit - The unit to link from
+ * @param link - The accountability link to add
+ * @returns The unit with the new link
+ */
+function linkAccountability(unit, link) {
+    const exists = unit.accountabilityLinks.some((l) => l.targetId === link.targetId && l.relationType === link.relationType);
+    if (exists)
+        return unit;
+    return {
+        ...unit,
+        accountabilityLinks: [...unit.accountabilityLinks, link],
+    };
+}
+/**
+ * Resolve all accountability links for a unit against a collection
+ * of known ImportanceUnits. Returns the links that point to valid
+ * existing units.
+ *
+ * @param unit - The unit whose links to resolve
+ * @param allUnits - Map of all known units by ID
+ * @returns Object with resolved (found) and unresolved (dangling) links
+ */
+function resolveLinks(unit, allUnits) {
+    const resolved = [];
+    const unresolved = [];
+    for (const link of unit.accountabilityLinks) {
+        if (allUnits.has(link.targetId)) {
+            resolved.push(link);
+        }
+        else {
+            unresolved.push(link);
+        }
+    }
+    return { resolved, unresolved };
+}
+/**
+ * Find accountability gaps across a set of ImportanceUnits.
+ *
+ * Identifies units that lack key relational connections:
+ * - Units with no accountability links at all
+ * - Units with no 'accountable-to' link
+ * - Units with high epistemic weight but no 'deepens' or 'circles-back-to' links
+ *
+ * @param units - Collection of ImportanceUnits to analyze
+ * @returns Array of identified gaps
+ */
+function findGaps(units) {
+    const gaps = [];
+    for (const unit of units) {
+        // Units with no links at all are relationally isolated
+        if (unit.accountabilityLinks.length === 0) {
+            gaps.push({
+                unitId: unit.id,
+                description: 'Unit has no accountability links — relationally isolated',
+                suggestedLinkType: 'accountable-to',
+            });
+            continue;
+        }
+        // Every unit should be accountable to something
+        const hasAccountableTo = unit.accountabilityLinks.some((l) => l.relationType === 'accountable-to');
+        if (!hasAccountableTo) {
+            gaps.push({
+                unitId: unit.id,
+                description: 'Unit lacks an "accountable-to" link — knowledge without accountability',
+                suggestedLinkType: 'accountable-to',
+            });
+        }
+        // High-weight units should have deepening connections
+        if (unit.epistemicWeight >= 0.8) {
+            const hasDeepening = unit.accountabilityLinks.some((l) => l.relationType === 'deepens' || l.relationType === 'circles-back-to');
+            if (!hasDeepening) {
+                gaps.push({
+                    unitId: unit.id,
+                    description: 'High-weight unit lacks deepening links — authority without depth',
+                    suggestedLinkType: 'deepens',
+                });
+            }
+        }
+    }
+    return gaps;
+}
+//# sourceMappingURL=accountability.js.map

package/dist/accountability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.js","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAkCH,gDAaC;AAWD,oCAgBC;AAaD,4BA0CC;AA3GD,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAChC,IAAoB,EACpB,IAAwB;IAExB,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAC1C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,YAAY,CAC5E,CAAC;IACF,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC;IAExB,OAAO;QACL,GAAG,IAAI;QACP,mBAAmB,EAAE,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC;KACzD,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAC1B,IAAoB,EACpB,QAAqC;IAErC,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAyB,EAAE,CAAC;IAE5C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC5C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,QAAQ,CAAC,KAAuB;IAC9C,MAAM,IAAI,GAAwB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,uDAAuD;QACvD,IAAI,IAAI,CAAC,mBAAmB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC;gBACR,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,WAAW,EAAE,0DAA0D;gBACvE,iBAAiB,EAAE,gBAAgB;aACpC,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,gDAAgD;QAChD,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CACpD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,gBAAgB,CAC3C,CAAC;QACF,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,IAAI,CAAC,IAAI,CAAC;gBACR,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,WAAW,EAAE,wEAAwE;gBACrF,iBAAiB,EAAE,gBAAgB;aACpC,CAAC,CAAC;QACL,CAAC;QAED,sDAAsD;QACtD,IAAI,IAAI,CAAC,eAAe,IAAI,GAAG,EAAE,CAAC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,SAAS,IAAI,CAAC,CAAC,YAAY,KAAK,iBAAiB,CAC5E,CAAC;YACF,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,IAAI,CAAC,IAAI,CAAC;oBACR,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,WAAW,EAAE,kEAAkE;oBAC/E,iBAAiB,EAAE,SAAS;iBAC7B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/circle-tracking.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @medicine-wheel/importance-unit — Circle / Spiral Tracking
+ *
+ * Tracks the spiral journey of ImportanceUnits through repeated
+ * circling. In Wilson's framework, returning to a topic is not
+ * redundancy — it is ceremony and deepening. Each circle reveals
+ * the "subtle difference between the 3rd and 4th circling."
+ *
+ * Detects both deepening (genuine shifts in understanding) and
+ * stagnation (circling without change).
+ */
+import type { DirectionName } from '@medicine-wheel/ontology-core';
+import type { ImportanceUnit } from './types.js';
+/**
+ * Increment the circle depth and record the current direction
+ * in the ceremony state's quadrantsVisited.
+ *
+ * @param unit - The unit to deepen
+ * @param direction - The direction being visited in this circle
+ * @returns Updated unit with incremented depth and visited direction
+ */
+export declare function incrementCircle(unit: ImportanceUnit, direction: DirectionName): ImportanceUnit;
+/**
+ * Record a refinement describing what shifted in this circle pass.
+ *
+ * @param unit - The unit being refined
+ * @param shift - What changed or deepened
+ * @returns Updated unit with the new refinement appended
+ */
+export declare function recordRefinement(unit: ImportanceUnit, shift: string): ImportanceUnit;
+/**
+ * Result of analyzing an ImportanceUnit's spiral depth.
+ */
+export interface DeepeningAnalysis {
+    /** Total number of circles completed */
+    totalCircles: number;
+    /** Number of refinements recorded */
+    refinementCount: number;
+    /** Whether genuine deepening is detected */
+    isDeepening: boolean;
+    /** Average refinement length as a crude signal of substance */
+    averageShiftLength: number;
+    /** The most recent refinement, if any */
+    latestShift?: string;
+}
+/**
+ * Detect whether an ImportanceUnit is genuinely deepening through
+ * its spiral journey. Deepening requires that refinements are being
+ * recorded and that they carry substance.
+ *
+ * @param unit - The unit to analyze
+ * @returns Analysis of the unit's spiral depth
+ */
+export declare function detectDeepening(unit: ImportanceUnit): DeepeningAnalysis;
+/**
+ * Result of stagnation analysis.
+ */
+export interface StagnationAnalysis {
+    /** Whether stagnation is detected */
+    isStagnant: boolean;
+    /** Number of circles without refinement */
+    circlesWithoutRefinement: number;
+    /** Ratio of refinements to circles */
+    refinementRatio: number;
+    /** Guidance for the practitioner */
+    guidance: string;
+}
+/**
+ * Detect whether an ImportanceUnit is stagnating — circling
+ * without genuine deepening or change.
+ *
+ * Stagnation is signaled when circleDepth exceeds refinement
+ * count by a significant margin, suggesting mechanical repetition
+ * rather than ceremonial deepening.
+ *
+ * @param unit - The unit to analyze
+ * @returns Stagnation analysis
+ */
+export declare function detectStagnation(unit: ImportanceUnit): StagnationAnalysis;
+//# sourceMappingURL=circle-tracking.d.ts.map

package/dist/circle-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circle-tracking.d.ts","sourceRoot":"","sources":["../src/circle-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAKlF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,aAAa,GACvB,cAAc,CAyBhB;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,MAAM,GACZ,cAAc,CAchB;AAID;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,iBAAiB,CA2BvE;AAID;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,wBAAwB,EAAE,MAAM,CAAC;IACjC,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CA2BzE"}

package/dist/circle-tracking.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * @medicine-wheel/importance-unit — Circle / Spiral Tracking
+ *
+ * Tracks the spiral journey of ImportanceUnits through repeated
+ * circling. In Wilson's framework, returning to a topic is not
+ * redundancy — it is ceremony and deepening. Each circle reveals
+ * the "subtle difference between the 3rd and 4th circling."
+ *
+ * Detects both deepening (genuine shifts in understanding) and
+ * stagnation (circling without change).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.incrementCircle = incrementCircle;
+exports.recordRefinement = recordRefinement;
+exports.detectDeepening = detectDeepening;
+exports.detectStagnation = detectStagnation;
+const epistemic_weight_js_1 = require("./epistemic-weight.js");
+// ── Circle Increment ────────────────────────────────────────────────────────
+/**
+ * Increment the circle depth and record the current direction
+ * in the ceremony state's quadrantsVisited.
+ *
+ * @param unit - The unit to deepen
+ * @param direction - The direction being visited in this circle
+ * @returns Updated unit with incremented depth and visited direction
+ */
+function incrementCircle(unit, direction) {
+    const newDepth = unit.circleDepth + 1;
+    const visited = unit.ceremonyState?.quadrantsVisited ?? [];
+    const updatedVisited = visited.includes(direction)
+        ? visited
+        : [...visited, direction];
+    const circleComplete = updatedVisited.length >= 4;
+    const ceremonyState = {
+        quadrantsVisited: updatedVisited,
+        circleComplete,
+        gatingConditions: unit.ceremonyState?.gatingConditions ?? [],
+    };
+    return {
+        ...unit,
+        circleDepth: newDepth,
+        direction,
+        epistemicWeight: (0, epistemic_weight_js_1.computeWeight)(unit.source, newDepth),
+        ceremonyState,
+        meta: {
+            ...unit.meta,
+            lastCircledAt: new Date().toISOString(),
+        },
+    };
+}
+// ── Refinement Recording ────────────────────────────────────────────────────
+/**
+ * Record a refinement describing what shifted in this circle pass.
+ *
+ * @param unit - The unit being refined
+ * @param shift - What changed or deepened
+ * @returns Updated unit with the new refinement appended
+ */
+function recordRefinement(unit, shift) {
+    const refinement = {
+        circle: unit.circleDepth,
+        shift,
+        timestamp: new Date().toISOString(),
+    };
+    return {
+        ...unit,
+        content: {
+            ...unit.content,
+            refinements: [...unit.content.refinements, refinement],
+        },
+    };
+}
+/**
+ * Detect whether an ImportanceUnit is genuinely deepening through
+ * its spiral journey. Deepening requires that refinements are being
+ * recorded and that they carry substance.
+ *
+ * @param unit - The unit to analyze
+ * @returns Analysis of the unit's spiral depth
+ */
+function detectDeepening(unit) {
+    const refinements = unit.content.refinements;
+    const refinementCount = refinements.length;
+    if (refinementCount === 0) {
+        return {
+            totalCircles: unit.circleDepth,
+            refinementCount: 0,
+            isDeepening: false,
+            averageShiftLength: 0,
+        };
+    }
+    const totalLength = refinements.reduce((sum, r) => sum + r.shift.length, 0);
+    const averageShiftLength = totalLength / refinementCount;
+    const latestShift = refinements[refinements.length - 1]?.shift;
+    // Deepening requires at least some substance in the shifts
+    const isDeepening = refinementCount > 0 && averageShiftLength > 10;
+    return {
+        totalCircles: unit.circleDepth,
+        refinementCount,
+        isDeepening,
+        averageShiftLength,
+        latestShift,
+    };
+}
+/**
+ * Detect whether an ImportanceUnit is stagnating — circling
+ * without genuine deepening or change.
+ *
+ * Stagnation is signaled when circleDepth exceeds refinement
+ * count by a significant margin, suggesting mechanical repetition
+ * rather than ceremonial deepening.
+ *
+ * @param unit - The unit to analyze
+ * @returns Stagnation analysis
+ */
+function detectStagnation(unit) {
+    const refinementCount = unit.content.refinements.length;
+    const circlesWithoutRefinement = Math.max(0, unit.circleDepth - refinementCount - 1);
+    const refinementRatio = unit.circleDepth > 1
+        ? refinementCount / (unit.circleDepth - 1)
+        : 1;
+    // Stagnation: many circles, few refinements
+    const isStagnant = unit.circleDepth >= 3 && refinementRatio < 0.5;
+    let guidance;
+    if (isStagnant) {
+        guidance = 'This unit has been circled multiple times without substantial deepening. '
+            + 'Consider approaching from a different direction or source dimension.';
+    }
+    else if (refinementRatio < 0.75) {
+        guidance = 'Some circles lack recorded refinements. Ensure each return captures '
+            + 'what shifted — the subtle differences are where meaning lives.';
+    }
+    else {
+        guidance = 'Healthy spiral — each circle is producing recorded shifts.';
+    }
+    return {
+        isStagnant,
+        circlesWithoutRefinement,
+        refinementRatio,
+        guidance,
+    };
+}
+//# sourceMappingURL=circle-tracking.js.map

package/dist/circle-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circle-tracking.js","sourceRoot":"","sources":["../src/circle-tracking.ts"],"names":[],"mappings":"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"}

package/dist/epistemic-weight.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @medicine-wheel/importance-unit — Epistemic Weight Computation
+ *
+ * Computes epistemic weight for ImportanceUnits based on their
+ * source dimension and circle depth. In Wilson's epistemology,
+ * not all knowledge is equal — dream-state and embodied knowledge
+ * carry more epistemic authority than rational analysis.
+ *
+ * Base weights:
+ * - dream: 0.85 (liminal/spirit-state knowing has highest authority)
+ * - land:  0.75 (place-grounded/embodied knowing)
+ * - vision: 0.65 (intentional/architectural knowing)
+ * - code:  0.50 (technical/implementation knowing)
+ *
+ * Weight increases with circleDepth using diminishing returns
+ * (logarithmic scaling), never exceeding 1.0.
+ */
+import type { EpistemicSource } from './types.js';
+/** Base epistemic weights by source dimension */
+export declare const BASE_WEIGHTS: Record<EpistemicSource, number>;
+/**
+ * Compute the full epistemic weight for a given source and depth.
+ *
+ * Weight = baseWeight + depthBonus, clamped to [0, 1].
+ *
+ * @param source - The epistemic source dimension
+ * @param circleDepth - How many times this topic has been circled
+ * @returns Epistemic weight between 0.0 and 1.0
+ */
+export declare function computeWeight(source: EpistemicSource, circleDepth: number): number;
+/**
+ * Adjust weight for a different source dimension.
+ *
+ * Re-bases the weight using the new source's base weight
+ * while preserving the depth-derived bonus.
+ *
+ * @param currentWeight - The current epistemic weight
+ * @param currentSource - The current source dimension
+ * @param newSource - The new source dimension
+ * @returns Adjusted weight for the new source
+ */
+export declare function adjustForSource(currentWeight: number, currentSource: EpistemicSource, newSource: EpistemicSource): number;
+/**
+ * Adjust weight for a new circle depth.
+ *
+ * Recalculates weight from the source base plus the new
+ * depth bonus.
+ *
+ * @param source - The epistemic source dimension
+ * @param newDepth - The new circle depth
+ * @returns Recalculated weight
+ */
+export declare function adjustForDepth(source: EpistemicSource, newDepth: number): number;
+//# sourceMappingURL=epistemic-weight.d.ts.map

package/dist/epistemic-weight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epistemic-weight.d.ts","sourceRoot":"","sources":["../src/epistemic-weight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,iDAAiD;AACjD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKxD,CAAC;AAyBF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAIlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,eAAe,EAC9B,SAAS,EAAE,eAAe,GACzB,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhF"}

package/dist/epistemic-weight.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * @medicine-wheel/importance-unit — Epistemic Weight Computation
+ *
+ * Computes epistemic weight for ImportanceUnits based on their
+ * source dimension and circle depth. In Wilson's epistemology,
+ * not all knowledge is equal — dream-state and embodied knowledge
+ * carry more epistemic authority than rational analysis.
+ *
+ * Base weights:
+ * - dream: 0.85 (liminal/spirit-state knowing has highest authority)
+ * - land:  0.75 (place-grounded/embodied knowing)
+ * - vision: 0.65 (intentional/architectural knowing)
+ * - code:  0.50 (technical/implementation knowing)
+ *
+ * Weight increases with circleDepth using diminishing returns
+ * (logarithmic scaling), never exceeding 1.0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_WEIGHTS = void 0;
+exports.computeWeight = computeWeight;
+exports.adjustForSource = adjustForSource;
+exports.adjustForDepth = adjustForDepth;
+// ── Base Weights ────────────────────────────────────────────────────────────
+/** Base epistemic weights by source dimension */
+exports.BASE_WEIGHTS = {
+    dream: 0.85,
+    land: 0.75,
+    vision: 0.65,
+    code: 0.50,
+};
+/** Maximum depth bonus that can be added to base weight */
+const MAX_DEPTH_BONUS = 0.15;
+/** Logarithmic scaling factor for depth bonus */
+const DEPTH_SCALE = 3;
+// ── Weight Computation ──────────────────────────────────────────────────────
+/**
+ * Compute the depth bonus using diminishing returns.
+ *
+ * Uses logarithmic scaling so that early circles contribute
+ * more than later ones — the first return yields more insight
+ * than the tenth, though all returns matter.
+ *
+ * @param circleDepth - Number of times circled (minimum 1)
+ * @returns Depth bonus between 0 and MAX_DEPTH_BONUS
+ */
+function depthBonus(circleDepth) {
+    if (circleDepth <= 1)
+        return 0;
+    return MAX_DEPTH_BONUS * (Math.log(circleDepth) / Math.log(circleDepth + DEPTH_SCALE));
+}
+/**
+ * Compute the full epistemic weight for a given source and depth.
+ *
+ * Weight = baseWeight + depthBonus, clamped to [0, 1].
+ *
+ * @param source - The epistemic source dimension
+ * @param circleDepth - How many times this topic has been circled
+ * @returns Epistemic weight between 0.0 and 1.0
+ */
+function computeWeight(source, circleDepth) {
+    const base = exports.BASE_WEIGHTS[source];
+    const bonus = depthBonus(circleDepth);
+    return Math.min(1.0, base + bonus);
+}
+/**
+ * Adjust weight for a different source dimension.
+ *
+ * Re-bases the weight using the new source's base weight
+ * while preserving the depth-derived bonus.
+ *
+ * @param currentWeight - The current epistemic weight
+ * @param currentSource - The current source dimension
+ * @param newSource - The new source dimension
+ * @returns Adjusted weight for the new source
+ */
+function adjustForSource(currentWeight, currentSource, newSource) {
+    const currentBase = exports.BASE_WEIGHTS[currentSource];
+    const bonus = currentWeight - currentBase;
+    const newBase = exports.BASE_WEIGHTS[newSource];
+    return Math.min(1.0, Math.max(0, newBase + Math.max(0, bonus)));
+}
+/**
+ * Adjust weight for a new circle depth.
+ *
+ * Recalculates weight from the source base plus the new
+ * depth bonus.
+ *
+ * @param source - The epistemic source dimension
+ * @param newDepth - The new circle depth
+ * @returns Recalculated weight
+ */
+function adjustForDepth(source, newDepth) {
+    return computeWeight(source, newDepth);
+}
+//# sourceMappingURL=epistemic-weight.js.map

package/dist/epistemic-weight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epistemic-weight.js","sourceRoot":"","sources":["../src/epistemic-weight.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AA8CH,sCAIC;AAaD,0CASC;AAYD,wCAEC;AAlFD,+EAA+E;AAE/E,iDAAiD;AACpC,QAAA,YAAY,GAAoC;IAC3D,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,IAAI;CACX,CAAC;AAEF,2DAA2D;AAC3D,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,iDAAiD;AACjD,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,WAAmB;IACrC,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,eAAe,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,aAAa,CAAC,MAAuB,EAAE,WAAmB;IACxE,MAAM,IAAI,GAAG,oBAAY,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAC7B,aAAqB,EACrB,aAA8B,EAC9B,SAA0B;IAE1B,MAAM,WAAW,GAAG,oBAAY,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,aAAa,GAAG,WAAW,CAAC;IAC1C,MAAM,OAAO,GAAG,oBAAY,CAAC,SAAS,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,MAAuB,EAAE,QAAgB;IACtE,OAAO,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC"}