@neuroverseos/governance 0.6.1 → 0.8.0

package/dist/radiant/index.d.ts

@@ -777,31 +777,56 @@ declare function createMockAI(fixedResponse: string): RadiantAI;
 /**
  * @neuroverseos/governance/radiant — scope resolution
  *
- * Parses scope strings like "aukiverse/posemesh" into typed scope objects
- * that adapters (GitHub, etc.) know how to fetch.
+ * Parses scope strings into typed scope objects that adapters know how
+ * to fetch. Supports two levels:
+ *
+ *   "owner/repo"  → RepoScope (single repo)
+ *   "owner/"      → OrgScope (entire organization)
+ *   "owner"       → OrgScope (entire organization)
  */
 /**
- * A GitHub repository scope — the unit of activity Radiant reads.
+ * A GitHub repository scope — single repo.
  */
 interface RepoScope {
+    type: 'repo';
     owner: string;
     repo: string;
 }
 /**
- * Parse a scope string into a RepoScope.
+ * A GitHub organization scope — all repos in an org.
+ */
+interface OrgScope {
+    type: 'org';
+    owner: string;
+}
+type Scope = RepoScope | OrgScope;
+/**
+ * Visibility level for a Radiant read. Controls what sources are
+ * included and where output goes.
  *
- * Accepts:
- *   "owner/repo"
- *   "https://github.com/owner/repo"
- *   "github.com/owner/repo"
+ *   community — public repos + public Discord. Anyone can reproduce.
+ *   team      — public + private repos + team channels. Team exocortex.
+ *   full      — everything + cross-exocortex. Leader's personal exocortex.
+ */
+type ViewLevel = 'community' | 'team' | 'full';
+/**
+ * Parse a scope string into a RepoScope or OrgScope.
  *
- * Throws on unparseable input.
+ * Accepts:
+ *   "owner/repo"                    → RepoScope
+ *   "owner/" or "owner"             → OrgScope
+ *   "https://github.com/owner/repo" → RepoScope
+ *   "https://github.com/owner"      → OrgScope
+ */
+declare function parseScope(scope: string): Scope;
+/**
+ * Backward-compatible: parse as RepoScope only. Throws if org-level.
  */
 declare function parseRepoScope(scope: string): RepoScope;
 /**
- * Format a RepoScope back to a display string.
+ * Format any scope back to a display string.
  */
-declare function formatScope(scope: RepoScope): string;
+declare function formatScope(scope: Scope): string;
 
 /**
  * @neuroverseos/governance/radiant — GitHub activity adapter
@@ -844,6 +869,15 @@ interface GitHubFetchOptions {
  * @param options — window size and pagination
  */
 declare function fetchGitHubActivity(scope: RepoScope, token: string, options?: GitHubFetchOptions): Promise<Event[]>;
+/**
+ * Fetch recent activity across an ENTIRE GitHub organization.
+ * Uses /orgs/{org}/repos to list repos, then fetches activity from
+ * each active repo.
+ */
+declare function fetchGitHubOrgActivity(scope: OrgScope, token: string, options?: GitHubFetchOptions): Promise<{
+    events: Event[];
+    repos: string[];
+}>;
 /**
  * Create a mock GitHub adapter for testing. Returns fixed events
  * without calling the GitHub API.
@@ -902,11 +936,210 @@ declare function readExocortex(dirPath: string): ExocortexContext;
  * prompt. Only includes fields that were actually loaded.
  */
 declare function formatExocortexForPrompt(ctx: ExocortexContext): string;
+/**
+ * Read multiple exocortices from a team directory. Each subdirectory
+ * (or symlink) is treated as one person's exocortex.
+ *
+ * Returns an array of { name, context } for each person.
+ */
+declare function readTeamExocortices(teamDir: string): Array<{
+    name: string;
+    context: ExocortexContext;
+}>;
+/**
+ * Format multiple exocortices for the AI prompt — shows each person's
+ * stated intent so the AI can compare them against each other and
+ * against observed activity.
+ */
+declare function formatTeamExocorticesForPrompt(team: Array<{
+    name: string;
+    context: ExocortexContext;
+}>): string;
 /**
  * One-line summary of what was loaded, for CLI status output.
  */
 declare function summarizeExocortex(ctx: ExocortexContext): string;
 
+/**
+ * @neuroverseos/governance/radiant — Discord adapter
+ *
+ * Reads conversational activity from Discord channels and maps it to
+ * Radiant's Event type. This is where Narrative Dynamics and Shared
+ * Prosperity signals become visible — how the team communicates,
+ * coordinates, welcomes newcomers, resolves debates.
+ *
+ * Two modes:
+ *   - Channel message reading (via Discord Bot API)
+ *   - Signal compression (aggregate metrics from raw messages)
+ *
+ * Privacy:
+ *   - Public channels → community view (anyone can reproduce)
+ *   - Team channels → team view (team exocortex only)
+ *   - Private channels / DMs → never read unless explicitly configured
+ *   - The bot token IS consent. Radiant respects Discord's permissions.
+ *
+ * Rate limiting:
+ *   - Caps at 100 messages per channel per fetch
+ *   - Produces compressed signals, not raw message dumps
+ *   - AI receives a sample of 20-30 representative messages, not the firehose
+ */
+
+interface DiscordFetchOptions {
+    /** Channel IDs to read from. If empty, reads all accessible channels. */
+    channelIds?: string[];
+    /** How many days of history to fetch. Default: 14. */
+    windowDays?: number;
+    /** Max messages per channel. Default: 100. */
+    perChannel?: number;
+    /** Visibility level — determines which channels to read. */
+    visibility?: 'public' | 'team';
+}
+interface DiscordSignals {
+    /** Total messages across all channels in the window. */
+    totalMessages: number;
+    /** Number of active channels. */
+    activeChannels: number;
+    /** Unique participants. */
+    uniqueParticipants: number;
+    /** Average response time in minutes (for threaded/reply messages). */
+    avgResponseMinutes: number | null;
+    /** Number of help requests detected (messages containing "help", "stuck", "how do I"). */
+    helpRequests: number;
+    /** Number of unresolved threads (threads with no reply). */
+    unresolvedThreads: number;
+    /** Top discussed topics (extracted from channel names + frequent terms). */
+    topTopics: string[];
+    /** Messages from new participants (first seen in this window). */
+    newcomerMessages: number;
+}
+/**
+ * Fetch Discord activity and return Radiant Events + compressed signals.
+ *
+ * Uses the Discord Bot API (raw fetch, no SDK dependency).
+ * Requires a bot token with MESSAGE_CONTENT intent enabled.
+ */
+declare function fetchDiscordActivity(guildId: string, token: string, options?: DiscordFetchOptions): Promise<{
+    events: Event[];
+    signals: DiscordSignals;
+}>;
+/**
+ * Format Discord signals for the AI interpretation prompt.
+ */
+declare function formatDiscordSignalsForPrompt(signals: DiscordSignals): string;
+
+/**
+ * @neuroverseos/governance/radiant — Slack adapter
+ *
+ * Reads conversational activity from Slack workspaces. For Auki, Slack
+ * is used for external client and partner communication — FairPrice,
+ * retail pilots, Intercognitive coalition partners.
+ *
+ * What it captures:
+ *   - Partner coordination patterns (peaq, Mawari, GEODNET)
+ *   - Client communication quality (responsiveness, follow-through)
+ *   - External contributor onboarding
+ *   - Cross-organization alignment signals
+ *   - Decision-making in channels (debates → outcomes)
+ *
+ * Privacy: workspace token controls access. Bot tokens see channels
+ * the bot is invited to. User tokens see what the user sees. Private
+ * channels and DMs only accessible if explicitly configured.
+ *
+ * Uses Slack Web API via raw fetch (no SDK dependency).
+ * Requires a Bot Token with channels:history + channels:read scopes.
+ */
+
+interface SlackFetchOptions {
+    /** Channel IDs to read. If empty, reads all public channels the bot can see. */
+    channelIds?: string[];
+    /** How many days of history to fetch. Default: 14. */
+    windowDays?: number;
+    /** Max messages per channel. Default: 100. */
+    perChannel?: number;
+    /** Visibility level. */
+    visibility?: 'public' | 'team';
+}
+interface SlackSignals {
+    totalMessages: number;
+    activeChannels: number;
+    uniqueParticipants: number;
+    avgResponseMinutes: number | null;
+    externalParticipants: number;
+    unresolvedThreads: number;
+    topChannels: string[];
+    reactionCount: number;
+}
+/**
+ * Fetch Slack activity and return Radiant Events + compressed signals.
+ */
+declare function fetchSlackActivity(token: string, options?: SlackFetchOptions): Promise<{
+    events: Event[];
+    signals: SlackSignals;
+}>;
+/**
+ * Format Slack signals for the AI interpretation prompt.
+ */
+declare function formatSlackSignalsForPrompt(signals: SlackSignals): string;
+
+/**
+ * @neuroverseos/governance/radiant — Notion adapter
+ *
+ * Reads documentation and knowledge-base activity from Notion.
+ * For Auki, Notion is where team documentation lives — specs, meeting
+ * notes, strategy docs, project plans, decision records.
+ *
+ * What it captures:
+ *   - Documentation freshness (when pages were last edited)
+ *   - Who maintains what (authorship patterns across pages)
+ *   - Knowledge gaps (sprint mentions things that have no doc page)
+ *   - Decision crystallization (are debates in Discord becoming docs in Notion?)
+ *   - Documentation velocity alongside code velocity
+ *
+ * The behavioral signal: high code shipping + low documentation =
+ * the team is building but not recording what they learn. That's a
+ * Narrative Dynamics gap — the story of what's being built isn't
+ * being told, even internally.
+ *
+ * Uses Notion API v1 via raw fetch (no SDK dependency).
+ * Requires an internal integration token with read access.
+ */
+
+interface NotionFetchOptions {
+    /** Specific database IDs to query. If empty, searches all accessible pages. */
+    databaseIds?: string[];
+    /** How many days of history to fetch. Default: 14. */
+    windowDays?: number;
+    /** Max pages to fetch. Default: 100. */
+    maxPages?: number;
+}
+interface NotionSignals {
+    /** Total pages created or updated in the window. */
+    pagesActive: number;
+    /** Pages created (new docs). */
+    pagesCreated: number;
+    /** Pages updated (edited docs). */
+    pagesUpdated: number;
+    /** Unique editors. */
+    uniqueEditors: number;
+    /** Pages not touched in 30+ days. */
+    stalePages: number;
+    /** Average days since last edit across all tracked pages. */
+    avgDaysSinceEdit: number | null;
+    /** Top page titles by recent activity. */
+    topPages: string[];
+}
+/**
+ * Fetch Notion page activity and return Radiant Events + compressed signals.
+ */
+declare function fetchNotionActivity(token: string, options?: NotionFetchOptions): Promise<{
+    events: Event[];
+    signals: NotionSignals;
+}>;
+/**
+ * Format Notion signals for the AI interpretation prompt.
+ */
+declare function formatNotionSignalsForPrompt(signals: NotionSignals): string;
+
 /**
  * @neuroverseos/governance/radiant — AI pattern interpretation
  *
@@ -970,6 +1203,60 @@ interface InterpretResult {
  */
 declare function interpretPatterns(input: InterpretInput): Promise<InterpretResult>;
 
+/**
+ * @neuroverseos/governance/radiant — governance audit
+ *
+ * Runs each GitHub event through the NeuroverseOS guard engine against
+ * the compiled worldmodel. Produces an audit trail showing which events
+ * triggered governance (BLOCK/MODIFY), which side (human/AI/joint),
+ * and what invariants were tested.
+ *
+ * This is where Radiant meets the NeuroverseOS governance engine.
+ * Same evaluateGuard() that runs at API-level, applied retroactively
+ * to activity that already happened. The audit trail is the proof that
+ * the cocoon's walls are holding — or shows where they're being tested.
+ */
+
+interface GovernanceVerdict {
+    eventId: string;
+    domain: ActorDomain;
+    status: 'ALLOW' | 'BLOCK' | 'MODIFY' | 'PAUSE' | 'PENALIZE' | 'REWARD';
+    reason?: string;
+    ruleId?: string;
+    warning?: string;
+}
+interface GovernanceAudit {
+    totalEvents: number;
+    human: {
+        allow: number;
+        modify: number;
+        block: number;
+        details: GovernanceVerdict[];
+    };
+    cyber: {
+        allow: number;
+        modify: number;
+        block: number;
+        details: GovernanceVerdict[];
+    };
+    joint: {
+        allow: number;
+        modify: number;
+        block: number;
+        details: GovernanceVerdict[];
+    };
+    /** Summary for rendering — most important findings. */
+    summary: string;
+}
+/**
+ * Run each classified event through the guard engine against the compiled
+ * worldmodel. Returns a structured audit with human/cyber/joint breakdown.
+ *
+ * @param events — classified events from the GitHub adapter
+ * @param worldPath — path to a compiled .nv-world.md or world directory
+ */
+declare function auditGovernance(events: readonly ClassifiedEvent[], worldPath: string): Promise<GovernanceAudit>;
+
 /**
  * @neuroverseos/governance/radiant — renderer
  *
@@ -983,7 +1270,7 @@ declare function interpretPatterns(input: InterpretInput): Promise<InterpretResu
  */
 
 interface RenderInput {
-    scope: RepoScope;
+    scope: Scope;
     windowDays: number;
     eventCount: number;
     signals: readonly Signal[];
@@ -1000,6 +1287,8 @@ interface RenderInput {
     move?: string;
     /** Number of prior Radiant reads available (0 = first run). */
     priorReadCount?: number;
+    /** Governance audit trail — events evaluated against the worldmodel. */
+    governance?: GovernanceAudit;
 }
 interface RenderOutput {
     /** The human-readable text output for terminal display. */
@@ -1009,6 +1298,85 @@ interface RenderOutput {
 }
 declare function render(input: RenderInput): RenderOutput;
 
+/**
+ * @neuroverseos/governance/radiant — Memory Palace file operations
+ *
+ * Writes Radiant reads to the exocortex as dated markdown files (with
+ * YAML frontmatter for structured signal data). Reads prior files to
+ * detect pattern persistence across runs.
+ *
+ * The exocortex directory IS the Memory Palace. Files are the tiers:
+ *   - reads/YYYY-MM-DD.md = Tier 2 (structured signals) + Tier 3 (narrative)
+ *   - knowledge.md = accumulated pattern facts with persistence counts
+ *
+ * No database. The file system is the time series. Git is the versioning.
+ */
+interface PriorRead {
+    date: string;
+    filename: string;
+    /** Pattern names found in this read (parsed from frontmatter). */
+    patternNames: string[];
+    /** Raw frontmatter content for signal comparison. */
+    frontmatter: string;
+}
+interface PatternPersistence {
+    name: string;
+    /** How many prior reads contained this pattern. */
+    occurrences: number;
+    /** Dates this pattern was observed. */
+    dates: string[];
+}
+/**
+ * Write a Radiant read to the exocortex. Creates the directory structure
+ * if it doesn't exist.
+ *
+ * @param exocortexDir — root of the exocortex (e.g. ~/exocortex/)
+ * @param frontmatter — YAML frontmatter (Tier 2 structured signals)
+ * @param text — prose output (Tier 3 narrative)
+ * @returns the path of the written file
+ */
+declare function writeRead(exocortexDir: string, frontmatter: string, text: string): string;
+/**
+ * Items from the worldmodel that Radiant tracks for subtraction proposals.
+ */
+interface WorldmodelItem {
+    type: 'invariant' | 'drift_behavior' | 'aligned_behavior' | 'decision_priority';
+    name: string;
+}
+/**
+ * Update the knowledge file with:
+ *   - Pattern persistence (what keeps recurring → consider adding)
+ *   - Subtraction proposals (what hasn't fired → consider removing)
+ *   - Active items (what recently triggered → keep)
+ *
+ * The leader reads this file and makes deliberate, rare, bidirectional
+ * changes to the worldmodel. Radiant proposes; the human decides.
+ */
+declare function updateKnowledge(exocortexDir: string, persistence: PatternPersistence[], options?: {
+    /** Items declared in the worldmodel (invariants, drift behaviors, etc.) */
+    declaredItems?: WorldmodelItem[];
+    /** Item names that triggered governance in this read */
+    triggeredItems?: string[];
+    /** Total number of reads completed (for "hasn't fired in N reads" tracking) */
+    totalReads?: number;
+}): string;
+/**
+ * Load prior Radiant reads from the exocortex. Returns them sorted by
+ * date (oldest first). Each read has its pattern names extracted from
+ * the frontmatter.
+ */
+declare function loadPriorReads(exocortexDir: string): PriorRead[];
+/**
+ * Compute pattern persistence across prior reads + the current patterns.
+ */
+declare function computePersistence(priorReads: PriorRead[], currentPatternNames: string[]): PatternPersistence[];
+/**
+ * Format prior-read context for the AI interpretation prompt.
+ * Tells the AI what patterns were seen in previous runs so it can
+ * reference persistence.
+ */
+declare function formatPriorReadsForPrompt(priorReads: PriorRead[]): string;
+
 /**
  * @neuroverseos/governance/radiant — `think` command
  *
@@ -1089,7 +1457,7 @@ declare function think(input: ThinkInput): Promise<ThinkResult>;
  */
 
 interface EmergentInput {
-    scope: RepoScope;
+    scope: RepoScope | OrgScope;
     githubToken: string;
     worldmodelContent: string;
     lensId: string;
@@ -1100,6 +1468,10 @@ interface EmergentInput {
      *  intent (attention, goals, sprint) and compares against observed
      *  behavior from GitHub. The gap is the most valuable signal. */
     exocortexPath?: string;
+    /** Path to a compiled world directory (for governance audit).
+     *  When present, each event is evaluated through evaluateGuard
+     *  and the GOVERNANCE section appears in the output. */
+    worldPath?: string;
 }
 interface EmergentResult {
     /** The rendered text output (EMERGENT / MEANING / MOVE). */
@@ -1147,17 +1519,16 @@ declare function emergent(input: EmergentInput): Promise<EmergentResult>;
  *     knowledge / synthesis) with a SQLite reference implementation
  *   - CLI entry (bin/radiant.ts) and MCP server entry (bin/radiant-mcp.ts)
  *
- * Build state: step 2 of 17 has landed — core types and L/C/N math.
- * Later steps land actor_domain classification, signals, patterns, the
- * auki-builder rendering lens, adapters, commands, CLI, and MCP.
- * Full roadmap: `radiant/PROJECT-PLAN.md` at the repo root.
+ * Build state: Phase 1 complete — voice layer, behavioral dashboard,
+ * MCP server, Memory Palace write-back, governance audit, ExoCortex
+ * handshake. See radiant/PROJECT-PLAN.md for the full roadmap.
  *
- * Usage (math layer, available today):
+ * Usage:
  *   import {
- *     scoreLife, scoreCyber, scoreNeuroVerse, scoreComposite,
- *     type LifeCapability, type CyberCapability,
+ *     think, emergent, scoreLife, classifyActorDomain,
+ *     aukiBuilderLens, checkForbiddenPhrases,
  *   } from '@neuroverseos/governance/radiant';
  */
 declare const RADIANT_PACKAGE_VERSION = "0.0.0";
 
-export { type Actor, type ActorDomain, type ActorKind, type AlignmentStatus, type BridgingComponent, type BridgingComponentScore, type ClassifiedEvent, type CyberCapability, type CyberDimension, DEFAULT_EVIDENCE_GATE, DEFAULT_SIGNAL_EXTRACTORS, type EmergentInput, type EmergentResult, type Event, type EventReference, type EvidenceGate, type ExemplarRef, type ExocortexContext, type ExtractionResult, type GitHubFetchOptions, type InterpretInput, type InterpretResult, LENSES, type LensVocabulary, type LifeCapability, type LifeDimension, type ObservedPattern, type OverlapDef, type PatternEvidence, type PrimaryFrame, RADIANT_PACKAGE_VERSION, type RadiantAI, type RenderInput, type RenderOutput, type RenderingLens, type RepoScope, type Score, type ScoreSentinel, type ScoredObservation, type Signal, type SignalExtractor, type SignalMatrix, type ThinkInput, type ThinkResult, type VoiceDirectives, type VoiceViolation, aukiBuilderLens, checkForbiddenPhrases, classifyActorDomain, classifyEvents, composeSystemPrompt, createAnthropicAI, createMockAI, createMockGitHubAdapter, emergent, extractSignals, fetchGitHubActivity, formatExocortexForPrompt, formatScope, getLens, interpretPatterns, isPresent, isScored, isSentinel, listLenses, parseRepoScope, presenceAverage, readExocortex, render, scoreComposite, scoreCyber, scoreLife, scoreNeuroVerse, summarizeExocortex, think };
+export { type Actor, type ActorDomain, type ActorKind, type AlignmentStatus, type BridgingComponent, type BridgingComponentScore, type ClassifiedEvent, type CyberCapability, type CyberDimension, DEFAULT_EVIDENCE_GATE, DEFAULT_SIGNAL_EXTRACTORS, type DiscordFetchOptions, type DiscordSignals, type EmergentInput, type EmergentResult, type Event, type EventReference, type EvidenceGate, type ExemplarRef, type ExocortexContext, type ExtractionResult, type GitHubFetchOptions, type GovernanceAudit, type GovernanceVerdict, type InterpretInput, type InterpretResult, LENSES, type LensVocabulary, type LifeCapability, type LifeDimension, type NotionFetchOptions, type NotionSignals, type ObservedPattern, type OrgScope, type OverlapDef, type PatternEvidence, type PatternPersistence, type PrimaryFrame, type PriorRead, RADIANT_PACKAGE_VERSION, type RadiantAI, type RenderInput, type RenderOutput, type RenderingLens, type RepoScope, type Scope, type Score, type ScoreSentinel, type ScoredObservation, type Signal, type SignalExtractor, type SignalMatrix, type SlackFetchOptions, type SlackSignals, type ThinkInput, type ThinkResult, type ViewLevel, type VoiceDirectives, type VoiceViolation, type WorldmodelItem, auditGovernance, aukiBuilderLens, checkForbiddenPhrases, classifyActorDomain, classifyEvents, composeSystemPrompt, computePersistence, createAnthropicAI, createMockAI, createMockGitHubAdapter, emergent, extractSignals, fetchDiscordActivity, fetchGitHubActivity, fetchGitHubOrgActivity, fetchNotionActivity, fetchSlackActivity, formatDiscordSignalsForPrompt, formatExocortexForPrompt, formatNotionSignalsForPrompt, formatPriorReadsForPrompt, formatScope, formatSlackSignalsForPrompt, formatTeamExocorticesForPrompt, getLens, interpretPatterns, isPresent, isScored, isSentinel, listLenses, loadPriorReads, parseRepoScope, parseScope, presenceAverage, readExocortex, readTeamExocortices, render, scoreComposite, scoreCyber, scoreLife, scoreNeuroVerse, summarizeExocortex, think, updateKnowledge, writeRead };