@kognai/orchestrator-core 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export * from './lib/trust-score-updater';
 export * from './lib/citizenship';
 export * from './lib/agent-registry';
 export * from './lib/sprint-state';
+export * from './lib/build-triage';
 export * as ksl from './lib/ksl';
 export * from './lib/wallet-state';
 export * from './lib/ceo-wallet';

package/dist/index.js

@@ -82,6 +82,9 @@ __exportStar(require("./lib/citizenship"), exports);
 __exportStar(require("./lib/agent-registry"), exports);
 // TICKET-098 sprint runtime-state split (committed defs vs gitignored status).
 __exportStar(require("./lib/sprint-state"), exports);
+// TICKET-234 build triage seam — classifyBuildPath (ceremony-depth axis) +
+// logBuildTriage. Consumed by the orchestrator run loop AND by kognai-build.
+__exportStar(require("./lib/build-triage"), exports);
 // Phase 3b-3 Wave B: KSL capture cluster (session records + error log + tap).
 // Namespaced ('ksl.tapAttempt', 'ksl.writeRecord', 'ksl.record', …) to keep the
 // generic 'record' export off the package's flat public surface.

package/dist/lib/build-triage.d.ts

@@ -0,0 +1,27 @@
+export type BuildPath = 'regulated' | 'fast';
+export interface BuildTriageResult {
+    path: BuildPath;
+    reason: string;
+    triggers: string[];
+    sensitive: boolean;
+    sovereign: boolean;
+    complexity: 'low' | 'medium' | 'high';
+    taskCount: number;
+    codeFileCount: number;
+}
+/**
+ * Classify a build into a ceremony-depth path. Pure + synchronous: it only reads
+ * the sprint JSON + task list, so it adds negligible cost relative to the
+ * ceremony it gates. Default-to-regulated on uncertainty.
+ *
+ * @param sprint  the raw sprint object (may carry regulated/strict/fast_track/sovereign flags)
+ * @param tasks   the loaded task list (each with deliverables/context/type)
+ */
+export declare function classifyBuildPath(sprint: any, tasks: any[]): BuildTriageResult;
+/**
+ * Append the triage decision to logs/routing/triage.jsonl (location-independent
+ * via engine-paths). Best-effort: never throws into the run loop. This is the
+ * audit trail required by the ticket — evidence that triage routes correctly and
+ * the means to audit any fast-tracked build later.
+ */
+export declare function logBuildTriage(sprintId: string, result: BuildTriageResult): void;

package/dist/lib/build-triage.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyBuildPath = classifyBuildPath;
+exports.logBuildTriage = logBuildTriage;
+/**
+ * build-triage.ts — TICKET-234: pre-orchestrator build triage (ceremony-depth axis).
+ *
+ * The orchestrator historically ran the SAME full ceremony for every build
+ * regardless of complexity or sensitivity (CEO assessment → execution →
+ * dual-supervisor review → CTO data analysis → CEO proposal cycle → post-sprint
+ * + agent minting). A 3-line `addTwo` cost 171s + the entire ceremony.
+ *
+ * This module adds a cheap classifier that runs BEFORE the orchestrator hands
+ * off to the swarm and routes the build to one of two execution paths:
+ *
+ *   - REGULATED (full ceremony) — CEO · CTO governance gate · dual-supervisor
+ *     review · reconciliation · the full CTO/CEO proposal cycle. Templates apply
+ *     on this path only. For sensitive / sovereign / complex builds.
+ *
+ *   - FAST  — coder → single-supervisor review → the minimum safety/security/
+ *     quality gate (QA gate: typecheck/compile/no-secrets, always on). No
+ *     dual-supervisor, no CTO/CEO post-sprint ceremony, no templates. For
+ *     simple, low-stakes, single-file, non-sensitive builds.
+ *
+ * It is the CEREMONY-DEPTH axis. It composes WITH `assessTaskComplexity`
+ * (engine-helpers), which scores the MODEL-ROUTING axis — they are orthogonal:
+ * a fast-tracked build can still route to a cloud model, and a regulated build
+ * can still run local. This stays a PURE HEURISTIC (no LLM call) so the triage
+ * never reintroduces the overhead it removes.
+ *
+ * Safety invariant: DEFAULT TO REGULATED on any uncertainty. `fast` is returned
+ * only when the build is provably simple AND non-sensitive AND non-sovereign.
+ * A `fast_track` opt-in never lowers the safety floor — sensitivity/complexity
+ * still force REGULATED.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+// Sensitivity keywords — PHI/PII, payments/financial, auth/secrets/credentials,
+// crypto/on-chain/contracts, destructive or privileged operations. A match in a
+// deliverable path, task context, or sprint goal forces REGULATED.
+const SENSITIVE_KEYWORDS = [
+    // auth / secrets / credentials
+    'auth', 'secret', 'credential', 'password', 'passwd', 'api[_-]?key', 'apikey',
+    'access[_-]?token', 'private[_-]?key', 'privatekey', 'seed[_-]?phrase', 'mnemonic',
+    'oauth', 'jwt', 'session[_-]?token', 'vault',
+    // payments / financial
+    'payment', 'billing', 'invoice', 'payout', 'stripe', 'paypal', 'charge', 'refund',
+    'kyc', 'ledger', 'wallet', 'pricing',
+    // crypto / on-chain / contracts
+    'x402', 'crypto', 'on[_-]?chain', 'onchain', 'blockchain', 'smart[_-]?contract',
+    'erc20', 'erc-20', 'usdc', '\\$kog', 'viem', 'web3',
+    // PHI / PII / regulated data
+    '\\bphi\\b', '\\bpii\\b', 'gdpr', 'hipaa', 'personal[_-]?data', 'health[_-]?record',
+    // schema / data migrations (high-blast-radius, hard to roll back)
+    'migration', 'prisma/migrations', 'drop[_-]?table', 'alter[_-]?table',
+];
+// Destructive / privileged operations — context-level matches force REGULATED.
+const DESTRUCTIVE_KEYWORDS = [
+    'rm\\s+-rf', 'drop\\s+table', 'delete\\s+from', 'truncate\\s+table',
+    'force[_-]?push', '--force', 'chmod\\s+777', 'sudo\\b', 'kill\\s+-9',
+];
+// Sensitive directories — a deliverable under one of these forces REGULATED.
+const SENSITIVE_DIRS = [
+    'banks/', 'wallet', 'ceo-wallet', 'gates/', 'policy/', 'contracts/', 'omel/',
+    'x402-base/', 'prisma/', 'credential', '.env', 'auth/', 'secrets/',
+];
+// Architectural / cross-cutting keywords — a match means the change is not a
+// simple single-concern build → REGULATED.
+const ARCHITECTURAL_KEYWORDS = [
+    'architect', 'refactor', 'migrate', 'cross[_-]?cutting', 'system[_-]?wide',
+    'redesign', 'database', 'schema', 'infrastructure', 'orchestrat', 'pipeline',
+    'framework', 'breaking[_-]?change', 'rewrite',
+];
+function compile(words) {
+    return new RegExp(`(${words.join('|')})`, 'i');
+}
+const SENSITIVE_RE = compile(SENSITIVE_KEYWORDS);
+const DESTRUCTIVE_RE = compile(DESTRUCTIVE_KEYWORDS);
+const ARCH_RE = compile(ARCHITECTURAL_KEYWORDS);
+function asBool(v) {
+    return v === true || v === 'true' || v === 1 || v === '1';
+}
+/**
+ * Classify a build into a ceremony-depth path. Pure + synchronous: it only reads
+ * the sprint JSON + task list, so it adds negligible cost relative to the
+ * ceremony it gates. Default-to-regulated on uncertainty.
+ *
+ * @param sprint  the raw sprint object (may carry regulated/strict/fast_track/sovereign flags)
+ * @param tasks   the loaded task list (each with deliverables/context/type)
+ */
+function classifyBuildPath(sprint, tasks) {
+    const triggers = [];
+    const taskList = Array.isArray(tasks) ? tasks : [];
+    const taskCount = taskList.length;
+    // Gather all the text we scan for sensitivity/architecture signals.
+    const deliverablePaths = [];
+    const codeFiles = [];
+    for (const t of taskList) {
+        const d = (t && t.deliverables) || {};
+        const code = Array.isArray(d.code) ? d.code : [];
+        const tests = Array.isArray(d.tests) ? d.tests : [];
+        const docs = Array.isArray(d.docs) ? d.docs : [];
+        codeFiles.push(...code);
+        deliverablePaths.push(...code, ...tests, ...docs);
+    }
+    const codeFileCount = new Set(codeFiles).size;
+    const contextText = taskList
+        .map((t) => `${(t && (t.context || t.title || t.id)) || ''} ${(t && (t.type || t.task_type)) || ''}`)
+        .join(' ');
+    const goalText = `${sprint?.name || sprint?.title || ''} ${sprint?.goal || sprint?.description || ''}`;
+    const pathText = deliverablePaths.join(' ');
+    const haystack = `${goalText} ${contextText} ${pathText}`;
+    // ── Explicit flags ────────────────────────────────────────────────────────
+    const forcedRegulated = asBool(sprint?.regulated) || asBool(sprint?.strict) || asBool(process.env.KOGNAI_FORCE_REGULATED);
+    const requestedFast = asBool(sprint?.fast_track) || asBool(sprint?.fast);
+    if (forcedRegulated)
+        triggers.push('explicit:regulated');
+    // ── Sensitivity ───────────────────────────────────────────────────────────
+    let sensitive = false;
+    if (SENSITIVE_RE.test(haystack)) {
+        sensitive = true;
+        triggers.push(`sensitive:keyword(${(haystack.match(SENSITIVE_RE) || [])[1]})`);
+    }
+    if (DESTRUCTIVE_RE.test(haystack)) {
+        sensitive = true;
+        triggers.push(`sensitive:destructive(${(haystack.match(DESTRUCTIVE_RE) || [])[1]})`);
+    }
+    const dirHit = SENSITIVE_DIRS.find((dir) => pathText.toLowerCase().includes(dir.toLowerCase()));
+    if (dirHit) {
+        sensitive = true;
+        triggers.push(`sensitive:path(${dirHit})`);
+    }
+    // ── Sovereign / regulated domain ──────────────────────────────────────────
+    const sovereign = asBool(sprint?.sovereign) || asBool(sprint?.regulated_domain);
+    if (sovereign)
+        triggers.push('sovereign');
+    // ── Complexity (ceremony-depth, NOT model routing) ────────────────────────
+    const estimated = String(sprint?.estimated_complexity || '').toLowerCase();
+    const archHit = ARCH_RE.test(haystack);
+    if (archHit)
+        triggers.push(`complex:architectural(${(haystack.match(ARCH_RE) || [])[1]})`);
+    if (taskCount > 1)
+        triggers.push(`complex:multi-task(${taskCount})`);
+    if (codeFileCount > 1)
+        triggers.push(`complex:multi-file(${codeFileCount})`);
+    if (estimated === 'high')
+        triggers.push('complex:estimated-high');
+    let complexity = 'low';
+    if (archHit || taskCount > 2 || codeFileCount > 2 || estimated === 'high')
+        complexity = 'high';
+    else if (taskCount > 1 || codeFileCount > 1 || estimated === 'medium')
+        complexity = 'medium';
+    // ── Decision (default-to-regulated) ───────────────────────────────────────
+    // A build is FAST-eligible only if it is provably simple AND nothing sensitive
+    // / sovereign / forced fired. Anything ambiguous → REGULATED.
+    const isSimple = taskCount === 1 && codeFileCount <= 1 && !archHit && estimated !== 'high';
+    const blockFast = forcedRegulated || sensitive || sovereign || !isSimple;
+    let path;
+    let reason;
+    if (blockFast) {
+        path = 'regulated';
+        reason =
+            forcedRegulated ? 'explicit --regulated/--strict flag'
+                : sensitive ? `sensitive build (${triggers.filter((t) => t.startsWith('sensitive')).join(', ')})`
+                    : sovereign ? 'sovereign / regulated-domain build'
+                        : `complexity above fast-track threshold (${triggers.filter((t) => t.startsWith('complex')).join(', ') || 'multi-concern'})`;
+    }
+    else {
+        path = 'fast';
+        reason = requestedFast
+            ? 'fast-track opt-in; simple non-sensitive single-file build'
+            : 'simple non-sensitive single-file build → fast track';
+    }
+    return { path, reason, triggers, sensitive, sovereign, complexity, taskCount, codeFileCount };
+}
+/**
+ * Append the triage decision to logs/routing/triage.jsonl (location-independent
+ * via engine-paths). Best-effort: never throws into the run loop. This is the
+ * audit trail required by the ticket — evidence that triage routes correctly and
+ * the means to audit any fast-tracked build later.
+ */
+function logBuildTriage(sprintId, result) {
+    try {
+        const file = (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)().logs, 'routing', 'triage.jsonl');
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(file), { recursive: true });
+        const row = {
+            sprint_id: sprintId,
+            path: result.path,
+            reason: result.reason,
+            triggers: result.triggers,
+            sensitive: result.sensitive,
+            sovereign: result.sovereign,
+            complexity: result.complexity,
+            task_count: result.taskCount,
+            code_file_count: result.codeFileCount,
+            logged_at: new Date().toISOString(),
+        };
+        (0, fs_1.appendFileSync)(file, JSON.stringify(row) + '\n');
+    }
+    catch { /* non-fatal — audit log must never break a run */ }
+}

package/dist/lib/citizenship.d.ts

@@ -27,6 +27,79 @@ export interface KopusConfig {
  *  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>;
+/**
+ * Who a spawned citizen *belongs to* — its lineage. SAF derives this from the
+ * spawn requester's DID so a new citizen inherits the requester's identity:
+ *   - `company`  internal product (kognai/voxight/invoica/kreativ/achiri/…). A
+ *                product CEO's spawn belongs to that company → `did:kognai:{company}:{agent}`.
+ *   - `external` an outside org (through the AMD-23 Cerberus airlock) →
+ *                `did:external:{org}:{agent}`.
+ *   - `user`     a human's wallet in the citizen journey. **Exactly ONE agent per
+ *                user per wallet** → `did:kognai:citizen:{wallet}`.
+ *   - `scs`      a Self-Committed Swarm a user's citizen forms. Sub-agents the
+ *                citizen spawns inherit the swarm's id → `did:kognai:scs:{scsId}:{agent}`.
+ */
+export type CitizenOwnerKind = 'company' | 'external' | 'user' | 'scs';
+export interface CitizenOwner {
+    kind: CitizenOwnerKind;
+    /** company name | external org id | user wallet | scs id. */
+    id: string;
+}
+/** The Default Instrumentation Posture (TICKET-150 / SOP-GEN-014) carried per
+ *  citizen: KSL monitoring + failure-log contribution + skill-bank participation. */
+export interface CitizenInstrumentation {
+    ksl: boolean;
+    failure_log: boolean;
+    skill_bank: boolean;
+}
+/**
+ * Posture by owner kind. **Internal** citizens (kognai + product companies) are
+ * born fully instrumented and bound to all constitutional duties — ON, mandatory.
+ * **External** orgs/swarms and **user** citizens (+ the SCS they form) get the
+ * same machinery baseline-available but OFF; they opt in (see citizenBenefits)
+ * for fee discounts and, for users, the improvement loop.
+ */
+export declare function defaultInstrumentation(owner_kind?: CitizenOwnerKind): CitizenInstrumentation;
+/** Kognai-fee discount (%) granted per shared channel an opt-in citizen enables.
+ *  Tunable Founder policy. */
+export declare const SHARE_DISCOUNT_PCT: {
+    failure_log: number;
+    skill_bank: number;
+};
+export interface CitizenBenefits {
+    /** % off Kognai fees for opting into sharing (external + user + scs). */
+    fee_discount_pct: number;
+    /** Users (+ their SCS) who share skills may use the skill bank for free. */
+    skill_bank_free_use: boolean;
+    /** Users (+ their SCS) who share failures get Plumber review of their work,
+     *  driven by failure-library findings. */
+    plumber_review: boolean;
+}
+/**
+ * Resolve the economic + improvement-loop benefits a citizen unlocks from its
+ * current instrumentation. Internal citizens are first-party (mandatory posture,
+ * no discount concept). External/user/scs earn a fee discount per shared channel;
+ * users (+ their SCS) additionally unlock free skill-bank use + Plumber review.
+ */
+export declare function citizenBenefits(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): CitizenBenefits;
+/** Apply a citizen's earned discount to a Kognai fee (atomic units). */
+export declare function applyCitizenDiscount(feeAtomic: number, c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): number;
+/** Skill-bank gate: may this citizen draw from the skill bank for free? */
+export declare function canUseSkillBankFree(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): boolean;
+/** Plumber gate: is this citizen's work eligible for failure-log-driven Plumber review? */
+export declare function eligibleForPlumberReview(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): boolean;
+/**
+ * Resolve an agent's canonical *instance* identity (DID + citizen_id) from the
+ * registry — the key failure-logging / KSL / SCORE must attribute to, instead of
+ * the role string (the TICKET-152 `agent_id="coder"` corruption). Returns null
+ * when the agent has no citizen record.
+ */
+export declare function identityFor(agent_name: string, company?: string): {
+    agent_did: string;
+    citizen_id: string;
+    owner_kind?: CitizenOwnerKind;
+    owner_id?: string;
+} | null;
 export interface CitizenRecord {
     /** Stable identifier. For company-scoped mints: `{PREFIX}-{rollNumber padded 4}`
      *  (e.g. `VXG-0042`). For legacy/Kognai-internal mints (no `company`):
@@ -39,12 +112,24 @@ export interface CitizenRecord {
     /** 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)`. */
+     *  multi-company extension. Idempotency key is `(agent_name, company)`.
+     *  Set only when owner_kind === 'company' (back-compat alias for owner_id). */
     company?: string;
+    /** Lineage owner kind — who this citizen belongs to (see CitizenOwner). */
+    owner_kind?: CitizenOwnerKind;
+    /** Lineage owner id — company name | external org | user wallet | scs id. */
+    owner_id?: string;
+    /** Default Instrumentation Posture (KSL / failure-log / skill-bank). Internal
+     *  citizens = all ON (mandatory); external/user/scs = baseline OFF, opt-in. */
+    instrumentation?: CitizenInstrumentation;
     /** 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;
+    /** Prior DID a citizen carried before a company-scoped re-mint (e.g. legacy
+     *  `did:kognai:{agent}`). Preserved so SCORE / ERC-8004 reputation history
+     *  keyed on the old DID isn't orphaned by the migration. */
+    legacy_did?: string;
     /** ISO-8601 mint timestamp. */
     mintedAt: string;
     /** New citizens start at Tier I; promotion is constitutional. */
@@ -82,12 +167,14 @@ export declare function mintCitizen(agent_name: string, opts?: {
     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). */
+    /** @deprecated prefer `owner: { kind:'company', id }`. Owning company —
+     *  back-compat alias that maps to owner kind 'company'. */
     company?: string;
+    /** Lineage owner — who the citizen belongs to. SAF derives this from the
+     *  spawn requester's DID so the new citizen inherits the requester's
+     *  identity (company / external org / user wallet / SCS). When omitted
+     *  (and no `company`), uses the legacy Kognai-internal path. */
+    owner?: CitizenOwner;
 }): CitizenRecord;
 /** Lookup an existing citizen by (agent_name, company). Returns null when
  *  no match. Treats undefined company as 'kognai' for legacy compatibility. */

package/dist/lib/citizenship.js

@@ -17,7 +17,13 @@
  * Stdlib only. No LLM, no network. Pure issuance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMPANY_PREFIXES = void 0;
+exports.SHARE_DISCOUNT_PCT = exports.COMPANY_PREFIXES = void 0;
+exports.defaultInstrumentation = defaultInstrumentation;
+exports.citizenBenefits = citizenBenefits;
+exports.applyCitizenDiscount = applyCitizenDiscount;
+exports.canUseSkillBankFree = canUseSkillBankFree;
+exports.eligibleForPlumberReview = eligibleForPlumberReview;
+exports.identityFor = identityFor;
 exports.mintCitizen = mintCitizen;
 exports.lookupCitizen = lookupCitizen;
 exports.renderCitizenYaml = renderCitizenYaml;
@@ -41,7 +47,84 @@ exports.COMPANY_PREFIXES = {
     kognai: 'KGN',
     voxight: 'VXG',
     invoica: 'INV',
+    kreativ: 'KRV', // Kognai Kreativ — SCS001 → creative studio (TICKET-158/306)
+    scs001: 'SCS', // legacy content swarm; folds into Kreativ as agents migrate
+    achiri: 'ACH', // Tunisia AI companion
+    asterpay: 'APY', // payments product
+    dri: 'DRI', // Dynamic Research Instrument (Phase 3)
 };
+/** citizen_id prefixes for the non-company owner kinds (company uses COMPANY_PREFIXES).
+ *  These use a GLOBAL per-kind roll sequence; the specific owner lives in the DID. */
+const OWNER_PREFIX = {
+    external: 'EXT',
+    user: 'CIT',
+    scs: 'SWM',
+};
+/**
+ * Posture by owner kind. **Internal** citizens (kognai + product companies) are
+ * born fully instrumented and bound to all constitutional duties — ON, mandatory.
+ * **External** orgs/swarms and **user** citizens (+ the SCS they form) get the
+ * same machinery baseline-available but OFF; they opt in (see citizenBenefits)
+ * for fee discounts and, for users, the improvement loop.
+ */
+function defaultInstrumentation(owner_kind) {
+    const internal = !owner_kind || owner_kind === 'company';
+    return { ksl: internal, failure_log: internal, skill_bank: internal };
+}
+/** Kognai-fee discount (%) granted per shared channel an opt-in citizen enables.
+ *  Tunable Founder policy. */
+exports.SHARE_DISCOUNT_PCT = { failure_log: 10, skill_bank: 10 };
+/**
+ * Resolve the economic + improvement-loop benefits a citizen unlocks from its
+ * current instrumentation. Internal citizens are first-party (mandatory posture,
+ * no discount concept). External/user/scs earn a fee discount per shared channel;
+ * users (+ their SCS) additionally unlock free skill-bank use + Plumber review.
+ */
+function citizenBenefits(c) {
+    const i = c.instrumentation ?? defaultInstrumentation(c.owner_kind);
+    const optInEligible = c.owner_kind === 'external' || c.owner_kind === 'user' || c.owner_kind === 'scs';
+    const isUser = c.owner_kind === 'user' || c.owner_kind === 'scs';
+    let discount = 0;
+    if (optInEligible) {
+        if (i.failure_log)
+            discount += exports.SHARE_DISCOUNT_PCT.failure_log;
+        if (i.skill_bank)
+            discount += exports.SHARE_DISCOUNT_PCT.skill_bank;
+    }
+    return {
+        fee_discount_pct: discount,
+        skill_bank_free_use: isUser && i.skill_bank,
+        plumber_review: isUser && i.failure_log,
+    };
+}
+// ─── citizenBenefits consumers (billing / skill-bank / plumber) ─────────────────
+// The integration surface for downstream systems. They call these instead of
+// re-deriving policy, so the discount/free-use/review rules live in one place.
+/** Apply a citizen's earned discount to a Kognai fee (atomic units). */
+function applyCitizenDiscount(feeAtomic, c) {
+    const pct = citizenBenefits(c).fee_discount_pct;
+    return Math.max(0, Math.round(feeAtomic * (1 - pct / 100)));
+}
+/** Skill-bank gate: may this citizen draw from the skill bank for free? */
+function canUseSkillBankFree(c) {
+    return citizenBenefits(c).skill_bank_free_use;
+}
+/** Plumber gate: is this citizen's work eligible for failure-log-driven Plumber review? */
+function eligibleForPlumberReview(c) {
+    return citizenBenefits(c).plumber_review;
+}
+/**
+ * Resolve an agent's canonical *instance* identity (DID + citizen_id) from the
+ * registry — the key failure-logging / KSL / SCORE must attribute to, instead of
+ * the role string (the TICKET-152 `agent_id="coder"` corruption). Returns null
+ * when the agent has no citizen record.
+ */
+function identityFor(agent_name, company) {
+    const c = lookupCitizen({ agent_name, company });
+    if (!c)
+        return null;
+    return { agent_did: c.agent_did, citizen_id: c.citizen_id, owner_kind: c.owner_kind, owner_id: c.owner_id };
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
  * Mint a new citizen. Assigns ID + roll number, writes the registry
@@ -65,26 +148,49 @@ function mintCitizen(agent_name, opts = {}) {
     // is a denormalized index that should always be derivable from them.
     reconcileFromDisk();
     const registry = readRegistry();
-    // Idempotency: lookup by (agent_name, company). Treat undefined company as
-    // 'kognai' so existing records (which predate the company field) match
-    // mints that explicitly target the kognai company.
-    const companyKey = opts.company; // undefined for legacy path
-    const existing = registry.citizens.find((c) => c.agent_name === agent_name && (c.company ?? 'kognai') === (companyKey ?? 'kognai'));
+    // Resolve lineage. `owner` wins; `company` is the back-compat alias; neither
+    // → legacy kognai-internal path (random hex id, global roll, did:kognai:{agent}).
+    const owner = opts.owner ?? (opts.company ? { kind: 'company', id: opts.company } : null);
+    // Idempotency. user → exactly ONE per wallet (key on owner_id only, ignoring
+    // agent_name — a wallet has a single citizen). company/external/scs →
+    // (agent_name, kind, owner_id). legacy → (agent_name, company='kognai').
+    const ownerIdOf = (c) => c.owner_id ?? c.company ?? 'kognai';
+    // Legacy records (no owner_kind) are company-scoped (kognai by default).
+    const ownerKindOf = (c) => c.owner_kind ?? 'company';
+    const existing = registry.citizens.find((c) => {
+        if (owner?.kind === 'user')
+            return c.owner_kind === 'user' && c.owner_id === owner.id;
+        if (owner)
+            return c.agent_name === agent_name && ownerKindOf(c) === owner.kind && ownerIdOf(c) === owner.id;
+        return c.agent_name === agent_name && (c.company ?? 'kognai') === 'kognai';
+    });
     if (existing)
         return existing;
     const now = opts.now ?? new Date();
     let citizen_id;
     let rollNumber;
     let agent_did;
-    if (companyKey) {
-        // Company-scoped path: per-company rollNumber, prefixed ID, scoped DID.
-        const prefix = exports.COMPANY_PREFIXES[companyKey] ?? companyKey.slice(0, 3).toUpperCase();
-        const companyRolls = registry.citizens
-            .filter((c) => (c.company ?? 'kognai') === companyKey)
+    if (owner?.kind === 'company') {
+        // Per-company rollNumber, COMPANY_PREFIXES id, did:kognai:{company}:{agent}.
+        const prefix = exports.COMPANY_PREFIXES[owner.id] ?? owner.id.slice(0, 3).toUpperCase();
+        const rolls = registry.citizens
+            .filter((c) => ownerKindOf(c) === 'company' && ownerIdOf(c) === owner.id)
             .map((c) => c.rollNumber);
-        rollNumber = companyRolls.length > 0 ? Math.max(...companyRolls) + 1 : 1;
+        rollNumber = rolls.length ? Math.max(...rolls) + 1 : 1;
         citizen_id = `${prefix}-${String(rollNumber).padStart(4, '0')}`;
-        agent_did = `did:kognai:${companyKey}:${agent_name}`;
+        agent_did = `did:kognai:${owner.id}:${agent_name}`;
+    }
+    else if (owner) {
+        // user / scs / external — GLOBAL per-kind roll; the specific owner lives in
+        // the DID. user: 1 per wallet → did:kognai:citizen:{wallet}.
+        const prefix = OWNER_PREFIX[owner.kind];
+        const rolls = registry.citizens.filter((c) => c.owner_kind === owner.kind).map((c) => c.rollNumber);
+        rollNumber = rolls.length ? Math.max(...rolls) + 1 : 1;
+        citizen_id = `${prefix}-${String(rollNumber).padStart(4, '0')}`;
+        agent_did =
+            owner.kind === 'user' ? `did:kognai:citizen:${owner.id}`
+                : owner.kind === 'scs' ? `did:kognai:scs:${owner.id}:${agent_name}`
+                    : `did:external:${owner.id}:${agent_name}`;
     }
     else {
         // Legacy Kognai-internal path: random hex ID + global rollNumber sequence.
@@ -96,7 +202,11 @@ function mintCitizen(agent_name, opts = {}) {
         citizen_id,
         rollNumber,
         agent_name,
-        ...(companyKey ? { company: companyKey } : {}),
+        ...(owner?.kind === 'company' ? { company: owner.id } : {}),
+        ...(owner ? { owner_kind: owner.kind, owner_id: owner.id } : {}),
+        // Every minted citizen carries the posture: internal ON, external/user/scs
+        // baseline-OFF (opt-in). KSL/failure-log/skill-bank + duties wire from this.
+        instrumentation: defaultInstrumentation(owner?.kind),
         agent_did,
         mintedAt: now.toISOString(),
         tier: opts.tier ?? 'I',
@@ -112,9 +222,9 @@ function mintCitizen(agent_name, opts = {}) {
     };
     registry.citizens.push(record);
     registry.total = registry.citizens.length;
-    // Only advance the global next_roll_number on legacy mints — company-scoped
-    // mints have their own per-company counter computed at mint time.
-    if (!companyKey)
+    // Advance the global next_roll_number only on the legacy path; owner-scoped
+    // mints compute their own roll at mint time.
+    if (!owner)
         registry.next_roll_number = rollNumber + 1;
     writeRegistry(registry);
     return record;
@@ -138,14 +248,17 @@ function renderCitizenYaml(c) {
 citizen_id: ${c.citizen_id}
 rollNumber: ${c.rollNumber}
 agent_name: ${c.agent_name}
-agent_did: ${c.agent_did}
-mintedAt: "${c.mintedAt}"
+${c.owner_kind ? `owner_kind: ${c.owner_kind}\n` : ''}${c.owner_id ? `owner_id: ${c.owner_id}\n` : ''}${c.company ? `company: ${c.company}\n` : ''}agent_did: ${c.agent_did}
+${c.legacy_did ? `legacy_did: ${c.legacy_did}\n` : ''}mintedAt: "${c.mintedAt}"
 tier: ${c.tier}
 citizen_type: ${c.citizen_type}
 mascot:
   hue: ${c.mascot.hue}
   state: ${c.mascot.state}
 reputation: ${c.reputation}
+instrumentation_ksl: ${c.instrumentation?.ksl ?? true}
+instrumentation_failure_log: ${c.instrumentation?.failure_log ?? true}
+instrumentation_skill_bank: ${c.instrumentation?.skill_bank ?? true}
 founding_agent: ${c.founding_agent ?? 'ceo'}
 proposing_agent: ${c.proposing_agent ?? 'cto'}
 ${c.origin_proposal_id ? `origin_proposal_id: ${c.origin_proposal_id}\n` : ''}`;
@@ -256,7 +369,11 @@ function parseCitizenYaml(raw) {
         citizen_id: flat.citizen_id,
         rollNumber: parseInt(flat.rollNumber, 10),
         agent_name: flat.agent_name,
+        ...(flat.company ? { company: flat.company } : {}),
+        ...(flat.owner_kind ? { owner_kind: flat.owner_kind } : {}),
+        ...(flat.owner_id ? { owner_id: flat.owner_id } : {}),
         agent_did: flat.agent_did || `did:kognai:${flat.agent_name}`,
+        ...(flat.legacy_did ? { legacy_did: flat.legacy_did } : {}),
         mintedAt: flat.mintedAt,
         tier: flat.tier || 'I',
         citizen_type: flat.citizen_type || 'spawned',
@@ -265,6 +382,13 @@ function parseCitizenYaml(raw) {
             state: mascot.state || 'idle',
         },
         reputation: flat.reputation ? parseInt(flat.reputation, 10) : 50,
+        instrumentation: flat.instrumentation_ksl !== undefined
+            ? {
+                ksl: flat.instrumentation_ksl === 'true',
+                failure_log: flat.instrumentation_failure_log === 'true',
+                skill_bank: flat.instrumentation_skill_bank === 'true',
+            }
+            : defaultInstrumentation(flat.owner_kind),
         founding_agent: flat.founding_agent,
         proposing_agent: flat.proposing_agent,
         origin_proposal_id: flat.origin_proposal_id,

package/dist/lib/engine-agents.d.ts

@@ -1,3 +1,4 @@
+import { type CitizenOwner } from './citizenship';
 import type { AgentTask, ReviewResult, CTOProposal, CTOReport } from './orchestrate-engine';
 export declare class SupervisorAgent {
     private systemPrompt;
@@ -62,6 +63,12 @@ export interface SpawnGateResult {
     pending_approval?: boolean;
     /** Optional one-line audit string logged on an approved decision. */
     audit?: string;
+    /** Lineage owner the gate resolved from the spawn requester (via SAF /
+     *  deriveOwner). When set, the engine mints the citizen owner-scoped instead
+     *  of legacy — so an Invoica swarm's spawn becomes an Invoica citizen, a
+     *  Voxight swarm's a Voxight citizen, etc. The running company is carried by
+     *  the template-injected gate's requester_did, not hardcoded in the engine. */
+    owner?: CitizenOwner;
 }
 export type SpawnGate = (spec: AgentSpawnSpec) => SpawnGateResult;
 export declare class AgentCreator {