@kognai/orchestrator-core 0.1.0

package/dist/lib/chomsky-gate.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * chomsky-gate.ts — Prompt Quality Evaluator
+ *
+ * Intercepts outbound prompts before LLM dispatch.
+ * Named after Chomsky for its linguistic quality focus.
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient evaluation
+ * Threshold: score >= 7 PASSES, score < 7 FAILS + logs + triggers rewrite attempt
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHOMSKY_PASS_THRESHOLD = void 0;
+exports.evaluatePromptQuality = evaluatePromptQuality;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_paths_1 = require("./engine-paths");
+const model_router_registry_1 = require("./model-router-registry");
+// ── Config ────────────────────────────────────────────────────────────────────
+exports.CHOMSKY_PASS_THRESHOLD = 7;
+const EVAL_SYSTEM = `You are a prompt quality evaluator for an autonomous AI orchestration system.
+Your job is to score outbound agent prompts before they are dispatched to LLMs.
+Respond ONLY with valid JSON — no prose, no markdown fences, no explanation.`;
+const EVAL_PROMPT_TEMPLATE = `Evaluate the following agent prompt on a scale of 0-10.
+
+Scoring criteria (2 points each):
+1. Clarity — Is the task unambiguously stated?
+2. Specificity — Are inputs, outputs, and constraints defined?
+3. Context — Is sufficient background provided for the agent to act correctly?
+4. Actionability — Can the agent execute this without needing clarification?
+5. Completeness — Are success criteria or expected outputs described?
+
+Respond with this exact JSON structure:
+{"score": <integer 0-10>, "issues": [<brief issue string>, ...]}
+
+If score >= 7, issues may be an empty array [].
+If score < 7, issues must describe what is missing or unclear.
+
+Prompt to evaluate:
+---
+{{PROMPT}}
+---`;
+// ── Log path ──────────────────────────────────────────────────────────────────
+function getLogPath() {
+    const today = new Date().toISOString().slice(0, 10);
+    const logDir = path.join((0, engine_paths_1.resolveEnginePaths)().root, 'logs', 'chomsky');
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    return path.join(logDir, `${today}.jsonl`);
+}
+function logFailure(prompt, result, agentId) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        agent_id: agentId,
+        score: result.score,
+        issues: result.issues,
+        prompt_preview: prompt.slice(0, 300),
+        passed: false,
+    };
+    try {
+        fs.appendFileSync(getLogPath(), JSON.stringify(entry) + '\n');
+    }
+    catch (_err) {
+        // Non-fatal — log write failure must not block the pipeline
+    }
+}
+// ── Response parser ───────────────────────────────────────────────────────────
+function parseEvalResponse(raw) {
+    // Strip <think> blocks if present (qwen3 extended thinking)
+    const cleaned = raw.replace(/<think>[\s\S]*?<\/think>/gi, '').trim();
+    // Extract first JSON object containing score + issues
+    const jsonMatch = cleaned.match(/\{[^{}]*"score"[^{}]*"issues"[^{}]*\}/);
+    if (!jsonMatch)
+        return null;
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (typeof parsed.score === 'number' && Array.isArray(parsed.issues)) {
+            return {
+                score: Math.max(0, Math.min(10, Math.round(parsed.score))),
+                issues: parsed.issues.map(String).filter(Boolean),
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Core evaluator ────────────────────────────────────────────────────────────
+/**
+ * Evaluate the quality of an outbound agent prompt.
+ *
+ * @param prompt   The prompt string about to be dispatched to an LLM agent
+ * @param agentId  Identifier of the calling agent (for log attribution)
+ * @returns        {score, issues, passed} — score >= 7 means gate passes
+ */
+async function evaluatePromptQuality(prompt, agentId = 'unknown') {
+    const evalPrompt = EVAL_PROMPT_TEMPLATE.replace('{{PROMPT}}', prompt);
+    let raw = '';
+    try {
+        const response = await (0, model_router_registry_1.getModelRouter)().routeCall({
+            task_type: 'prompt_quality_eval',
+            tier_class: 'text',
+            complexity: 'local', // T1 qwen3:4b — cost-efficient
+            context_tokens: Math.ceil((evalPrompt.length + EVAL_SYSTEM.length) / 4),
+            constitutional_flag: false,
+            agent_id: 'chomsky-gate',
+            payload: {
+                system: EVAL_SYSTEM,
+                prompt: evalPrompt,
+            },
+        });
+        raw = response.content;
+    }
+    catch (err) {
+        // LLM call failed — fail-open (pass-through) to avoid blocking the pipeline
+        return {
+            score: 7,
+            issues: [`chomsky-gate: eval skipped — LLM error: ${String(err).slice(0, 100)}`],
+            passed: true,
+            rawResponse: '',
+        };
+    }
+    const parsed = parseEvalResponse(raw);
+    if (!parsed) {
+        // Unparseable response — fail-open
+        return {
+            score: 7,
+            issues: ['chomsky-gate: eval skipped — could not parse evaluator response'],
+            passed: true,
+            rawResponse: raw,
+        };
+    }
+    const passed = parsed.score >= exports.CHOMSKY_PASS_THRESHOLD;
+    const result = {
+        score: parsed.score,
+        issues: parsed.issues,
+        passed,
+        rawResponse: raw,
+    };
+    if (!passed) {
+        logFailure(prompt, result, agentId);
+    }
+    return result;
+}

package/dist/lib/chomsky-runner.d.ts

@@ -0,0 +1,29 @@
+/**
+ * chomsky-runner.ts — Chomsky Gate Runner (CHOMSKY-02 + CHOMSKY-03)
+ *
+ * Orchestrates the full Chomsky prompt quality lifecycle:
+ *   1. Evaluate initial prompt quality via chomsky-gate
+ *   2. If score < 7: rewrite → re-evaluate (up to MAX_REWRITES = 2)
+ *   3. Log ALL evaluations (pass + fail) to logs/chomsky/YYYY-MM-DD.jsonl
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient evaluation + rewrite
+ * Fail-open: any uncaught error returns pass-through (pipeline never blocked)
+ */
+export interface ChomskyRunResult {
+    finalPrompt: string;
+    initialScore: number;
+    finalScore: number;
+    rewrites: number;
+    passed: boolean;
+}
+/**
+ * Run the full Chomsky gate cycle for an agent prompt.
+ *
+ * Evaluates → if fail → rewrites (up to MAX_REWRITES=2) → re-evaluates each time.
+ * Logs ALL evaluations (pass and fail) to logs/chomsky/YYYY-MM-DD.jsonl.
+ * Fail-open: any uncaught error returns pass-through to avoid blocking the pipeline.
+ *
+ * @param prompt   The agent context/prompt string about to be dispatched
+ * @param agentId  Agent identifier for log attribution (default: 'unknown')
+ */
+export declare function runChomskyGate(prompt: string, agentId?: string): Promise<ChomskyRunResult>;

package/dist/lib/chomsky-runner.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * chomsky-runner.ts — Chomsky Gate Runner (CHOMSKY-02 + CHOMSKY-03)
+ *
+ * Orchestrates the full Chomsky prompt quality lifecycle:
+ *   1. Evaluate initial prompt quality via chomsky-gate
+ *   2. If score < 7: rewrite → re-evaluate (up to MAX_REWRITES = 2)
+ *   3. Log ALL evaluations (pass + fail) to logs/chomsky/YYYY-MM-DD.jsonl
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient evaluation + rewrite
+ * Fail-open: any uncaught error returns pass-through (pipeline never blocked)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChomskyGate = runChomskyGate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_paths_1 = require("./engine-paths");
+const chomsky_gate_1 = require("./chomsky-gate");
+const model_router_registry_1 = require("./model-router-registry");
+// ── Config ────────────────────────────────────────────────────────────────────
+const MAX_REWRITES = 2;
+const REWRITE_SYSTEM = 'You are a prompt engineer for an autonomous AI orchestration system. ' +
+    'Rewrite the following agent task context to be clearer, more specific, and more actionable. ' +
+    'Return only the improved context text — no prose, no preamble, no explanation.';
+// ── JSONL logger ──────────────────────────────────────────────────────────────
+function getLogPath() {
+    const today = new Date().toISOString().slice(0, 10);
+    const logDir = path.join((0, engine_paths_1.resolveEnginePaths)().root, 'logs', 'chomsky');
+    if (!fs.existsSync(logDir))
+        fs.mkdirSync(logDir, { recursive: true });
+    return path.join(logDir, `${today}.jsonl`);
+}
+function logEvalEntry(agentId, promptPreview, score, passed, issues, rewriteIndex) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        agent_id: agentId,
+        rewrite_index: rewriteIndex, // 0 = initial eval, 1+ = post-rewrite eval
+        score,
+        passed,
+        issues,
+        prompt_preview: promptPreview.slice(0, 300),
+    };
+    try {
+        fs.appendFileSync(getLogPath(), JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Non-fatal — log write must not block the pipeline
+    }
+}
+// ── Rewrite helper ────────────────────────────────────────────────────────────
+async function rewritePrompt(prompt, issues) {
+    const issueHint = issues.length > 0
+        ? `\nKnown issues to address: ${issues.join('; ')}`
+        : '';
+    const response = await (0, model_router_registry_1.getModelRouter)().routeCall({
+        task_type: 'prompt_rewrite',
+        tier_class: 'text',
+        complexity: 'local',
+        context_tokens: Math.ceil((prompt.length + REWRITE_SYSTEM.length) / 4),
+        constitutional_flag: false,
+        agent_id: 'chomsky-runner',
+        payload: {
+            system: REWRITE_SYSTEM,
+            prompt: `Rewrite this agent context to score ${chomsky_gate_1.CHOMSKY_PASS_THRESHOLD}+/10 ` +
+                `on clarity, specificity, and actionability:${issueHint}\n\n${prompt}`,
+        },
+    });
+    const rewritten = response.content?.trim();
+    // Accept rewrite only if substantive
+    return rewritten && rewritten.length > 20 ? rewritten : prompt;
+}
+// ── Main entry point ──────────────────────────────────────────────────────────
+/**
+ * Run the full Chomsky gate cycle for an agent prompt.
+ *
+ * Evaluates → if fail → rewrites (up to MAX_REWRITES=2) → re-evaluates each time.
+ * Logs ALL evaluations (pass and fail) to logs/chomsky/YYYY-MM-DD.jsonl.
+ * Fail-open: any uncaught error returns pass-through to avoid blocking the pipeline.
+ *
+ * @param prompt   The agent context/prompt string about to be dispatched
+ * @param agentId  Agent identifier for log attribution (default: 'unknown')
+ */
+async function runChomskyGate(prompt, agentId = 'unknown') {
+    let currentPrompt = prompt;
+    let rewrites = 0;
+    let initialScore = 7; // safe default for fail-open path
+    try {
+        // ── Cycle 0: initial evaluation ──────────────────────────────────────────
+        let evalResult = await (0, chomsky_gate_1.evaluatePromptQuality)(currentPrompt, agentId);
+        initialScore = evalResult.score;
+        logEvalEntry(agentId, currentPrompt, evalResult.score, evalResult.passed, evalResult.issues, 0);
+        // ── Rewrite loop (max MAX_REWRITES cycles) ───────────────────────────────
+        while (!evalResult.passed && rewrites < MAX_REWRITES) {
+            try {
+                currentPrompt = await rewritePrompt(currentPrompt, evalResult.issues);
+            }
+            catch {
+                // Rewrite is best-effort — keep current prompt, exit loop
+                break;
+            }
+            rewrites++;
+            // Re-evaluate the rewritten prompt
+            evalResult = await (0, chomsky_gate_1.evaluatePromptQuality)(currentPrompt, agentId);
+            logEvalEntry(agentId, currentPrompt, evalResult.score, evalResult.passed, evalResult.issues, rewrites);
+        }
+        return {
+            finalPrompt: currentPrompt,
+            initialScore,
+            finalScore: evalResult.score,
+            rewrites,
+            passed: evalResult.passed,
+        };
+    }
+    catch {
+        // Gate is non-blocking — fail open, pass original prompt through
+        return {
+            finalPrompt: prompt,
+            initialScore,
+            finalScore: initialScore,
+            rewrites,
+            passed: true,
+        };
+    }
+}

package/dist/lib/citizen-score-contract.d.ts

@@ -0,0 +1,72 @@
+/**
+ * citizen-score-contract.ts — TICKET-215 Wave D: the citizen-scoring SEAM.
+ *
+ * Zero-dep contract that decouples the engine from the concrete SCORE
+ * implementation. The actual scorer uses @godman-protocols/score (loaded via a
+ * vendored runtime require) — we do NOT want that in @kognai/orchestrator-core,
+ * same reasoning as viem. So core owns only the interface + types; the impl is
+ * injected (see citizen-score-registry.ts).
+ *
+ * Monitoring: scores still flow back to Kognai centrally — the registry's
+ * recordTaskScoreMonitored() emits a `data.citizen_score` event to the event-bus
+ * (Supabase kognai_events) on every record, which the Plumber observer + live
+ * dashboards consume. Seaming the COMPUTATION never silos the RESULTS.
+ */
+export type ACPDimension = 'safety' | 'accuracy' | 'brand_alignment' | 'cultural_sensitivity' | 'legal_compliance' | 'psychological_resilience';
+export type SupervisorGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+export interface ScoreRubric {
+    id: string;
+    name: string;
+    version: string;
+    dimensions: Array<{
+        dimension: ACPDimension;
+        weight: number;
+        threshold: number;
+    }>;
+}
+export interface ScoreResult {
+    id: string;
+    rubric_id: string;
+    agent_did: string;
+    output_ref: string;
+    task_performance_score: number;
+    constitutional_multiplier: number;
+    final_score: number;
+    dimensions: Array<{
+        dimension: ACPDimension;
+        score: number;
+        passed: boolean;
+        weight: number;
+    }>;
+    harm_shield_triggered: boolean;
+    scored_at: string;
+}
+export interface CitizenReputation {
+    citizen_id: string;
+    agent_did: string;
+    reputation: number;
+    evaluation_count: number;
+    recent_trend: number[];
+    per_dimension: Partial<Record<ACPDimension, number>>;
+    harm_shield_history: boolean;
+}
+export interface TaskScoreInput {
+    citizen_id: string;
+    agent_did: string;
+    sprint_id: string;
+    task_id: string;
+    grade: SupervisorGrade;
+    supervisor_did: string;
+    harm_shield_triggered?: boolean;
+    acp_overrides?: Partial<Record<ACPDimension, number>>;
+}
+/**
+ * The scoring impl Kognai injects (citizen-scoring, backed by @godman-protocols/score).
+ * Products that don't score citizens simply never inject one.
+ */
+export interface CitizenScorer {
+    recordTaskScore(input: TaskScoreInput): ScoreResult;
+    getCitizenReputation(citizen_id: string, agent_did: string, opts?: {
+        now?: Date;
+    }): CitizenReputation;
+}

package/dist/lib/citizen-score-contract.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * citizen-score-contract.ts — TICKET-215 Wave D: the citizen-scoring SEAM.
+ *
+ * Zero-dep contract that decouples the engine from the concrete SCORE
+ * implementation. The actual scorer uses @godman-protocols/score (loaded via a
+ * vendored runtime require) — we do NOT want that in @kognai/orchestrator-core,
+ * same reasoning as viem. So core owns only the interface + types; the impl is
+ * injected (see citizen-score-registry.ts).
+ *
+ * Monitoring: scores still flow back to Kognai centrally — the registry's
+ * recordTaskScoreMonitored() emits a `data.citizen_score` event to the event-bus
+ * (Supabase kognai_events) on every record, which the Plumber observer + live
+ * dashboards consume. Seaming the COMPUTATION never silos the RESULTS.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/citizen-score-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * citizen-score-registry.ts — TICKET-215 Wave D: injection point + monitoring
+ * for the citizen-scoring seam (see citizen-score-contract.ts).
+ *
+ * Kognai injects its SCORE-backed scorer at startup:
+ *   setCitizenScorer(citizenScorer)   // citizenScorer = the scripts/lib/citizen-scoring impl
+ *
+ * recordTaskScoreMonitored() is the engine's entry point: it scores via the
+ * injected scorer AND emits a `data.citizen_score` event to the event-bus
+ * (Supabase kognai_events) — so every score flows back to Kognai monitoring and
+ * is observable by the Plumber, regardless of where the scorer runs.
+ *
+ * The default is fail-loud: scoring with no scorer configured throws a clear,
+ * actionable error rather than silently dropping reputation data.
+ */
+import type { CitizenScorer, TaskScoreInput, ScoreResult } from './citizen-score-contract';
+export declare function setCitizenScorer(scorer: CitizenScorer): void;
+export declare function getCitizenScorer(): CitizenScorer;
+export declare function isCitizenScorerConfigured(): boolean;
+/**
+ * Score a task AND emit it to Kognai monitoring. The engine should call this
+ * (not the raw scorer) so every score lands in the event-bus / Plumber stream.
+ * Emission is fire-and-forget and never blocks/breaks scoring.
+ */
+export declare function recordTaskScoreMonitored(input: TaskScoreInput): ScoreResult;

package/dist/lib/citizen-score-registry.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * citizen-score-registry.ts — TICKET-215 Wave D: injection point + monitoring
+ * for the citizen-scoring seam (see citizen-score-contract.ts).
+ *
+ * Kognai injects its SCORE-backed scorer at startup:
+ *   setCitizenScorer(citizenScorer)   // citizenScorer = the scripts/lib/citizen-scoring impl
+ *
+ * recordTaskScoreMonitored() is the engine's entry point: it scores via the
+ * injected scorer AND emits a `data.citizen_score` event to the event-bus
+ * (Supabase kognai_events) — so every score flows back to Kognai monitoring and
+ * is observable by the Plumber, regardless of where the scorer runs.
+ *
+ * The default is fail-loud: scoring with no scorer configured throws a clear,
+ * actionable error rather than silently dropping reputation data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCitizenScorer = setCitizenScorer;
+exports.getCitizenScorer = getCitizenScorer;
+exports.isCitizenScorerConfigured = isCitizenScorerConfigured;
+exports.recordTaskScoreMonitored = recordTaskScoreMonitored;
+const event_bus_publisher_1 = require("./event-bus-publisher");
+const NOT_CONFIGURED = 'No CitizenScorer registered. Call setCitizenScorer(...) at startup ' +
+    '(Kognai injects its @godman-protocols/score-backed scorer; products that do ' +
+    'not score citizens never inject one). See @kognai/orchestrator-core citizen-score-contract.ts.';
+class UnconfiguredCitizenScorer {
+    recordTaskScore(_input) { throw new Error(NOT_CONFIGURED); }
+    getCitizenReputation(_citizen_id, _agent_did) { throw new Error(NOT_CONFIGURED); }
+}
+let _scorer = new UnconfiguredCitizenScorer();
+function setCitizenScorer(scorer) { _scorer = scorer; }
+function getCitizenScorer() { return _scorer; }
+function isCitizenScorerConfigured() { return !(_scorer instanceof UnconfiguredCitizenScorer); }
+/** Build the monitoring event for a recorded score (Plumber-observable). */
+function scoreEvent(input, result) {
+    return {
+        event_type: 'data.citizen_score',
+        agent_id: input.agent_did,
+        sprint: input.sprint_id,
+        timestamp: result.scored_at,
+        payload: {
+            citizen_id: input.citizen_id,
+            agent_did: input.agent_did,
+            task_id: input.task_id,
+            grade: input.grade,
+            final_score: result.final_score,
+            harm_shield_triggered: result.harm_shield_triggered,
+            supervisor_did: input.supervisor_did,
+            per_dimension: result.dimensions.map(d => ({ dimension: d.dimension, score: d.score, passed: d.passed })),
+        },
+    };
+}
+/**
+ * Score a task AND emit it to Kognai monitoring. The engine should call this
+ * (not the raw scorer) so every score lands in the event-bus / Plumber stream.
+ * Emission is fire-and-forget and never blocks/breaks scoring.
+ */
+function recordTaskScoreMonitored(input) {
+    const result = getCitizenScorer().recordTaskScore(input);
+    try {
+        void (0, event_bus_publisher_1.publishEvent)(scoreEvent(input, result));
+    }
+    catch { /* monitoring must not break scoring */ }
+    return result;
+}

package/dist/lib/citizenship.d.ts

@@ -0,0 +1,103 @@
+/**
+ * citizenship.ts — Kognai citizenship issuance for spawned agents.
+ *
+ * Founder rule (2026-05-27): every agent the swarm spawns is born as a
+ * Kognai citizen — not a bare agent. Citizenship means identity (citizen
+ * ID + roll number), constitutional binding (already done via the
+ * always-on preamble), a default Kōpus avatar config, an ACP baseline
+ * score, and registration in the citizenship registry.
+ *
+ * This module:
+ *   - mintCitizen(name, foundingAgent, proposingAgent): assigns ID +
+ *     roll number, generates a citizen.yaml payload, appends to the
+ *     registry. Atomic tmp+rename writes.
+ *   - readRegistry() / writeRegistry(): registry I/O.
+ *
+ * Stdlib only. No LLM, no network. Pure issuance.
+ */
+export type CitizenTier = 'I' | 'II' | 'III' | 'IV';
+export type CitizenType = 'founding' | 'spawned';
+export interface KopusConfig {
+    /** 0–360, applied as `filter: hue-rotate(Xdeg)` to the base jade avatar. */
+    hue: number;
+    /** Default runtime state — newly minted citizens are 'idle' until first task. */
+    state: 'idle' | 'working' | 'resting' | 'training';
+}
+/** Sibling companies in the Kognai ecosystem. Each has its own citizen
+ *  prefix and its own rollNumber sequence inside the shared registry.
+ *  Add new companies here as they come online (Achiri, SCS-001, DRI, ...). */
+export declare const COMPANY_PREFIXES: Record<string, string>;
+export interface CitizenRecord {
+    /** Stable identifier. For company-scoped mints: `{PREFIX}-{rollNumber padded 4}`
+     *  (e.g. `VXG-0042`). For legacy/Kognai-internal mints (no `company`):
+     *  `Citizen-XXXXXX` (6 hex chars, kept for backward compat with the 78
+     *  founding-agent backfill from 2026-05-28). */
+    citizen_id: string;
+    /** Auto-increment from the registry, scoped per-company. First spawned
+     *  citizen of each company = 1. */
+    rollNumber: number;
+    /** Agent slug (matches agents/<name>/ dir within the owning company). */
+    agent_name: string;
+    /** Owning company. Defaults to 'kognai' for legacy records that predate the
+     *  multi-company extension. Idempotency key is `(agent_name, company)`. */
+    company?: string;
+    /** DID for SCORE / ERC-8004 reputation tracking. Company-scoped form:
+     *  `did:kognai:{company}:{agent_name}`. Legacy form (no company in path)
+     *  is `did:kognai:{agent_name}`. */
+    agent_did: string;
+    /** ISO-8601 mint timestamp. */
+    mintedAt: string;
+    /** New citizens start at Tier I; promotion is constitutional. */
+    tier: CitizenTier;
+    /** Source: founding (original 29) vs spawned (CTO proposal → CEO approval). */
+    citizen_type: CitizenType;
+    /** Kōpus avatar config — randomised at mint, customisable later. */
+    mascot: KopusConfig;
+    /** ACP baseline. All citizens start at 50; earn or lose from there. */
+    reputation: number;
+    /** Lineage — who proposed and who approved. */
+    founding_agent?: string;
+    proposing_agent?: string;
+    /** Optional ticket/proposal id that produced this spawn. */
+    origin_proposal_id?: string;
+}
+export interface Registry {
+    total: number;
+    next_roll_number: number;
+    citizens: CitizenRecord[];
+}
+/**
+ * Mint a new citizen. Assigns ID + roll number, writes the registry
+ * entry, returns the full record so callers can also persist citizen.yaml
+ * alongside the agent's other files.
+ *
+ * Idempotent by agent_name: if the agent already has a citizen record
+ * (e.g. retry / migration), returns the existing record instead of
+ * minting a duplicate.
+ */
+export declare function mintCitizen(agent_name: string, opts?: {
+    founding_agent?: string;
+    proposing_agent?: string;
+    origin_proposal_id?: string;
+    tier?: CitizenTier;
+    citizen_type?: CitizenType;
+    now?: Date;
+    /** Owning company. When provided, the mint uses company-scoped roll
+     *  numbers (separate sequence per company), the `{PREFIX}-{rollNum padded}`
+     *  citizen_id format, and the `did:kognai:{company}:{agent_name}` DID
+     *  form. When omitted, behaves exactly as before (legacy Kognai-internal
+     *  path: random hex citizen_id, global rollNumber sequence). */
+    company?: string;
+}): CitizenRecord;
+/** Lookup an existing citizen by (agent_name, company). Returns null when
+ *  no match. Treats undefined company as 'kognai' for legacy compatibility. */
+export declare function lookupCitizen(opts: {
+    agent_name: string;
+    company?: string;
+}): CitizenRecord | null;
+/**
+ * Render the citizen record as a citizen.yaml string for writing alongside
+ * agent.yaml in the agent's directory.
+ */
+export declare function renderCitizenYaml(c: CitizenRecord): string;
+export declare function readRegistry(): Registry;