@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/dist/platform/knowledge-router.js

@@ -0,0 +1,320 @@
+import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
+import { CapabilityError } from './plugin-contract.js';
+export function unwrapKnowledgeResult(value) {
+    if (value?.structuredContent !== undefined)
+        return value.structuredContent;
+    if (Array.isArray(value?.content)) {
+        const text = value.content.find((item) => item.type === 'text')?.text;
+        if (text) {
+            try {
+                return JSON.parse(text);
+            }
+            catch { /* domain result stays intact */ }
+        }
+    }
+    return value;
+}
+/** Account-aware routing and lazy transfer live in the platform, not in a plugin. */
+export class KnowledgeRouter {
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.options = options;
+        this.cache = new Map();
+        this.cacheBytes = 0;
+        // Session-bounded revision metadata prevents a known correction from falling back to old bytes.
+        this.revisions = new Map();
+        this.secret = options.secret ?? randomBytes(32);
+        if (this.secret.length < 32)
+            throw new Error('Knowledge reference key must be at least 256 bits');
+    }
+    now() { return this.options.now?.() ?? Date.now(); }
+    accountTag(accountId) { return createHmac('sha256', this.secret).update('account:' + accountId).digest('base64url'); }
+    reference(context, provider, card) {
+        const ref = { v: 1, account: this.accountTag(context.accountId), provider, origin: card.originDeviceId, id: card.id, version: card.version, project: card.scope.projectId };
+        const payload = Buffer.from(JSON.stringify(ref)).toString('base64url');
+        return 'k1.' + payload + '.' + createHmac('sha256', this.secret).update(payload).digest('base64url');
+    }
+    parseReference(context, input) {
+        if (typeof input !== 'string' || input.length > 4096)
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid knowledge reference');
+        const [prefix, payload, signature, extra] = input.split('.');
+        if (prefix !== 'k1' || !payload || !signature || extra !== undefined)
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid knowledge reference');
+        const expected = createHmac('sha256', this.secret).update(payload).digest();
+        let received;
+        try {
+            received = Buffer.from(signature, 'base64url');
+        }
+        catch {
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid reference signature');
+        }
+        if (received.length !== expected.length || !timingSafeEqual(expected, received))
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid reference signature');
+        let ref;
+        try {
+            ref = JSON.parse(Buffer.from(payload, 'base64url').toString());
+        }
+        catch {
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid reference payload');
+        }
+        if (ref.v !== 1 || ref.account !== this.accountTag(context.accountId))
+            throw new CapabilityError('ACCESS_DENIED', 'Knowledge reference belongs to another account');
+        if (![ref.provider, ref.origin, ref.id].every(value => typeof value === 'string' && value.length > 0 && value.length <= 1024) || !Number.isSafeInteger(ref.version))
+            throw new CapabilityError('KNOWLEDGE_REF_INVALID', 'Invalid reference fields');
+        return ref;
+    }
+    async scope(context) {
+        if (!context.accountId || !context.requesterDeviceId || !context.sessionId)
+            throw new CapabilityError('AUTH_REQUIRED', 'Authenticated account, requesting Device and session are required');
+        const devices = (await this.transport.devices(context.accountId)).filter(device => device.accountId === context.accountId);
+        if (!devices.some(device => device.deviceId === context.requesterDeviceId))
+            throw new CapabilityError('ACCESS_DENIED', 'Requesting Device is not owned by this account');
+        return devices;
+    }
+    allowed(card, providerId, context, projectId) {
+        if (!card.scope || !['project', 'account', 'local'].includes(card.scope.visibility))
+            return false;
+        if (card.scope.visibility === 'local' && providerId !== context.requesterDeviceId)
+            return false;
+        if (card.scope.projectId && card.scope.projectId !== projectId)
+            return false;
+        if (card.scope.visibility === 'project' && !card.scope.projectId)
+            return false;
+        return true;
+    }
+    cacheKey(context, origin, id) { return JSON.stringify([context.accountId, context.requesterDeviceId, context.sessionId, origin, id]); }
+    pruneCache() {
+        for (const [key, entry] of this.cache)
+            if (this.now() - entry.at > (this.options.cacheTtlMs ?? 300000)) {
+                this.cache.delete(key);
+                this.cacheBytes -= entry.bytes;
+            }
+        for (const [key, entry] of this.revisions)
+            if (this.now() - entry.at > (this.options.cacheTtlMs ?? 300000))
+                this.revisions.delete(key);
+        while (this.revisions.size > 256)
+            this.revisions.delete(this.revisions.keys().next().value);
+        while (this.cache.size > 256 || this.cacheBytes > (this.options.cacheBytes ?? 8 * 1024 * 1024)) {
+            const first = this.cache.entries().next().value;
+            if (!first)
+                break;
+            this.cache.delete(first[0]);
+            this.cacheBytes -= first[1].bytes;
+        }
+    }
+    forgetCached(key) {
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.cache.delete(key);
+            this.cacheBytes -= cached.bytes;
+        }
+    }
+    rememberRevision(key, card, blocked) {
+        const prior = this.revisions.get(key);
+        if (prior && (card.version < prior.version || (card.version === prior.version && (card.contentHash !== prior.contentHash || card.status !== prior.status)))) {
+            throw new CapabilityError('KNOWLEDGE_REVISION_CONFLICT', 'Origin revision conflicts with previously observed knowledge');
+        }
+        this.revisions.delete(key);
+        this.revisions.set(key, { version: card.version, contentHash: card.contentHash, status: card.status, at: this.now(), ...(blocked ? { blocked } : {}) });
+        const cached = this.cache.get(key)?.card;
+        if (blocked || (cached && (cached.version < card.version || (cached.version === card.version && (cached.contentHash !== card.contentHash || cached.status !== card.status)))))
+            this.forgetCached(key);
+        this.pruneCache();
+    }
+    cacheCard(context, card) {
+        const key = this.cacheKey(context, card.originDeviceId, card.id), bytes = Buffer.byteLength(JSON.stringify(card));
+        if (bytes > Math.min(1024 * 1024, this.options.cacheBytes ?? 8 * 1024 * 1024))
+            return;
+        const previous = this.cache.get(key);
+        if (previous)
+            this.cacheBytes -= previous.bytes;
+        this.cache.delete(key);
+        this.cache.set(key, { card: structuredClone(card), at: this.now(), bytes });
+        this.cacheBytes += bytes;
+        this.pruneCache();
+    }
+    cacheStats() { this.pruneCache(); return { entries: this.cache.size, bytes: this.cacheBytes }; }
+    preview(value, context, provider) {
+        if (!value || typeof value.id !== 'string' || typeof value.summary !== 'string' || typeof value.originDeviceId !== 'string' || !Number.isSafeInteger(value.version))
+            return;
+        return {
+            id: value.id, version: value.version, contentHash: String(value.contentHash ?? ''), summary: value.summary.slice(0, 1200), status: value.status,
+            originDeviceId: value.originDeviceId, servingDeviceId: provider, scope: value.scope, evidenceCount: Number(value.evidenceCount ?? 0), lastVerifiedAt: value.lastVerifiedAt ?? null,
+            read_ref: this.reference(context, provider, value)
+        };
+    }
+    async search(context, input, action = 'search') {
+        const devices = await this.scope(context), capability = 'knowledge.' + action;
+        const limit = Math.min(50, Math.max(1, input.limit ?? 10)), budget = Math.min(64 * 1024, Math.max(1024, input.maxBytes ?? 16 * 1024));
+        const score = (device) => (device.deviceId === context.requesterDeviceId ? 1000 : 0) + (input.projectId && device.projects?.includes(input.projectId) ? 500 : 0) - Math.min(device.latencyMs ?? 100, 500) / 10;
+        const providers = devices.filter(device => device.online && device.capabilities.includes(capability) && (!input.providerDeviceId || input.providerDeviceId === device.deviceId)).sort((a, b) => score(b) - score(a) || (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0) || a.deviceId.localeCompare(b.deviceId));
+        if (input.providerDeviceId && !devices.some(d => d.deviceId === input.providerDeviceId))
+            throw new CapabilityError('ACCESS_DENIED', 'Provider Device is not owned by this account');
+        const items = [], queried = [], unavailable = [], dedup = new Set();
+        let truncated = false;
+        // A relevant successful provider is enough; fallback is bounded and only used for absence/failure.
+        for (const provider of providers.slice(0, Math.min(3, Math.max(1, this.options.maxProviders ?? 2)))) {
+            queried.push(provider.deviceId);
+            try {
+                const result = unwrapKnowledgeResult(await this.transport.call(context.accountId, provider.deviceId, capability, { query: input.query, projectId: input.projectId, limit, maxBytes: budget }));
+                for (const candidate of result.items ?? []) {
+                    if (!this.allowed(candidate, provider.deviceId, context, input.projectId) || ['withdrawn', 'superseded'].includes(candidate.status))
+                        continue;
+                    const item = this.preview(candidate, context, provider.deviceId);
+                    if (!item)
+                        continue;
+                    const key = item.originDeviceId + ':' + item.id;
+                    if (dedup.has(key))
+                        continue;
+                    if (items.length >= limit || Buffer.byteLength(JSON.stringify({ items: [...items, item], queried, unavailable, truncated: true })) > budget) {
+                        truncated = true;
+                        break;
+                    }
+                    dedup.add(key);
+                    items.push(item);
+                }
+                truncated || (truncated = Boolean(result.truncated));
+                if (items.length)
+                    break;
+            }
+            catch (error) {
+                unavailable.push({ deviceId: provider.deviceId, code: error.code ?? 'PROVIDER_UNAVAILABLE' });
+            }
+        }
+        const response = { items, queried, unavailable, truncated, imported: 0 };
+        while (Buffer.byteLength(JSON.stringify(response)) > budget && response.items.length) {
+            response.items.pop();
+            response.truncated = true;
+        }
+        if (Buffer.byteLength(JSON.stringify(response)) > budget)
+            throw new CapabilityError('BUDGET_TOO_SMALL', 'Routing metadata exceeds the response budget');
+        return response;
+    }
+    async read(context, input) {
+        const devices = await this.scope(context), ref = this.parseReference(context, input.ref);
+        if (input.projectId !== undefined && ref.project !== undefined && input.projectId !== ref.project)
+            throw new CapabilityError('ACCESS_DENIED', 'Reference does not belong to the requested project');
+        const projectId = input.projectId ?? ref.project;
+        const provider = devices.find(device => device.deviceId === ref.provider), requester = devices.find(device => device.deviceId === context.requesterDeviceId);
+        if (!provider)
+            throw new CapabilityError('ACCESS_DENIED', 'Serving Device is no longer owned by this account');
+        const key = this.cacheKey(context, ref.origin, ref.id);
+        this.pruneCache();
+        const cached = this.cache.get(key);
+        let card, evidence;
+        let freshness = 'current';
+        const assertRevision = (value) => {
+            if (!value || !Number.isSafeInteger(value.version) || value.version < 1 || typeof value.contentHash !== 'string' || !value.contentHash || value.contentHash.length > 128 ||
+                !['hypothesis', 'observed', 'validated', 'stale', 'superseded', 'withdrawn'].includes(value.status))
+                throw new CapabilityError('KNOWLEDGE_REVISION_INVALID', 'Provider returned invalid revision metadata');
+            const known = this.revisions.get(key), minimum = Math.max(ref.version, known?.version ?? 0);
+            if (value.version < minimum)
+                throw new CapabilityError('KNOWLEDGE_REVISION_UNAVAILABLE', 'The selected or newer known knowledge revision is unavailable');
+            if (known && value.version === known.version && (value.contentHash !== known.contentHash || value.status !== known.status))
+                throw new CapabilityError('KNOWLEDGE_REVISION_CONFLICT', 'Provider returned conflicting bytes for a known revision');
+        };
+        const fetchCard = async (device) => {
+            const result = unwrapKnowledgeResult(await this.transport.call(context.accountId, device.deviceId, 'knowledge.read', { ref: ref.id, projectId, evidence: input.evidence === true, maxBytes: Math.min(64 * 1024, Math.max(1024, input.maxBytes ?? 16 * 1024)) }));
+            if (!result.card || result.card.id !== ref.id || result.card.originDeviceId !== ref.origin)
+                throw new CapabilityError('KNOWLEDGE_IDENTITY_MISMATCH', 'Provider returned a different knowledge identity');
+            assertRevision(result.card);
+            if (!this.allowed(result.card, device.deviceId, context, projectId))
+                throw new CapabilityError('ACCESS_DENIED', 'Knowledge scope does not permit this read');
+            // Routing identity comes from the authenticated transport, never from provider-supplied metadata.
+            card = { ...result.card, servingDeviceId: device.deviceId };
+            evidence = result.evidence;
+        };
+        const useCache = () => {
+            if (!cached || this.revisions.get(key)?.blocked)
+                return false;
+            try {
+                assertRevision(cached.card);
+            }
+            catch {
+                return false;
+            }
+            card = structuredClone(cached.card);
+            freshness = 'stale';
+            return true;
+        };
+        // Prefer a previously imported copy on the requesting Device, if it has one.
+        if (requester.online && requester.deviceId !== provider.deviceId && requester.capabilities.includes('knowledge.read')) {
+            try {
+                await fetchCard(requester);
+            }
+            catch { /* selected provider remains authoritative fallback */ }
+        }
+        if (!card && !input.evidence)
+            useCache();
+        if (!card && provider.online && provider.capabilities.includes('knowledge.read'))
+            await fetchCard(provider);
+        if (!card)
+            useCache();
+        if (!card) {
+            const blocked = this.revisions.get(key)?.blocked;
+            if (blocked)
+                throw new CapabilityError(blocked, 'Origin denied or removed this knowledge');
+            if (this.revisions.has(key))
+                throw new CapabilityError('KNOWLEDGE_REVISION_UNAVAILABLE', 'The newer known knowledge revision is unavailable');
+            throw new CapabilityError('PROVIDER_UNAVAILABLE', 'Knowledge provider is offline and this session has no cached selected read');
+        }
+        const origin = devices.find(device => device.deviceId === card.originDeviceId);
+        if (origin?.online && origin.capabilities.includes('knowledge.stat')) {
+            let metadata, metadataReceived = false;
+            try {
+                metadata = unwrapKnowledgeResult(await this.transport.call(context.accountId, origin.deviceId, 'knowledge.stat', { ref: card.id, projectId }));
+                metadataReceived = true;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ACCESS_DENIED' || code === 'KNOWLEDGE_NOT_FOUND' || code === 'KNOWLEDGE_SCOPE_MISMATCH') {
+                    this.rememberRevision(key, this.revisions.get(key) ?? card, code);
+                    throw error;
+                }
+                freshness = 'stale';
+            }
+            if (metadataReceived) {
+                if (!metadata || typeof metadata !== 'object')
+                    throw new CapabilityError('KNOWLEDGE_REVISION_INVALID', 'Origin returned invalid revision metadata');
+                if ((metadata.id !== undefined && metadata.id !== ref.id) || (metadata.originDeviceId !== undefined && metadata.originDeviceId !== ref.origin))
+                    throw new CapabilityError('KNOWLEDGE_IDENTITY_MISMATCH', 'Origin returned different revision metadata');
+                assertRevision(metadata);
+                const wasBlocked = this.revisions.get(key)?.blocked;
+                this.rememberRevision(key, metadata, wasBlocked);
+                // Once origin confirms change, failure to fetch it must never resurrect/import older bytes.
+                if (wasBlocked || metadata.version !== card.version || metadata.contentHash !== card.contentHash || metadata.status !== card.status) {
+                    try {
+                        await fetchCard(origin);
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        if (code === 'ACCESS_DENIED' || code === 'KNOWLEDGE_NOT_FOUND' || code === 'KNOWLEDGE_SCOPE_MISMATCH')
+                            this.rememberRevision(key, metadata, code);
+                        throw error;
+                    }
+                }
+                assertRevision(card);
+                this.rememberRevision(key, card);
+                freshness = 'current';
+            }
+        }
+        else if (!origin?.online || card.servingDeviceId !== card.originDeviceId)
+            freshness = 'stale';
+        const blocked = this.revisions.get(key)?.blocked;
+        if (blocked)
+            throw new CapabilityError(blocked, 'Origin denied or removed this knowledge');
+        assertRevision(card);
+        if (!this.allowed(card, card.servingDeviceId, context, projectId))
+            throw new CapabilityError('ACCESS_DENIED', 'Knowledge scope does not permit this read');
+        const response = { card, ...(evidence === undefined ? {} : { evidence }), imported: false, freshness: { status: freshness, lastVerifiedAt: freshness === 'current' ? this.now() : card.lastVerifiedAt }, read_ref: this.reference(context, card.servingDeviceId, card) };
+        if (Buffer.byteLength(JSON.stringify(response)) > Math.min(64 * 1024, Math.max(1024, input.maxBytes ?? 16 * 1024)))
+            throw new CapabilityError('BUDGET_TOO_SMALL', 'Full selected knowledge and provenance exceed the response budget');
+        if (requester.online && requester.capabilities.includes('knowledge.import') && card.originDeviceId !== requester.deviceId) {
+            const result = unwrapKnowledgeResult(await this.transport.call(context.accountId, requester.deviceId, 'knowledge.import', { card }));
+            response.imported = Boolean(result.imported);
+        }
+        this.rememberRevision(key, card);
+        this.cacheCard(context, card);
+        return response;
+    }
+}

package/dist/platform/plugin-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/plugin-child.js

@@ -0,0 +1,115 @@
+import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import readline from 'node:readline';
+import { CapabilityError } from './plugin-contract.js';
+import { createPluginServices } from './plugin-services.js';
+// Generic JSON-lines adapter; non-Node sidecars implement the same request/callback frames.
+let instance;
+let initializing = false;
+let requirements = [];
+const controllers = new Map();
+const hostPending = new Map();
+const send = (value) => process.stdout.write(JSON.stringify(value) + '\n');
+console.log = (...args) => console.error(...args);
+const servicesFor = (parentId, signal) => createPluginServices(requirements, (name, input, options) => {
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            if (!hostPending.delete(id))
+                return;
+            send({ type: 'host_cancel', id, parent_id: parentId });
+            reject(new CapabilityError('CANCELLED', 'Dependency callback cancelled'));
+        };
+        options.signal.addEventListener('abort', abort, { once: true });
+        hostPending.set(id, { resolve, reject, cleanup: () => options.signal.removeEventListener('abort', abort) });
+        send({ type: 'host_call', id, parent_id: parentId, method: 'capability.invoke', params: { name, input } });
+    });
+}, signal);
+const lines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+lines.on('line', async (line) => {
+    let request;
+    try {
+        if (Buffer.byteLength(line) > 2 * 1024 * 1024)
+            throw new Error('Plugin request exceeds frame budget');
+        request = JSON.parse(line);
+        if (!request || typeof request.id !== 'string')
+            throw new Error('Invalid request id');
+        if (request.type === 'host_result') {
+            const pending = hostPending.get(request.id);
+            if (pending) {
+                hostPending.delete(request.id);
+                pending.cleanup();
+                if (request.error)
+                    pending.reject(new CapabilityError(request.error.code ?? 'CAPABILITY_CALL_FAILED', request.error.message ?? 'Dependency failed'));
+                else
+                    pending.resolve(request.result);
+            }
+            return;
+        }
+        if (request.type !== undefined || typeof request.method !== 'string')
+            throw new Error('Invalid request frame');
+    }
+    catch (error) {
+        send({ id: null, error: { code: 'PLUGIN_PROTOCOL_ERROR', message: String(error) } });
+        return;
+    }
+    const { id, method, params } = request;
+    const controller = new AbortController();
+    if (controllers.has(id)) {
+        send({ id, error: { code: 'PLUGIN_PROTOCOL_ERROR', message: 'Duplicate request id' } });
+        return;
+    }
+    controllers.set(id, controller);
+    const invocation = { signal: controller.signal, services: servicesFor(id, controller.signal) };
+    try {
+        if (method === 'init') {
+            if (instance || initializing)
+                throw new Error('Plugin already initialized');
+            initializing = true;
+            requirements = params.requires ?? [];
+            const mod = await import(pathToFileURL(params.entry).href);
+            const context = { ...params.context, services: servicesFor(id, controller.signal) };
+            if (context.previousSchemaVersion !== undefined && context.previousSchemaVersion !== params.schemaVersion) {
+                if (!mod.migrate)
+                    throw new Error('Plugin data schema changed without a migration hook');
+                await mod.migrate({ dataRoot: context.dataRoot, fromVersion: context.previousSchemaVersion, toVersion: params.schemaVersion });
+            }
+            instance = await mod.createPlugin(context);
+            if (!instance || typeof instance.invoke !== 'function')
+                throw new Error('Plugin does not implement invoke');
+            await instance.start?.({ signal: controller.signal, services: servicesFor(id, controller.signal) });
+            send({ id, result: { ready: true } });
+        }
+        else if (method === 'invoke') {
+            if (!instance)
+                throw new Error('Plugin not initialized');
+            send({ id, result: await instance.invoke(params.capability, params.input, invocation) });
+        }
+        else if (method === 'cancel') {
+            controllers.get(params.id)?.abort();
+            send({ id, result: { cancelled: true } });
+        }
+        else if (method === 'stop') {
+            for (const [otherId, other] of controllers)
+                if (otherId !== id)
+                    other.abort();
+            await instance?.stop?.(invocation);
+            instance = undefined;
+            send({ id, result: { stopped: true } });
+            lines.close();
+            process.stdin.destroy();
+        }
+        else
+            throw new Error('Unknown plugin protocol method');
+    }
+    catch (error) {
+        const e = error;
+        send({ id, error: { code: e.code ?? 'PLUGIN_CALL_FAILED', message: e.message ?? String(error) } });
+    }
+    finally {
+        controller.abort();
+        controllers.delete(id);
+        if (method === 'init')
+            initializing = false;
+    }
+});

package/dist/platform/plugin-contract.d.ts

@@ -0,0 +1,76 @@
+import type { PluginServices } from './plugin-services.js';
+export type CapabilityRole = 'provider' | 'augmenter' | 'observer' | 'fallback';
+export interface Capability {
+    name: string;
+    version: string;
+    role?: CapabilityRole;
+    priority?: number;
+}
+export interface CapabilityRequirement {
+    name: string;
+    version: string;
+}
+export interface PluginManifest {
+    id: string;
+    version: string;
+    dataSchemaVersion: number;
+    capabilities: Capability[];
+    requires?: CapabilityRequirement[];
+    isolation: 'process' | 'in-process';
+    /** In-process code is trusted and must not block the JS event loop. */
+    trusted?: boolean;
+    entry: string;
+    /** Optional language-independent JSON-lines executable. */
+    executable?: string;
+    args?: string[];
+    timeoutMs?: number;
+}
+export interface PluginContext {
+    deviceId: string;
+    dataRoot: string;
+    projectRoots: string[];
+    sourceRoots: string[];
+    previousSchemaVersion?: number;
+    settings?: Record<string, unknown>;
+    /** Init-scoped dependency services; invoke/start receive a fresh scope. */
+    services?: PluginServices;
+}
+export interface InvocationContext {
+    signal: AbortSignal;
+    services: PluginServices;
+}
+export interface PluginInstance {
+    start?(context?: InvocationContext): Promise<void> | void;
+    stop?(context?: InvocationContext): Promise<void> | void;
+    invoke(capability: string, input: unknown, context: InvocationContext): Promise<unknown> | unknown;
+}
+export interface PluginModule {
+    createPlugin(context: PluginContext): Promise<PluginInstance> | PluginInstance;
+    migrate?(options: {
+        dataRoot: string;
+        fromVersion: number;
+        toVersion: number;
+    }): Promise<void> | void;
+}
+export type PluginState = 'installed' | 'enabled' | 'disabled' | 'faulted' | 'uninstalled' | 'missing';
+export interface PluginRecord {
+    manifest: PluginManifest;
+    enabled: boolean;
+    installed: boolean;
+    schemaVersion: number;
+    state: PluginState;
+    error?: string;
+    /** Only ensureBundled creates distribution provenance. Unmarked records are user-managed. */
+    installationSource?: 'distribution' | 'manual';
+    /** Persisted gate: replaced distribution bytes must not run under stale metadata. */
+    bundleUpgradeRequired?: {
+        version: string;
+        dataSchemaVersion: number;
+    };
+}
+export declare class CapabilityError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function compatible(version: string, range: string): boolean;
+export declare function validateManifest(value: PluginManifest): void;

package/dist/platform/plugin-contract.js

@@ -0,0 +1,53 @@
+export class CapabilityError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CapabilityError';
+    }
+}
+export function compatible(version, range) {
+    const actual = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!actual)
+        return false;
+    if (range === '*' || range === version)
+        return true;
+    const requested = range.match(/^(?:\^)?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/);
+    if (!requested || actual[1] !== requested[1])
+        return false;
+    if (range.startsWith('^')) {
+        if (!/^\^\d+\.\d+\.\d+$/.test(range))
+            return false;
+        const minor = Number(requested[2] ?? 0), patch = Number(requested[3] ?? 0);
+        if (Number(actual[1]) === 0)
+            return Number(actual[2]) === minor && (minor === 0 ? Number(actual[3]) === patch : Number(actual[3]) >= patch);
+        return Number(actual[2]) > minor || (Number(actual[2]) === minor && Number(actual[3]) >= patch);
+    }
+    return (!requested[2] || /[x*]/.test(requested[2]) || requested[2] === actual[2]) &&
+        (!requested[3] || /[x*]/.test(requested[3]) || requested[3] === actual[3]);
+}
+export function validateManifest(value) {
+    if (!value || !/^[a-z][a-z0-9-]{0,63}$/.test(value.id))
+        throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid plugin id');
+    if (!/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(value.version))
+        throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid plugin version');
+    if (!Number.isSafeInteger(value.dataSchemaVersion) || value.dataSchemaVersion < 1)
+        throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid data schema');
+    if (!['process', 'in-process'].includes(value.isolation) || (value.isolation === 'in-process' && value.trusted !== true))
+        throw new CapabilityError('PLUGIN_ISOLATION_REQUIRED', 'In-process plugins must explicitly declare cooperative trusted execution');
+    if (typeof value.entry !== 'string' || !value.entry || !Array.isArray(value.capabilities) || value.capabilities.length > 128)
+        throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid entry/capabilities');
+    const seen = new Set();
+    for (const c of value.capabilities) {
+        const key = `${c.name}:${c.role ?? 'provider'}`;
+        if (!/^[a-z][a-z0-9_.-]{0,95}$/.test(c.name) || !/^\d+\.\d+\.\d+$/.test(c.version) || seen.has(key) || !['provider', 'augmenter', 'observer', 'fallback'].includes(c.role ?? 'provider'))
+            throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid or duplicate capability');
+        if (c.priority !== undefined && (!Number.isSafeInteger(c.priority) || Math.abs(c.priority) > 10000))
+            throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid capability priority');
+        seen.add(key);
+    }
+    if (new Set((value.requires ?? []).map(requirement => requirement.name)).size !== (value.requires ?? []).length)
+        throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Duplicate capability requirement');
+    for (const r of value.requires ?? [])
+        if (!/^[a-z][a-z0-9_.-]{0,95}$/.test(r.name) || typeof r.version !== 'string' || !(r.version === '*' || /^\^\d+\.\d+\.\d+$/.test(r.version) || /^\d+(?:\.(?:\d+|x|\*)){0,2}$/.test(r.version)))
+            throw new CapabilityError('PLUGIN_MANIFEST_INVALID', 'Invalid capability requirement or unsupported version range');
+}

package/dist/platform/plugin-driver.d.ts

@@ -0,0 +1,8 @@
+import { type PluginContext, type PluginManifest } from './plugin-contract.js';
+import { type DependencyInvoker } from './plugin-services.js';
+export interface PluginDriver {
+    start(): Promise<void>;
+    invoke(capability: string, input: unknown, signal?: AbortSignal): Promise<unknown>;
+    stop(): Promise<void>;
+}
+export declare function createPluginDriver(manifest: PluginManifest, context: PluginContext, fault: (error: Error) => void, invokeDependency?: DependencyInvoker): PluginDriver;