@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/core/chunk.js

@@ -0,0 +1,212 @@
+import { CHUNK_PAYLOAD_FIELDS, ragSourcesWithinBounds } from "../../schema/qvac.js";
+import { chunkTypeOrdinal, mediaKindOrdinal } from '../../schema/helpers.js';
+import { putApprovalRule } from "./approval-rules.js";
+import { linkAttachment } from "./attachment-link.js";
+import { randomId } from "./id.js";
+const CHUNKS = '@qvac/chunks';
+const CHUNKS_BY_CHAT = '@qvac/chunks-by-chat';
+const CHUNKS_BY_TYPE = '@qvac/chunks-by-type';
+const HISTORY_CHUNKS = '@qvac/history-chunks';
+const ATTACHMENTS_BY_MEDIA_KIND = '@qvac/attachments-by-media-kind';
+const ATTACHMENTS_BY_MEDIA_KIND_ORIGIN = '@qvac/attachments-by-media-kind-origin';
+export const HISTORY_CHUNK_TYPES = [
+    'user-message',
+    'run-request',
+    'content',
+    'attachment',
+    'compaction'
+];
+function linkChunks(store, chunks) {
+    const mint = store.attachmentUrl;
+    if (!mint)
+        return chunks;
+    return chunks.map((chunk) => chunk.attachment ? { ...chunk, attachment: linkAttachment(mint, chunk.attachment) } : chunk);
+}
+export function findChunksOfType(snap, chatId, type, { fromSeq, toSeq } = {}) {
+    const ordinal = chunkTypeOrdinal(type);
+    return snap
+        .find(CHUNKS_BY_TYPE, {
+        gte: fromSeq === undefined ? { chatId, type: ordinal } : { chatId, type: ordinal, seq: fromSeq },
+        lte: toSeq === undefined ? { chatId, type: ordinal } : { chatId, type: ordinal, seq: toSeq }
+    })
+        .toArray();
+}
+export async function listChunks(store, { chatId, type, types, fromSeq, reverse, limit }) {
+    const selected = selectedChunkTypes(type, types);
+    if (selected?.length === 0)
+        return [];
+    const options = { reverse: reverse === true, limit: limit || undefined };
+    if (selected && selected.length > 1 && !isHistorySelection(selected)) {
+        throw new Error('multiple chunk types require a mapped index');
+    }
+    const snap = store.view.snapshot();
+    try {
+        if (selected?.length === 1) {
+            const selectedType = chunkTypeOrdinal(selected[0]);
+            const chunks = await snap
+                .find(CHUNKS_BY_TYPE, {
+                gte: fromSeq === undefined
+                    ? { chatId, type: selectedType }
+                    : { chatId, type: selectedType, seq: fromSeq },
+                lte: { chatId, type: selectedType },
+                ...options
+            })
+                .toArray();
+            return linkChunks(store, chunks);
+        }
+        const chunks = await snap
+            .find(selected ? HISTORY_CHUNKS : CHUNKS_BY_CHAT, {
+            gte: fromSeq === undefined ? { chatId } : { chatId, seq: fromSeq },
+            lte: { chatId },
+            ...options
+        })
+            .toArray();
+        return linkChunks(store, chunks);
+    }
+    finally {
+        await snap.close();
+    }
+}
+export async function listAttachmentsByKind(store, { kind, origin, fromCreatedAt, reverse, limit }) {
+    const mediaKind = mediaKindOrdinal(kind);
+    const options = { reverse: reverse === true, limit: limit || undefined };
+    const snap = store.view.snapshot();
+    try {
+        if (origin === undefined) {
+            const chunks = await snap
+                .find(ATTACHMENTS_BY_MEDIA_KIND, {
+                gte: fromCreatedAt === undefined ? { mediaKind } : { mediaKind, createdAt: fromCreatedAt },
+                lte: { mediaKind },
+                ...options
+            })
+                .toArray();
+            return linkChunks(store, chunks);
+        }
+        const generated = origin === 'generated' ? 1 : 0;
+        const chunks = await snap
+            .find(ATTACHMENTS_BY_MEDIA_KIND_ORIGIN, {
+            gte: fromCreatedAt === undefined
+                ? { mediaKind, generated }
+                : { mediaKind, generated, createdAt: fromCreatedAt },
+            lte: { mediaKind, generated },
+            ...options
+        })
+            .toArray();
+        return linkChunks(store, chunks);
+    }
+    finally {
+        await snap.close();
+    }
+}
+function selectedChunkTypes(type, types) {
+    if (!type && types === undefined)
+        return null;
+    const selected = new Set(types);
+    if (type)
+        selected.add(type);
+    return [...selected];
+}
+function isHistorySelection(types) {
+    return (types.length === HISTORY_CHUNK_TYPES.length &&
+        types.every((type) => HISTORY_CHUNK_TYPES.includes(type)));
+}
+export async function getChunk(store, id) {
+    const snap = store.view.snapshot();
+    try {
+        const chunk = await snap.get(CHUNKS, { id });
+        return chunk;
+    }
+    finally {
+        await snap.close();
+    }
+}
+async function mustGetChunk(store, id) {
+    const chunk = await getChunk(store, id);
+    if (!chunk)
+        throw new Error(`chunk not found: ${id}`);
+    return chunk;
+}
+function assertPayloadMatchesType(type, payload) {
+    const field = CHUNK_PAYLOAD_FIELDS[type];
+    for (const candidate of Object.values(CHUNK_PAYLOAD_FIELDS)) {
+        if ((payload[candidate] !== null && payload[candidate] !== undefined) ===
+            (candidate === field)) {
+            continue;
+        }
+        throw new Error(`chunk payload invalid: ${type} carries ${field} and nothing else`);
+    }
+}
+export async function appendChunk(store, { id = randomId(), chatId, runId, type, originDeviceId, parentId, effect, intent, display, rawCall, ...payload }, into = store) {
+    assertPayloadMatchesType(type, payload);
+    if (type === 'sources' && !runId) {
+        throw new Error('chunk payload invalid: a sources chunk requires runId');
+    }
+    if (type === 'sources' && !ragSourcesWithinBounds(payload.sources)) {
+        throw new Error('chunk payload invalid: a sources chunk exceeds its wire bounds');
+    }
+    if (parentId) {
+        const parent = await getChunk(store, parentId);
+        if (!parent || parent.chatId !== chatId) {
+            throw new Error(`chunk payload invalid: parentId is not a chunk in this chat: ${parentId}`);
+        }
+    }
+    const op = {
+        id,
+        chatId,
+        runId,
+        type,
+        originDeviceId,
+        parentId,
+        effect,
+        intent,
+        display,
+        rawCall,
+        createdAt: Date.now(),
+        ...payload
+    };
+    await into.dispatch('append-chunk', op);
+    return { id };
+}
+export async function updateChunk(store, { id, runStatus, attachment }) {
+    const chunk = await mustGetChunk(store, id);
+    await store.dispatch('update-chunk', updateOp(chunk, { id, runStatus, attachment }));
+    const updated = await mustGetChunk(store, id);
+    return updated;
+}
+export function updateOp(chunk, { id, runStatus, attachment }) {
+    if (chunk.type === 'run-status' &&
+        runStatus !== null &&
+        runStatus !== undefined &&
+        (attachment === null || attachment === undefined)) {
+        return { id, runStatus, updatedAt: Date.now() };
+    }
+    if (chunk.type === 'attachment' &&
+        attachment !== null &&
+        attachment !== undefined &&
+        (runStatus === null || runStatus === undefined)) {
+        return { id, attachment, updatedAt: Date.now() };
+    }
+    throw new Error('chunk payload invalid: a run-status edits runStatus, an attachment edits attachment');
+}
+const DEFAULT_APPROVAL_RULE_TTL_MS = 60 * 60 * 1000;
+export async function resolveApproval(store, { id, approved, scope, expiresAt, agentId }) {
+    const before = await getChunk(store, id);
+    const wasPending = before?.type === 'approval-request' && before.approvalRequest?.status === 'pending';
+    await store.dispatch('resolve-approval', { id, approved, resolvedAt: Date.now() });
+    const resolved = await mustGetChunk(store, id);
+    if (scope === 'always' && wasPending) {
+        const ask = resolved.approvalRequest;
+        if (ask && (ask.status === 'approved' || ask.status === 'denied')) {
+            await putApprovalRule(store, {
+                toolName: ask.name,
+                resourceKind: ask.resource?.kind ?? undefined,
+                resourcePattern: ask.resource?.label ?? undefined,
+                decision: ask.status === 'approved' ? 'allow' : 'deny',
+                expiresAt: expiresAt ?? Date.now() + DEFAULT_APPROVAL_RULE_TTL_MS,
+                agentId: ask.agentId ?? agentId,
+                effect: resolved.effect ?? undefined
+            });
+        }
+    }
+    return resolved;
+}

package/dist-lib/lib/core/contract/activity.d.ts

@@ -0,0 +1,11 @@
+import type { AutobeeNode } from 'autobee';
+import type HyperDB from 'hyperdb';
+import type { QvacDevice } from '../../../spec/mesh/hyperschema/types.d.ts';
+import type { RouterContext } from './types.ts';
+type RouteHandler<T> = (op: T, ctx: RouterContext) => Promise<unknown>;
+export declare function trackActivity<T>(handler: RouteHandler<T>): RouteHandler<T>;
+export declare function devicesByWriterKey(tx: HyperDB, writerKey: Buffer): import("hyperdb").HyperDBStream<QvacDevice>;
+export declare function liveDeviceForWriter(db: HyperDB, writerKey: Buffer): Promise<QvacDevice | null>;
+export declare function markWriterRevoked(tx: HyperDB, writerKey: Buffer, revoked: boolean): Promise<void>;
+export declare function recordActivity(tx: HyperDB, node: AutobeeNode, clock: number): Promise<void>;
+export {};

package/dist-lib/lib/core/contract/activity.js

@@ -0,0 +1,45 @@
+const WRITER_ACTIVITY = '@qvac/writer-activity';
+const DEVICES_BY_WRITER_KEY = '@qvac/devices-by-writer-key';
+export function trackActivity(handler) {
+    return async (op, ctx) => {
+        const applied = await handler(op, ctx);
+        if (applied)
+            await recordActivity(ctx.tx, ctx.node, ctx.host.clock);
+        return applied;
+    };
+}
+export function devicesByWriterKey(tx, writerKey) {
+    return tx.find(DEVICES_BY_WRITER_KEY, {
+        gte: { writerKey },
+        lte: { writerKey }
+    });
+}
+export async function liveDeviceForWriter(db, writerKey) {
+    for await (const device of devicesByWriterKey(db, writerKey)) {
+        if (!device.revoked)
+            return device;
+    }
+    return null;
+}
+export async function markWriterRevoked(tx, writerKey, revoked) {
+    const existing = await tx.get(WRITER_ACTIVITY, { writerKey });
+    if (!existing || existing.revoked === revoked)
+        return;
+    await tx.insert(WRITER_ACTIVITY, { ...existing, revoked });
+}
+export async function recordActivity(tx, node, clock) {
+    const existing = await tx.get(WRITER_ACTIVITY, { writerKey: node.key });
+    if (existing && existing.length >= node.length)
+        return;
+    const device = existing ? null : await devicesByWriterKey(tx, node.key).one();
+    const deviceId = existing?.deviceId ?? device?.id;
+    if (!deviceId)
+        return;
+    await tx.insert(WRITER_ACTIVITY, {
+        writerKey: node.key,
+        deviceId,
+        length: node.length,
+        clock,
+        revoked: existing ? existing.revoked : device?.revoked
+    });
+}

package/dist-lib/lib/core/contract/agents.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerAgentRoutes(router: Router): void;

package/dist-lib/lib/core/contract/agents.js

@@ -0,0 +1,29 @@
+import { trackActivity } from "./activity.js";
+const AGENTS = '@qvac/agents';
+export function registerAgentRoutes(router) {
+    router.add('@qvac/put-agent', trackActivity(async ({ agent }, { tx, log }) => {
+        const existing = await tx.get(AGENTS, { id: agent.id });
+        if (existing && existing.updatedAt > agent.updatedAt) {
+            log?.debug('contract', 'put-agent dropped: stale updatedAt', { id: agent.id });
+            return;
+        }
+        await tx.insert(AGENTS, agent);
+        log?.debug('contract', existing ? 'agent updated' : 'agent created', { id: agent.id });
+        return agent;
+    }));
+    router.add('@qvac/migrate-agent-catalog', trackActivity(async ({ agent: healthAssistant }, { tx, log }) => {
+        if (await tx.get(AGENTS, { id: healthAssistant.id }))
+            return false;
+        const legacyDefault = (await tx.find(AGENTS).toArray()).find((agent) => !agent.deletedAt && agent.isDefault && agent.name === 'Agent');
+        if (legacyDefault) {
+            await tx.insert(AGENTS, {
+                ...legacyDefault,
+                version: undefined,
+                name: 'QV.AC'
+            });
+        }
+        await tx.insert(AGENTS, healthAssistant);
+        log?.info('contract', 'agent catalog migrated');
+        return true;
+    }));
+}

package/dist-lib/lib/core/contract/approval-rules.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerApprovalRuleRoutes(router: Router): void;

package/dist-lib/lib/core/contract/approval-rules.js

@@ -0,0 +1,14 @@
+import { trackActivity } from "./activity.js";
+const APPROVAL_RULES = '@qvac/approval-rules';
+export function registerApprovalRuleRoutes(router) {
+    router.add('@qvac/put-approval-rule', trackActivity(async ({ rule }, { tx, log }) => {
+        const existing = await tx.get(APPROVAL_RULES, { id: rule.id });
+        if (existing && existing.updatedAt > rule.updatedAt) {
+            log?.debug('contract', 'put-approval-rule dropped: stale updatedAt', { id: rule.id });
+            return;
+        }
+        await tx.insert(APPROVAL_RULES, rule);
+        log?.info('contract', 'approval rule set', { id: rule.id });
+        return rule;
+    }));
+}

package/dist-lib/lib/core/contract/attestations.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerAttestationRoutes(router: Router): void;

package/dist-lib/lib/core/contract/attestations.js

@@ -0,0 +1,14 @@
+import { verifyDeviceAttestation } from "../device-attestation.js";
+const DEVICE_ATTESTATIONS = '@qvac/device-attestations';
+export function registerAttestationRoutes(router) {
+    router.add('@qvac/attest-device', async (payload, { tx, meshDevicePublicKey, log }) => {
+        if (!verifyDeviceAttestation(meshDevicePublicKey, payload)) {
+            log?.warn('contract', 'attest-device dropped: signature is not over this device id');
+            return;
+        }
+        await tx.insert(DEVICE_ATTESTATIONS, {
+            deviceId: payload.deviceId,
+            signature: payload.signature
+        });
+    });
+}

package/dist-lib/lib/core/contract/chat-group.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerChatGroupRoutes(router: Router): void;

package/dist-lib/lib/core/contract/chat-group.js

@@ -0,0 +1,20 @@
+import { trackActivity } from "./activity.js";
+const CHAT_GROUPS = '@qvac/chat-groups';
+export function registerChatGroupRoutes(router) {
+    router.add('@qvac/put-chat-group', trackActivity(async ({ group }, { tx, log }) => {
+        const existing = await tx.get(CHAT_GROUPS, { id: group.id });
+        if (existing?.deletedAt && !group.deletedAt) {
+            log?.debug('contract', 'put-chat-group dropped: tombstone is sticky', { id: group.id });
+            return;
+        }
+        if (existing && !group.deletedAt && existing.updatedAt > group.updatedAt) {
+            log?.debug('contract', 'put-chat-group dropped: stale updatedAt', { id: group.id });
+            return;
+        }
+        await tx.insert(CHAT_GROUPS, group);
+        log?.debug('contract', existing ? 'chat group updated' : 'chat group created', {
+            id: group.id
+        });
+        return group;
+    }));
+}

package/dist-lib/lib/core/contract/chat.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerChatRoutes(router: Router): void;

package/dist-lib/lib/core/contract/chat.js

@@ -0,0 +1,18 @@
+import { trackActivity } from "./activity.js";
+const CHATS = '@qvac/chats';
+export function registerChatRoutes(router) {
+    router.add('@qvac/put-chat', trackActivity(async ({ chat }, { tx, log }) => {
+        const existing = await tx.get(CHATS, { id: chat.id });
+        if (existing?.deletedAt && !chat.deletedAt) {
+            log?.debug('contract', 'put-chat dropped: tombstone is sticky', { id: chat.id });
+            return;
+        }
+        if (existing && !chat.deletedAt && (existing.updatedAt ?? 0) > (chat.updatedAt ?? 0)) {
+            log?.debug('contract', 'put-chat dropped: stale updatedAt', { id: chat.id });
+            return;
+        }
+        await tx.insert(CHATS, chat);
+        log?.debug('contract', existing ? 'chat updated' : 'chat created', { id: chat.id });
+        return chat;
+    }));
+}

package/dist-lib/lib/core/contract/chunks.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerChunkRoutes(router: Router): void;

package/dist-lib/lib/core/contract/chunks.js

@@ -0,0 +1,156 @@
+import { devicesByWriterKey, trackActivity } from "./activity.js";
+import { CHUNK_PAYLOAD_FIELDS, ragSourcesWithinBounds } from "../../../schema/qvac.js";
+import { chunkTypeOrdinal } from '../../../schema/helpers.js';
+const CHUNKS = '@qvac/chunks';
+const CHUNKS_BY_TYPE = '@qvac/chunks-by-type';
+const CHUNK_COUNTERS = '@qvac/chunk-counters';
+const DEVICES = '@qvac/devices';
+const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
+const CREDITED_CHUNK_TYPES = new Set(['run-request', 'run-status']);
+async function runHasTerminalStatus(tx, chatId, runId) {
+    const type = chunkTypeOrdinal('run-status');
+    const statuses = tx.find(CHUNKS_BY_TYPE, {
+        gte: { chatId, type },
+        lte: { chatId, type }
+    });
+    for await (const chunk of statuses) {
+        if (chunk.runId === runId && TERMINAL_RUN_STATES.has(chunk.runStatus?.state ?? ''))
+            return true;
+    }
+    return false;
+}
+async function isOriginWriter(tx, chunk, writerKey) {
+    const device = await tx.get(DEVICES, { id: chunk.originDeviceId });
+    return Boolean(device?.writerKey?.equals(writerKey));
+}
+async function isAdmittedWriter(tx, writerKey) {
+    for await (const device of devicesByWriterKey(tx, writerKey)) {
+        if (!device.revoked)
+            return true;
+    }
+    return false;
+}
+function payloadMatchesType(op) {
+    const field = CHUNK_PAYLOAD_FIELDS[op.type];
+    for (const candidate of Object.values(CHUNK_PAYLOAD_FIELDS)) {
+        if ((op[candidate] !== null && op[candidate] !== undefined) !== (candidate === field)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function registerChunkRoutes(router) {
+    router.add('@qvac/append-chunk', trackActivity(async (op, { tx, log }) => {
+        const chunk = await tx.get(CHUNKS, { id: op.id });
+        if (chunk)
+            return;
+        if (!payloadMatchesType(op)) {
+            log?.warn('contract', 'append-chunk dropped: payload does not match its type', {
+                id: op.id
+            });
+            return;
+        }
+        if (op.type === 'sources' && !op.runId) {
+            log?.warn('contract', 'append-chunk dropped: a sources chunk requires runId', {
+                id: op.id
+            });
+            return;
+        }
+        if (op.type === 'sources' && !ragSourcesWithinBounds(op.sources)) {
+            log?.warn('contract', 'append-chunk dropped: a sources chunk exceeds its wire bounds', {
+                id: op.id
+            });
+            return;
+        }
+        if (op.type === 'run-status' &&
+            op.runId !== null &&
+            op.runId !== undefined &&
+            (await runHasTerminalStatus(tx, op.chatId, op.runId))) {
+            log?.warn('contract', 'append-chunk dropped: the run already has a terminal run-status', {
+                id: op.id
+            });
+            return;
+        }
+        if (op.parentId !== null && op.parentId !== undefined) {
+            const parent = await tx.get(CHUNKS, { id: op.parentId });
+            if (!parent || parent.chatId !== op.chatId) {
+                log?.warn('contract', 'append-chunk dropped: parentId is not a chunk in this chat', {
+                    id: op.id
+                });
+                return;
+            }
+        }
+        const counter = await tx.get(CHUNK_COUNTERS, { chatId: op.chatId });
+        const prevCount = counter?.count ?? 0;
+        const appended = { ...op, seq: prevCount };
+        await tx.insert(CHUNK_COUNTERS, {
+            chatId: op.chatId,
+            count: prevCount + 1,
+            lastActivityAt: Math.max(counter?.lastActivityAt ?? 0, op.createdAt)
+        });
+        await tx.insert(CHUNKS, appended);
+        return CREDITED_CHUNK_TYPES.has(op.type) ? appended : undefined;
+    }));
+    router.add('@qvac/update-chunk', trackActivity(async (op, { tx, node, log }) => {
+        const chunk = await tx.get(CHUNKS, { id: op.id });
+        if (!chunk) {
+            log?.debug('contract', 'update-chunk dropped: unknown chunk', { id: op.id });
+            return;
+        }
+        if (!(await isOriginWriter(tx, chunk, node.key))) {
+            log?.warn('contract', 'update-chunk dropped: writer is not the origin device', {
+                id: op.id
+            });
+            return;
+        }
+        if (chunk.type === 'run-status' && op.runStatus !== null && op.runStatus !== undefined) {
+            if (op.runStatus.state !== chunk.runStatus?.state) {
+                log?.warn('contract', 'update-chunk dropped: run-status state cannot change in place', {
+                    id: op.id
+                });
+                return;
+            }
+            const next = { ...chunk, runStatus: op.runStatus, updatedAt: op.updatedAt };
+            await tx.insert(CHUNKS, next);
+            return next;
+        }
+        if (chunk.type === 'attachment' && op.attachment !== null && op.attachment !== undefined) {
+            if (chunk.attachment?.deletedAt) {
+                log?.debug('contract', 'update-chunk dropped: attachment is tombstoned', { id: op.id });
+                return;
+            }
+            const next = { ...chunk, attachment: op.attachment, updatedAt: op.updatedAt };
+            await tx.insert(CHUNKS, next);
+            return next;
+        }
+        log?.warn('contract', 'update-chunk dropped: only a run-status (runStatus) or attachment (attachment) edits', { id: op.id });
+    }));
+    router.add('@qvac/resolve-approval', trackActivity(async (op, { tx, node, log }) => {
+        const chunk = await tx.get(CHUNKS, { id: op.id });
+        if (!chunk || chunk.type !== 'approval-request' || !chunk.approvalRequest) {
+            log?.debug('contract', 'resolve-approval dropped: not a known approval-request', {
+                id: op.id
+            });
+            return;
+        }
+        if (chunk.approvalRequest.status !== 'pending')
+            return;
+        if (!(await isAdmittedWriter(tx, node.key))) {
+            log?.warn('contract', 'resolve-approval dropped: writer is not an admitted device', {
+                id: op.id
+            });
+            return;
+        }
+        const resolved = {
+            ...chunk,
+            approvalRequest: {
+                ...chunk.approvalRequest,
+                status: op.approved ? 'approved' : 'denied'
+            },
+            updatedAt: op.resolvedAt
+        };
+        await tx.insert(CHUNKS, resolved);
+        log?.info('contract', `approval ${op.approved ? 'approved' : 'denied'}`, { id: op.id });
+        return resolved;
+    }));
+}

package/dist-lib/lib/core/contract/devices.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerDeviceRoutes(router: Router): void;

package/dist-lib/lib/core/contract/devices.js

@@ -0,0 +1,110 @@
+import { trackActivity } from "./activity.js";
+const DEVICES = '@qvac/devices';
+export function registerDeviceRoutes(router) {
+    router.add('@qvac/register-device', trackActivity(async ({ device }, { tx, node, log }) => {
+        const existing = await tx.get(DEVICES, { id: device.id });
+        if (existing) {
+            log?.debug('contract', 'register-device dropped: device already registered');
+            return;
+        }
+        const registered = {
+            id: device.id,
+            name: device.name,
+            joinedAt: device.joinedAt,
+            capabilityProfile: device.capabilityProfile,
+            recommendedModelName: device.recommendedModelName,
+            revoked: device.revoked,
+            revokedAt: device.revokedAt,
+            writerKey: node.key,
+            installedToolNames: device.installedToolNames,
+            installedSkillNames: device.installedSkillNames,
+            installedModelNames: device.installedModelNames,
+            cachedModelNames: device.cachedModelNames,
+            revokedBy: device.revokedBy,
+            appVersion: device.appVersion,
+            appBuild: device.appBuild,
+            appChannel: device.appChannel,
+            platform: device.platform,
+            readySkillNames: device.readySkillNames
+        };
+        await tx.insert(DEVICES, registered);
+        return registered;
+    }));
+    router.add('@qvac/update-device', trackActivity(async ({ device }, { tx, node, log }) => {
+        const existing = await tx.get(DEVICES, { id: device.id });
+        if (!existing) {
+            log?.debug('contract', 'update-device dropped: unknown device');
+            return;
+        }
+        if (!existing.writerKey?.equals(node.key)) {
+            log?.warn('contract', 'update-device dropped: writer is not the device owner', {
+                id: device.id
+            });
+            return;
+        }
+        const next = { ...existing, name: device.name };
+        await tx.insert(DEVICES, next);
+        return next;
+    }));
+    router.add('@qvac/update-device-profile', trackActivity(async ({ deviceId, capabilityProfile, recommendedModelName, platform }, { tx, node, log }) => {
+        const existing = await tx.get(DEVICES, { id: deviceId });
+        if (!existing) {
+            log?.debug('contract', 'update-device-profile dropped: unknown device');
+            return;
+        }
+        if (!existing.writerKey?.equals(node.key)) {
+            log?.warn('contract', 'update-device-profile dropped: writer is not the device owner', {
+                id: deviceId
+            });
+            return;
+        }
+        const next = {
+            ...existing,
+            capabilityProfile,
+            recommendedModelName,
+            platform: platform ?? existing.platform
+        };
+        await tx.insert(DEVICES, next);
+        return next;
+    }));
+    router.add('@qvac/report-device-capabilities', trackActivity(async ({ deviceId, installedToolNames, installedSkillNames, installedModelNames, cachedModelNames, readySkillNames, toolCatalog }, { tx, node, log }) => {
+        const existing = await tx.get(DEVICES, { id: deviceId });
+        if (!existing) {
+            log?.debug('contract', 'report-device-capabilities dropped: unknown device');
+            return;
+        }
+        if (!existing.writerKey?.equals(node.key)) {
+            log?.warn('contract', 'report-device-capabilities dropped: writer is not the device owner', {
+                id: deviceId
+            });
+            return;
+        }
+        const next = {
+            ...existing,
+            installedToolNames: installedToolNames ?? [],
+            installedSkillNames: installedSkillNames ?? [],
+            installedModelNames: installedModelNames ?? [],
+            cachedModelNames: cachedModelNames ?? [],
+            readySkillNames: readySkillNames ?? existing.readySkillNames,
+            toolCatalog: toolCatalog ?? existing.toolCatalog
+        };
+        await tx.insert(DEVICES, next);
+        return next;
+    }));
+    router.add('@qvac/report-device-version', trackActivity(async ({ deviceId, appVersion, appBuild, appChannel }, { tx, node, log }) => {
+        const existing = await tx.get(DEVICES, { id: deviceId });
+        if (!existing) {
+            log?.debug('contract', 'report-device-version dropped: unknown device');
+            return;
+        }
+        if (!existing.writerKey?.equals(node.key)) {
+            log?.warn('contract', 'report-device-version dropped: writer is not the device owner', {
+                id: deviceId
+            });
+            return;
+        }
+        const next = { ...existing, appVersion, appBuild, appChannel };
+        await tx.insert(DEVICES, next);
+        return next;
+    }));
+}

package/dist-lib/lib/core/contract/index.d.ts

@@ -0,0 +1,2 @@
+import type { Router } from '../../../spec/mesh/hyperdispatch/index.js';
+export declare function registerRoutes(router: Router): void;