@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/adapters/raw.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The adapter contract: what every source adapter emits before ingestion. Adapters are pure functions over pinned
+ * input (a parsed file); none of them fetches, installs or runs anything.
+ */
+import type { BusinessTier, JSONSchema, Lifecycle, Network, Origin, Pricing, PrivacyClass, SideEffect, ToolRecord } from '../types/tool';
+export interface RawOp {
+    op: string;
+    summary: string;
+    input_schema?: JSONSchema | null;
+    output_schema?: JSONSchema | null;
+    /** null or absent = unknown, which ingestion treats as network + data modification (never safe). */
+    side_effects?: SideEffect[] | null;
+    scopes?: string[];
+    idempotent?: boolean | null;
+    capabilities?: string[];
+    method?: string;
+    path?: string;
+}
+/** Where a descriptor came from; every adapter receives this from the caller. */
+export interface ProvenanceIn {
+    source: string;
+    retrieved_at: string;
+    licence: string | null;
+    snapshot_sha256: string;
+}
+export interface RawToolDescriptor {
+    source: string;
+    source_ref: string;
+    origin: Origin;
+    /** namespace/name for the tool id (ADR-004), before normalisation. */
+    path: string;
+    name: string;
+    description: string;
+    provider: {
+        name: string;
+        url?: string;
+        kognai_owned?: boolean;
+    };
+    category?: string;
+    tags?: string[];
+    operations: RawOp[];
+    auth?: ToolRecord['auth'];
+    pricing?: Pricing;
+    pricing_text?: string;
+    licence?: string | null;
+    endpoint?: string;
+    package?: {
+        registry: string;
+        identifier: string;
+        version?: string;
+    };
+    /** 'package' = code to install (never run by KTR), 'remote' = a hosted endpoint, 'native' = Kognai code in repo. */
+    implementation?: 'package' | 'remote' | 'native' | 'http' | 'metadata';
+    version?: string;
+    privacy_class?: PrivacyClass;
+    business_tier?: BusinessTier | null;
+    regions?: string[];
+    networks?: Network[];
+    product_id?: string;
+    /** The provider serves a valid AIAX manifest (checked by the caller; only true is carried into the record). */
+    aiax_ready?: boolean;
+    aliases?: string[];
+    skill_ids?: string[];
+    lifecycle?: Lifecycle;
+    dependencies?: string[];
+    /** A digest of the implementation when the source knows it (package version, file content of native code). */
+    implementation_hash?: string;
+    /** Tags the tool as a Kognai release path that keeps the Founder's approval (E4 publish exception). */
+    founder_approval?: boolean;
+    provenance: ProvenanceIn & {
+        adapter: string;
+        adapter_version: string;
+    };
+}
+export declare const prov: (p: ProvenanceIn, adapter: string, adapter_version: string) => {
+    adapter: string;
+    adapter_version: string;
+    source: string;
+    retrieved_at: string;
+    licence: string | null;
+    snapshot_sha256: string;
+};

package/dist/adapters/raw.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prov = void 0;
+const prov = (p, adapter, adapter_version) => ({ ...p, adapter, adapter_version });
+exports.prov = prov;

package/dist/adapters/x402-discovery.d.ts

@@ -0,0 +1,6 @@
+import type { Network } from '../types/tool';
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "x402-discovery";
+export declare const ADAPTER_VERSION = "1.0.0";
+export declare const networkOf: (n: unknown) => Network | null;
+export declare function fromX402Resources(items: unknown, p: ProvenanceIn, sourceName?: string): RawToolDescriptor[];

package/dist/adapters/x402-discovery.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.networkOf = exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.fromX402Resources = fromX402Resources;
+/**
+ * x402 discovery catalogs: PayAI (facilitator.payai.network/discovery/resources) and the Coinbase CDP Bazaar
+ * (api.cdp.coinbase.com/platform/v2/x402/discovery/resources). Accepts both the raw discovery items and the
+ * normalised resources Golden Kog keeps in its daily catalog (scripts/labor/golden-kog/intel.ts). The field mapping
+ * follows Golden Kog's (resource url, accepts[] offers in micro units, bazaar input), re-implemented here: the package
+ * imports nothing from scripts/. Payees are not copied into the catalog: an agent never chooses where money goes.
+ */
+const node_crypto_1 = require("node:crypto");
+const raw_1 = require("./raw");
+exports.ADAPTER = 'x402-discovery';
+exports.ADAPTER_VERSION = '1.0.0';
+const CAIP = {
+    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': 'solana',
+    'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1': 'solana-devnet',
+    'eip155:8453': 'base',
+    'eip155:84532': 'base-sepolia',
+    solana: 'solana', base: 'base', 'base-sepolia': 'base-sepolia', 'solana-devnet': 'solana-devnet',
+};
+const networkOf = (n) => CAIP[String(n || '')] || null;
+exports.networkOf = networkOf;
+function schemaFromInput(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const properties = {};
+    const fromShape = (o) => {
+        if (!o || typeof o !== 'object')
+            return;
+        const props = o.properties && typeof o.properties === 'object' ? o.properties : o;
+        for (const [k, v] of Object.entries(props)) {
+            if (k === 'type' || k === 'required' || k === 'properties')
+                continue;
+            properties[k] = v && typeof v === 'object' && typeof v.type === 'string' ? { type: v.type, ...(v.description ? { description: String(v.description).slice(0, 200) } : {}) } : { type: typeof v === 'number' ? 'number' : 'string' };
+        }
+    };
+    fromShape(input.queryParams);
+    fromShape(input.body);
+    const required = Array.isArray(input.required) ? input.required.map(String) : [];
+    if (!Object.keys(properties).length && !required.length)
+        return null;
+    return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+/** One item, raw (resource string, accepts[]) or Golden Kog normalised (url, offers[]). */
+function norm(it) {
+    const url = String(typeof it?.resource === 'string' ? it.resource : it?.url || it?.resource?.url || '');
+    if (!/^https:\/\//i.test(url))
+        return null;
+    const offers = Array.isArray(it.accepts) ? it.accepts : Array.isArray(it.offers) ? it.offers : [];
+    const amounts = offers
+        .map((o) => ({ micro: String(o?.amount ?? o?.maxAmountRequired ?? ''), network: (0, exports.networkOf)(o?.network) }))
+        .filter((a) => /^\d{1,15}$/.test(a.micro));
+    const baseInput = it?.input || it?.extensions?.bazaar?.info?.input || it?.inputSchema || it?.accepts?.[0]?.outputSchema?.input || null;
+    const req = baseInput?.required
+        || it?.extensions?.bazaar?.schema?.properties?.input?.properties?.body?.required
+        || it?.extensions?.bazaar?.schema?.properties?.input?.properties?.queryParams?.required || [];
+    const input = baseInput ? { ...baseInput, required: Array.isArray(req) ? req.map(String) : [] } : null;
+    const method = String(baseInput?.method || it.method || 'GET').toUpperCase();
+    const description = String(it.description || it.metadata?.description || offers.map((o) => o?.description).filter(Boolean)[0] || '');
+    const tags = [...(Array.isArray(it.topics) ? it.topics : []), ...(Array.isArray(it.tags) ? it.tags : [])].map(String).slice(0, 10);
+    return { url, method, description, amounts, input, tags, source: String(it.source || '') };
+}
+function fromX402Resources(items, p, sourceName = 'x402-discovery') {
+    const list = Array.isArray(items) ? items : Array.isArray(items?.resources) ? items.resources : Array.isArray(items?.items) ? items.items : [];
+    const out = [];
+    const used = new Set();
+    for (const it of list) {
+        const r = norm(it);
+        if (!r)
+            continue;
+        const u = new URL(r.url);
+        const host = u.hostname.toLowerCase().replace(/^www\./, '');
+        let name = (u.pathname.replace(/^\/+|\/+$/g, '').replace(/\//g, '-') || 'root') + (r.method !== 'GET' ? `-${r.method.toLowerCase()}` : '');
+        // long resource paths (token addresses in the path) keep a readable head and a digest of the full resource
+        if (name.length > 48)
+            name = `${name.slice(0, 39).replace(/[-.]+$/, '')}-${(0, node_crypto_1.createHash)('sha256').update(`${r.method} ${r.url}`).digest('hex').slice(0, 8)}`;
+        let path = `${host}/${name}`;
+        for (let i = 2; used.has(path.toLowerCase()); i++)
+            path = `${host}/${name}-${i}`;
+        used.add(path.toLowerCase());
+        const networks = [...new Set(r.amounts.map((a) => a.network).filter(Boolean))];
+        const micros = r.amounts.map((a) => BigInt(a.micro));
+        const pricing = micros.length
+            ? { model: 'per_call', price: { amount_micro: micros.reduce((a, b) => (b < a ? b : a)).toString(), currency: 'USDC', ...(networks[0] ? { network: networks[0] } : {}) }, unit: 'request', source: 'provider' }
+            : { model: 'unknown', source: 'unknown' };
+        const side = r.method === 'GET' || r.method === 'HEAD' ? ['read'] : null;
+        out.push({
+            source: sourceName, source_ref: `${r.method} ${r.url}`, origin: 'x402', path,
+            name: `${host} ${u.pathname}`.slice(0, 120), description: r.description,
+            provider: { name: host, url: `${u.protocol}//${u.host}`, kognai_owned: false },
+            category: 'x402-service', tags: ['x402', ...(r.source ? [r.source] : []), ...r.tags],
+            operations: [{ op: 'call', method: r.method, summary: r.description || `${r.method} ${u.pathname}`, input_schema: schemaFromInput(r.input), output_schema: null, side_effects: side }],
+            auth: { kind: 'x402' }, pricing, licence: p.licence, endpoint: r.url, implementation: 'http',
+            networks, lifecycle: 'active', provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+        });
+    }
+    return out;
+}

package/dist/catalog/file-store.d.ts

@@ -0,0 +1,27 @@
+import type { TrustEvent } from '../types/ports';
+import type { ToolRecord, TrustState } from '../types/tool';
+import { MemoryCatalogStore } from './memory-store';
+export declare class FileCatalogStore extends MemoryCatalogStore {
+    readonly dir: string;
+    private loading;
+    constructor(dir: string);
+    private flush;
+    upsert(rows: ToolRecord[]): {
+        added: number;
+        versioned: number;
+        unchanged: number;
+    };
+    setTrust(id: string, version: string, to: TrustState, by: string, why: string): void;
+    recordEvent(e: TrustEvent): void;
+    writeRaw(sha: string, text: string): void;
+    vectors(model: string): {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    } | null;
+    writeVectors(model: string, v: {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    }, builtAt: string): void;
+}

package/dist/catalog/file-store.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileCatalogStore = void 0;
+/**
+ * FileCatalogStore (ADR-003): workspace/ktr/catalog/
+ *   tools.jsonl            one row per tool version, rewritten by atomic rename
+ *   index.json             snapshot id + index entries (id, version, schema hash, trust, lifecycle, latest)
+ *   events.jsonl           trust events, append only
+ *   raw/<sha>.txt          raw provider descriptions, by hash, never shown to a model
+ *   vectors.<model>.f32    float32 little endian, row major; vectors.<model>.json { model, dims, ids, built_at }
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const memory_store_1 = require("./memory-store");
+const MODEL_RE = /^[a-z0-9.:_-]{1,60}$/i;
+function atomicWrite(path, data) {
+    const tmp = `${path}.tmp-${process.pid}`;
+    (0, node_fs_1.writeFileSync)(tmp, data);
+    (0, node_fs_1.renameSync)(tmp, path);
+}
+class FileCatalogStore extends memory_store_1.MemoryCatalogStore {
+    dir;
+    loading = false;
+    constructor(dir) {
+        super();
+        this.dir = dir;
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        this.loading = true;
+        const tools = (0, node_path_1.join)(dir, 'tools.jsonl');
+        const index = (0, node_path_1.join)(dir, 'index.json');
+        if ((0, node_fs_1.existsSync)(tools)) {
+            const rows = (0, node_fs_1.readFileSync)(tools, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+            // restore ingestion order of latest versions from the index
+            const latest = (0, node_fs_1.existsSync)(index) ? new Map((JSON.parse((0, node_fs_1.readFileSync)(index, 'utf8')).entries || []).filter((e) => e.latest).map((e) => [e.id, e.version])) : new Map();
+            for (const r of rows)
+                this.rows.set(this.key(r.id, r.version), r);
+            for (const r of rows)
+                if (!latest.size || latest.get(r.id) === r.version)
+                    this.latestVersion.set(r.id, r.version);
+        }
+        const ev = (0, node_path_1.join)(dir, 'events.jsonl');
+        if ((0, node_fs_1.existsSync)(ev))
+            this.trustEvents = (0, node_fs_1.readFileSync)(ev, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+        this.loading = false;
+    }
+    flush() {
+        const rows = [...this.rows.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.version < b.version ? -1 : 1));
+        atomicWrite((0, node_path_1.join)(this.dir, 'tools.jsonl'), rows.map((r) => JSON.stringify(r)).join('\n') + (rows.length ? '\n' : ''));
+        atomicWrite((0, node_path_1.join)(this.dir, 'index.json'), JSON.stringify({ snapshot_id: this.snapshotId(), count: rows.length, entries: this.index() }, null, 1) + '\n');
+    }
+    upsert(rows) {
+        const r = super.upsert(rows);
+        if (!this.loading)
+            this.flush();
+        return r;
+    }
+    setTrust(id, version, to, by, why) {
+        super.setTrust(id, version, to, by, why);
+        this.flush();
+    }
+    recordEvent(e) {
+        super.recordEvent(e);
+        if (!this.loading)
+            (0, node_fs_1.appendFileSync)((0, node_path_1.join)(this.dir, 'events.jsonl'), JSON.stringify(e) + '\n');
+    }
+    writeRaw(sha, text) {
+        if (!/^[0-9a-f]{64}$/.test(sha))
+            throw new Error('bad sha');
+        const d = (0, node_path_1.join)(this.dir, 'raw');
+        (0, node_fs_1.mkdirSync)(d, { recursive: true });
+        const p = (0, node_path_1.join)(d, `${sha}.txt`);
+        if (!(0, node_fs_1.existsSync)(p))
+            atomicWrite(p, text);
+    }
+    vectors(model) {
+        const mem = super.vectors(model);
+        if (mem)
+            return mem;
+        if (!MODEL_RE.test(model))
+            return null;
+        const meta = (0, node_path_1.join)(this.dir, `vectors.${model}.json`);
+        const bin = (0, node_path_1.join)(this.dir, `vectors.${model}.f32`);
+        if (!(0, node_fs_1.existsSync)(meta) || !(0, node_fs_1.existsSync)(bin))
+            return null;
+        const m = JSON.parse((0, node_fs_1.readFileSync)(meta, 'utf8'));
+        const buf = (0, node_fs_1.readFileSync)(bin);
+        const data = new Float32Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+        if (m.model !== model || data.length !== m.dims * m.ids.length)
+            throw new Error(`vectors.${model} do not match their metadata`);
+        const v = { dims: m.dims, ids: m.ids, data };
+        super.setVectors(model, v);
+        return v;
+    }
+    writeVectors(model, v, builtAt) {
+        if (!MODEL_RE.test(model))
+            throw new Error('bad model name');
+        super.setVectors(model, v);
+        atomicWrite((0, node_path_1.join)(this.dir, `vectors.${model}.f32`), Buffer.from(v.data.buffer, v.data.byteOffset, v.data.byteLength));
+        atomicWrite((0, node_path_1.join)(this.dir, `vectors.${model}.json`), JSON.stringify({ model, dims: v.dims, count: v.ids.length, built_at: builtAt, ids: v.ids }) + '\n');
+    }
+}
+exports.FileCatalogStore = FileCatalogStore;

package/dist/catalog/ingest.d.ts

@@ -0,0 +1,53 @@
+import type { RawToolDescriptor } from '../adapters/raw';
+import type { CatalogStore, TrustEvent } from '../types/ports';
+import type { ToolRecord } from '../types/tool';
+import { type SanitiseFlag } from './sanitise';
+export declare const MAX_SCHEMA_BYTES: number;
+export declare const MAX_OPS = 200;
+export declare const MAX_SAME_AS_GROUP = 8;
+export interface Revocation {
+    id: string;
+    version: string | '*';
+    why: string;
+    by: string;
+    at: string;
+}
+export interface IngestOpts {
+    /** ISO time stamped on rows as ingested_at (not part of the snapshot id). */
+    now: string;
+    revoked?: Revocation[];
+    /** Capability tagger (S2): returns capability ids for an operation's text. */
+    tagger?: (text: string) => string[];
+    /** Maximum rows kept per source (T14). */
+    sourceCaps?: Record<string, number>;
+    /** Raw text sink (catalog/raw/<sha>.txt in the file store). */
+    rawSink?: (sha: string, text: string) => void;
+}
+export interface SourceCount {
+    seen: number;
+    added: number;
+    versioned: number;
+    unchanged: number;
+    rejected: number;
+    capped: number;
+}
+export interface IngestReport {
+    per_source: Record<string, SourceCount>;
+    quarantined: number;
+    verified: number;
+    rejected: Array<{
+        source: string;
+        source_ref: string;
+        why: string;
+    }>;
+    sanitise_flags: Partial<Record<SanitiseFlag, number>>;
+    same_as_links: number;
+    same_as_groups_skipped: number;
+    revoked_applied: number;
+    events: TrustEvent[];
+    snapshot_id: string;
+}
+export declare function toRecord(r: RawToolDescriptor, opts: IngestOpts, flagSink: (f: SanitiseFlag[]) => void): ToolRecord | {
+    reject: string;
+};
+export declare function ingest(raws: RawToolDescriptor[], store: CatalogStore, opts: IngestOpts): IngestReport;

package/dist/catalog/ingest.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SAME_AS_GROUP = exports.MAX_OPS = exports.MAX_SCHEMA_BYTES = void 0;
+exports.toRecord = toRecord;
+exports.ingest = ingest;
+/**
+ * Ingestion (plan.md S1): raw descriptors to ToolRecords in a CatalogStore.
+ *
+ *   1. validate: at most 200 operations, schemas at most 64 KB each (T14), a valid id (ADR-004)
+ *   2. sanitise text (T1); raw text kept by hash only
+ *   3. risk classes per operation (fail closed); a payment operation taking a destination is refused (security.txt 1)
+ *   4. schema hash and implementation hash (no probe)
+ *   5. dedup and versions: same id + same version + same schema = unchanged; a new provider version or a new schema =
+ *      a new version row; same endpoint host + same known schema under another id = same_as link
+ *   6. trust: native Kognai rows from Kognai sources are verified; everything else is quarantined; a reviewed or
+ *      verified outside row whose hashes change goes back to quarantine with an event
+ *   7. revocation list applied last
+ *   8. report: counts per source, quarantined, rejected with reasons, sanitise flags
+ *
+ * Deterministic: input order does not matter (sorted), and nothing time based enters the snapshot id.
+ */
+const hash_1 = require("../hash");
+const ids_1 = require("../ids");
+const tool_1 = require("../types/tool");
+const lifecycle_1 = require("./lifecycle");
+const risk_1 = require("./risk");
+const sanitise_1 = require("./sanitise");
+const validate_1 = require("../schema/validate");
+exports.MAX_SCHEMA_BYTES = 64 * 1024;
+exports.MAX_OPS = 200;
+exports.MAX_SAME_AS_GROUP = 8;
+const KOGNAI_SOURCE = /^kognai:/;
+/** Operations that move value somewhere (T15), as opposed to reading about tokens. */
+const TRANSFER_CUE = /\b(transfer|send|withdraw|payout|pay out|remit|disburse)\b/;
+const cleanName = (s) => (0, sanitise_1.sanitiseShort)(s, 120) || 'unnamed';
+const hostOf = (u) => { try {
+    return u ? new URL(u).hostname.toLowerCase() : null;
+}
+catch {
+    return null;
+} };
+function implHash(r) {
+    if (r.implementation_hash)
+        return r.implementation_hash;
+    if (r.package)
+        return (0, hash_1.sha256)(`${r.package.registry}:${r.package.identifier}@${r.package.version || '?'}`);
+    const h = hostOf(r.endpoint);
+    return h ? (0, hash_1.sha256)(`endpoint:${h}`) : null;
+}
+function toRecord(r, opts, flagSink) {
+    if (!Array.isArray(r.operations))
+        return { reject: 'no operations array' };
+    if (r.operations.length > exports.MAX_OPS)
+        return { reject: `more than ${exports.MAX_OPS} operations (T14)` };
+    let id;
+    try {
+        id = (0, ids_1.formatToolId)(r.origin, r.path);
+    }
+    catch (e) {
+        return { reject: `bad id: ${e.message}` };
+    }
+    const native = r.origin === 'kognai' && KOGNAI_SOURCE.test(r.source);
+    if (r.origin === 'kognai' && !native)
+        return { reject: 'origin kognai claimed by a non Kognai source' };
+    const desc = (0, sanitise_1.sanitise)(r.description || '');
+    flagSink(desc.flags);
+    const rawSha = (0, hash_1.sha256)(String(r.description || ''));
+    opts.rawSink?.(rawSha, String(r.description || ''));
+    const externalNet = !native || !!hostOf(r.endpoint);
+    const ops = [];
+    const seenOps = new Set();
+    for (const o of r.operations) {
+        const op = String(o.op || 'call').toLowerCase().replace(/[^a-z0-9_.-]+/g, '_').slice(0, 64) || 'call';
+        if (seenOps.has(op))
+            continue;
+        seenOps.add(op);
+        for (const s of [o.input_schema, o.output_schema]) {
+            if (s && Buffer.byteLength((0, hash_1.canonical)(s)) > exports.MAX_SCHEMA_BYTES)
+                return { reject: `schema of ${op} over 64 KB (T14)` };
+        }
+        const summaryRaw = o.summary || r.name;
+        const sum = (0, sanitise_1.sanitise)(summaryRaw);
+        flagSink(sum.flags);
+        const text = native ? sum.text : `${r.name} ${desc.text} ${sum.text}`;
+        const risk = (0, risk_1.deriveRisk)({ origin: r.origin, side_effects: o.side_effects, scopes: o.scopes, text, input_schema: o.input_schema, external_network: externalNet });
+        // a declared read is not a transfer; a declared payment, or unknown side effects with a transfer cue, is
+        const movesMoney = risk.side_effects.includes('payment') || (risk.side_effects.length === 0 && TRANSFER_CUE.test(text.toLowerCase()));
+        if (risk.risk.includes('payment') && movesMoney && (0, risk_1.takesDestination)(o.input_schema))
+            return { reject: `operation ${op} moves money to an address it takes as input (security.txt rule 1, T15)` };
+        // explicit capabilities (native sources) are authoritative; only untagged operations are tagged from text
+        const tagged = opts.tagger && !(o.capabilities && o.capabilities.length) ? opts.tagger(`${cleanName(r.name)} ${sum.text} ${native ? '' : desc.text} ${(r.tags || []).join(' ')}`) : [];
+        ops.push({
+            op,
+            summary: (0, sanitise_1.sanitiseShort)(summaryRaw, 200),
+            capabilities: [...new Set([...(o.capabilities || []), ...tagged])].sort(),
+            input_schema: (o.input_schema && typeof o.input_schema === 'object') ? o.input_schema : {},
+            output_schema: (o.output_schema && typeof o.output_schema === 'object') ? o.output_schema : null,
+            side_effects: risk.side_effects,
+            risk_classes: risk.risk,
+            scopes: [...(o.scopes || [])],
+            idempotent: o.idempotent ?? null,
+            url_from_user: risk.url_from_user,
+        });
+    }
+    const sh = (0, hash_1.schemaHash)(ops);
+    const providerVersion = r.version && /^[0-9A-Za-z.+_-]{1,40}$/.test(r.version) ? r.version : null;
+    const version = providerVersion || `0.0.0+${sh.slice(0, 12)}`;
+    const privacy = r.privacy_class || 'public';
+    const tier = r.business_tier === undefined ? null : r.business_tier;
+    const rec = {
+        schema_version: 1,
+        id,
+        version,
+        name: cleanName(r.name),
+        description_safe: desc.text,
+        description_raw_sha256: rawSha,
+        provider: { name: cleanName(r.provider?.name || 'unknown'), ...(r.provider?.url ? { url: String(r.provider.url).slice(0, 300) } : {}), kognai_owned: native && r.provider?.kognai_owned !== false },
+        origin: r.origin,
+        category: String(r.category || 'other').toLowerCase().slice(0, 60),
+        tags: [...new Set([...(r.tags || []).map((t) => String(t).toLowerCase().slice(0, 60)), ...(r.founder_approval ? ['founder_approval'] : [])])].slice(0, 40),
+        operations: ops,
+        auth: r.auth ? { ...r.auth } : { kind: 'none' },
+        privacy_class: privacy,
+        business_tier: tier,
+        regions: r.regions && r.regions.length ? [...r.regions] : ['*'],
+        networks: [...new Set(r.networks || [])],
+        pricing: r.pricing ? { ...r.pricing } : { model: 'unknown', source: 'unknown' },
+        success: { ...tool_1.EMPTY_SUCCESS },
+        latency: { p50_ms: null, p95_ms: null, n: 0 },
+        rate_limits: null,
+        health: { state: 'unknown', checked_at: null, source: 'none' },
+        dependencies: [...(r.dependencies || [])],
+        trust_state: native ? 'verified' : 'quarantined',
+        skill_ids: [...(r.skill_ids || [])],
+        last_validated: null,
+        schema_hash: sh,
+        implementation_hash: implHash(r),
+        lifecycle: r.lifecycle || 'active',
+        aliases: [...new Set(r.aliases || [])],
+        same_as: [],
+        ...(r.product_id ? { product_id: r.product_id } : {}),
+        ...(r.aiax_ready === true ? { aiax_ready: true } : {}),
+        provenance: [{
+                source: r.source, source_ref: String(r.source_ref).slice(0, 400), retrieved_at: r.provenance.retrieved_at,
+                licence: r.provenance.licence ?? r.licence ?? null, adapter: r.provenance.adapter, adapter_version: r.provenance.adapter_version,
+                snapshot_sha256: r.provenance.snapshot_sha256,
+            }],
+        ingested_at: opts.now,
+    };
+    const v = (0, validate_1.validateToolRecord)(rec);
+    if (!v.ok)
+        return { reject: `schema: ${v.errors.slice(0, 3).join('; ')}` };
+    return rec;
+}
+const knownSchema = (r) => r.operations.some((o) => Object.keys(o.input_schema || {}).length > 0);
+function ingest(raws, store, opts) {
+    const report = { per_source: {}, quarantined: 0, verified: 0, rejected: [], sanitise_flags: {}, same_as_links: 0, same_as_groups_skipped: 0, revoked_applied: 0, events: [], snapshot_id: '' };
+    const count = (s) => (report.per_source[s] ||= { seen: 0, added: 0, versioned: 0, unchanged: 0, rejected: 0, capped: 0 });
+    const flagSink = (fs) => { for (const f of fs)
+        report.sanitise_flags[f] = (report.sanitise_flags[f] || 0) + 1; };
+    const sorted = [...raws].sort((a, b) => (`${a.source}\u0000${a.path}\u0000${a.source_ref}` < `${b.source}\u0000${b.path}\u0000${b.source_ref}` ? -1 : 1));
+    const keptPerSource = new Map();
+    const batch = new Map(); // id -> record (latest in this batch)
+    for (const raw of sorted) {
+        const c = count(raw.source);
+        c.seen++;
+        const cap = opts.sourceCaps?.[raw.source];
+        if (cap !== undefined && (keptPerSource.get(raw.source) || 0) >= cap) {
+            c.capped++;
+            continue;
+        }
+        const rec = toRecord(raw, opts, flagSink);
+        if ('reject' in rec) {
+            c.rejected++;
+            report.rejected.push({ source: raw.source, source_ref: raw.source_ref, why: rec.reject });
+            continue;
+        }
+        keptPerSource.set(raw.source, (keptPerSource.get(raw.source) || 0) + 1);
+        const prevInBatch = batch.get(rec.id);
+        if (prevInBatch) {
+            // two descriptors with one id in one batch: the first stays, the second is reported (not merged silently)
+            c.rejected++;
+            report.rejected.push({ source: raw.source, source_ref: raw.source_ref, why: `duplicate id ${rec.id} in this batch` });
+            continue;
+        }
+        // versions against the store
+        const prev = store.get(rec.id);
+        if (prev) {
+            if (prev.version === rec.version && prev.schema_hash !== rec.schema_hash)
+                rec.version = `${rec.version.split('+')[0]}+${rec.schema_hash.slice(0, 12)}`;
+            const drift = (0, lifecycle_1.trustAfterDrift)(prev, rec);
+            if (rec.origin !== 'kognai') {
+                const carried = prev.trust_state === 'revoked' ? 'revoked' : drift.drifted ? drift.trust : prev.trust_state;
+                if (drift.drifted && (prev.trust_state === 'verified' || prev.trust_state === 'reviewed')) {
+                    const e = { at: opts.now, id: rec.id, version: rec.version, from: prev.trust_state, to: 'quarantined', by: 'ktr-ingest', why: 'hash drift: schema or implementation changed' };
+                    report.events.push(e);
+                    store.recordEvent(e);
+                }
+                rec.trust_state = carried;
+            }
+            rec.same_as = [...prev.same_as];
+        }
+        batch.set(rec.id, rec);
+    }
+    // same_as: same endpoint host and same known schema under another id
+    const all = new Map();
+    for (const r of store.latest())
+        all.set(r.id, r);
+    for (const r of batch.values())
+        all.set(r.id, r);
+    const byKey = new Map();
+    for (const r of all.values()) {
+        // native rows share a source file hash, not an endpoint: they are never duplicates of each other
+        if (r.origin === 'kognai' || !knownSchema(r) || !r.implementation_hash)
+            continue;
+        const k = `${r.implementation_hash}|${r.schema_hash}`;
+        (byKey.get(k) || byKey.set(k, []).get(k)).push(r.id);
+    }
+    for (const ids of byKey.values()) {
+        if (ids.length < 2)
+            continue;
+        // a large group is one templated endpoint (a token address in the path): not duplicates of one tool
+        if (ids.length > exports.MAX_SAME_AS_GROUP) {
+            report.same_as_groups_skipped++;
+            continue;
+        }
+        for (const id of ids) {
+            const r = batch.get(id);
+            if (!r)
+                continue;
+            const before = r.same_as.length;
+            r.same_as = [...new Set([...r.same_as, ...ids.filter((x) => x !== id)])].sort();
+            report.same_as_links += r.same_as.length - before;
+        }
+    }
+    // revocation last
+    for (const rv of opts.revoked || []) {
+        const r = batch.get(rv.id);
+        if (r && (rv.version === '*' || rv.version === r.version) && r.trust_state !== 'revoked') {
+            const e = { at: rv.at, id: r.id, version: r.version, from: r.trust_state, to: 'revoked', by: rv.by, why: rv.why };
+            r.trust_state = 'revoked';
+            report.revoked_applied++;
+            report.events.push(e);
+            store.recordEvent(e);
+        }
+    }
+    // a revocation of a stored row that is not in this batch
+    for (const rv of opts.revoked || []) {
+        if (batch.has(rv.id))
+            continue;
+        const r = store.get(rv.id);
+        if (r && (rv.version === '*' || rv.version === r.version) && r.trust_state !== 'revoked') {
+            store.setTrust(r.id, r.version, 'revoked', rv.by, rv.why);
+            report.revoked_applied++;
+        }
+    }
+    const rows = [...batch.values()].sort((a, b) => (a.id < b.id ? -1 : 1));
+    const before = new Map(rows.map((r) => [r.id, store.get(r.id)]));
+    store.upsert(rows);
+    for (const r of rows) {
+        const c = count(r.provenance[0].source);
+        const p = before.get(r.id);
+        if (!p)
+            c.added++;
+        else if (p.version === r.version)
+            c.unchanged++;
+        else
+            c.versioned++;
+        if (r.trust_state === 'quarantined')
+            report.quarantined++;
+        if (r.trust_state === 'verified')
+            report.verified++;
+    }
+    report.snapshot_id = store.snapshotId();
+    return report;
+}