@tequila99/githuman 0.11.0 → 0.12.0

package/dist/server/routes/artifact-actions.js

@@ -0,0 +1,129 @@
+import { Value } from '@sinclair/typebox/value';
+import { ArtifactValidationInspectionSchema, ArtifactActionInspectionSchema, ArtifactActionListSchema, ArtifactStoredChangeSetSchema, ArtifactValidationViewSchema, ArtifactReportChunkSchema, ArtifactValidationReportQuery, ArtifactHistoryQuery, ArtifactParams, ArtifactChangeSetProposeBody, ArtifactValidationPrepareBody, ArtifactValidationStartBody, ArtifactLifecycleCommitBody, ArtifactAuthorizationRequestBody, ArtifactAuthorizationApproveBody, ArtifactLifecycleResultSchema } from "../../shared/artifacts/schemas.js";
+import { DefinitionQuery } from "../../shared/tasks/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+import { ArtifactInputError } from "../errors/artifacts.js";
+import { artifactUserActor } from "../utils/artifact-actor.js";
+import { artifactSessionId } from "../services/artifact-lifecycle.service.js";
+export async function artifactActionRoutes(app, options) {
+    const { service } = options;
+    function post(url, body, run) {
+        app.post(url, {
+            preHandler: options.recheckAccess,
+            validatorCompiler: ({ httpPart }) => data => Value.Check(httpPart === 'params' ? ArtifactParams : body, data)
+                ? { value: data }
+                : { error: new ArtifactInputError('Invalid artifact action.') },
+            schema: {
+                tags: ['artifacts'],
+                summary: 'Execute a structured artifact lifecycle action',
+                ...(url.includes(':id') ? { params: ArtifactParams } : {}),
+                body,
+                response: { 200: ArtifactLifecycleResultSchema, ...ERROR_RESPONSES }
+            }
+        }, run);
+    }
+    post('/api/artifact-change-sets', ArtifactChangeSetProposeBody, request => service.propose(request.body, artifactUserActor(request)));
+    post('/api/artifact-validations', ArtifactValidationPrepareBody, request => service.jobs.get(service.prepare(request.body.changeSetId, request.body.version).id));
+    post('/api/artifact-validations/:id/start', ArtifactValidationStartBody, request => service.jobs.start(request.params.id, request.body.presetId, request.access?.device.status === 'device'
+        ? request.access.device.device.id
+        : undefined));
+    post('/api/artifact-change-sets/:id/commit', ArtifactLifecycleCommitBody, request => service.commit(request.params.id, request.body, artifactUserActor(request)));
+    post('/api/artifact-actions', ArtifactAuthorizationRequestBody, request => service.authorization.request(request.body, artifactSessionId(artifactUserActor(request))));
+    post('/api/artifact-actions/:id/approve', ArtifactAuthorizationApproveBody, request => service.storage.catalog.transaction(() => service.authorization.approve(request.params.id, request)));
+    app.get('/api/artifact-change-sets/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read the current immutable proposal version',
+            params: ArtifactParams,
+            response: { 200: ArtifactStoredChangeSetSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.get(request.params.id));
+    app.get('/api/artifact-validations/:id/check', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Inspect validation freshness and exact post-state',
+            params: ArtifactParams,
+            response: {
+                200: ArtifactValidationInspectionSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => service.inspectValidation(request.params.id));
+    app.get('/api/artifact-validations/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read validation status and report summary',
+            params: ArtifactParams,
+            response: { 200: ArtifactValidationViewSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.jobs.get(request.params.id));
+    app.get('/api/artifact-validations/:id/manifest', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read a bounded manifest page',
+            params: ArtifactParams,
+            querystring: DefinitionQuery,
+            response: { 200: ArtifactLifecycleResultSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.jobs.manifest(request.params.id, request.query.limit, request.query.cursor));
+    app.get('/api/artifact-validations/:id/report', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read the complete structured report in bounded chunks',
+            params: ArtifactParams,
+            querystring: ArtifactValidationReportQuery,
+            response: { 200: ArtifactReportChunkSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.jobs.report(request.params.id, request.query.offset));
+    app.get('/api/artifact-validations/:id/history', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read immutable validation state history',
+            params: ArtifactParams,
+            querystring: ArtifactHistoryQuery,
+            response: { 200: ArtifactLifecycleResultSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.jobs.history(request.params.id, request.query.afterSeq, request.query.limit));
+    app.get('/api/artifact-actions', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read pending actions awaiting explicit user confirmation',
+            response: { 200: ArtifactActionListSchema, ...ERROR_RESPONSES }
+        }
+    }, () => ({
+        storeId: service.storage.storeId,
+        items: service.authorization.list()
+    }));
+    app.get('/api/artifact-actions/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Inspect the exact pending or authorized action scope',
+            params: ArtifactParams,
+            response: { 200: ArtifactActionInspectionSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.inspectAction(request.params.id, artifactUserActor(request)));
+    app.delete('/api/artifact-actions/:id', {
+        preHandler: options.recheckAccess,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Revoke a pending action or authorization',
+            params: ArtifactParams,
+            response: { 200: ArtifactLifecycleResultSchema, ...ERROR_RESPONSES }
+        }
+    }, request => {
+        service.authorization.revoke(request.params.id);
+        return { revoked: true };
+    });
+    app.delete('/api/artifact-validations/:id', {
+        preHandler: options.recheckAccess,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Cancel a running validation job',
+            params: ArtifactParams,
+            response: { 200: ArtifactLifecycleResultSchema, ...ERROR_RESPONSES }
+        }
+    }, request => {
+        service.jobs.cancel(request.params.id);
+        return service.jobs.get(request.params.id);
+    });
+}

package/dist/server/routes/artifact-agent.js

@@ -0,0 +1,183 @@
+import { artifactSessionId } from "../services/artifact-lifecycle.service.js";
+import { Value } from '@sinclair/typebox/value';
+import { ArtifactToolSchemas, ArtifactBridgeBody, ArtifactBridgeParams, ArtifactBridgeResponse } from "../../shared/artifact-tools/schemas.js";
+import { ARTIFACT_BRIDGE_ROUTE, ARTIFACT_BRIDGE_BODY_LIMIT } from "../../shared/artifacts/mcp-constants.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+import { ArtifactInputError } from "../errors/artifacts.js";
+import { ForbiddenError } from "../errors/http.js";
+function checked(schema, run) {
+    return (input, actor) => {
+        if (!Value.Check(schema, input)) {
+            throw new ArtifactInputError('Invalid artifact tool parameters.');
+        }
+        return run(input, actor);
+    };
+}
+export async function artifactAgentRoutes(app, { storage, registry }) {
+    const operations = new Map([
+        [
+            'artifacts.search',
+            checked(ArtifactToolSchemas['artifacts.search'], p => storage.search.search(p))
+        ],
+        [
+            'change_sets.propose',
+            checked(ArtifactToolSchemas['change_sets.propose'], (p, a) => storage.lifecycle.propose(p, a))
+        ],
+        [
+            'change_sets.get',
+            checked(ArtifactToolSchemas['change_sets.get'], p => storage.lifecycle.get(p.id))
+        ],
+        [
+            'change_sets.commit',
+            checked(ArtifactToolSchemas['change_sets.commit'], ({ id, ...p }, a) => storage.lifecycle.commit(id, p, a))
+        ],
+        [
+            'validations.prepare',
+            checked(ArtifactToolSchemas['validations.prepare'], p => storage.lifecycle.jobs.get(storage.lifecycle.prepare(p.changeSetId, p.version).id))
+        ],
+        [
+            'validations.start',
+            checked(ArtifactToolSchemas['validations.start'], (p, a) => storage.lifecycle.jobs.start(p.id, p.presetId, undefined, a.id))
+        ],
+        [
+            'validations.report',
+            checked(ArtifactToolSchemas['validations.report'], p => storage.lifecycle.jobs.report(p.id, p.offset))
+        ],
+        [
+            'validations.history',
+            checked(ArtifactToolSchemas['validations.history'], p => storage.lifecycle.jobs.history(p.id, p.afterSeq, p.limit))
+        ],
+        [
+            'validations.get',
+            checked(ArtifactToolSchemas['validations.get'], p => storage.lifecycle.jobs.get(p.id))
+        ],
+        [
+            'validations.manifest',
+            checked(ArtifactToolSchemas['validations.manifest'], p => storage.lifecycle.jobs.manifest(p.id, p.limit, p.cursor))
+        ],
+        [
+            'validations.read',
+            checked(ArtifactToolSchemas['validations.read'], (p, a) => storage.lifecycle.jobs.read(p.id, a.id, p.key, p.offset))
+        ],
+        [
+            'validations.submit',
+            checked(ArtifactToolSchemas['validations.submit'], ({ id, ...p }, a) => storage.lifecycle.jobs.submit(id, a.id, p))
+        ],
+        [
+            'validations.create_report',
+            checked(ArtifactToolSchemas['validations.create_report'], (p, a) => storage.lifecycle.jobs.createReport(p.id, a.id, p.body))
+        ],
+        [
+            'actions.request',
+            checked(ArtifactToolSchemas['actions.request'], (p, a) => storage.lifecycle.authorization.request(p, artifactSessionId(a)))
+        ],
+        [
+            'actions.status',
+            checked(ArtifactToolSchemas['actions.status'], (p, a) => storage.lifecycle.authorization.status(p.id, artifactSessionId(a)))
+        ],
+        [
+            'artifacts.create',
+            checked(ArtifactToolSchemas['artifacts.create'], (p, a) => storage.create(p, a, registry.get(a.id)?.turnTaskContext))
+        ],
+        [
+            'artifacts.update_metadata',
+            checked(ArtifactToolSchemas['artifacts.update_metadata'], ({ id, ...p }, a) => storage.updateMetadata(id, p, a))
+        ],
+        [
+            'artifacts.get',
+            checked(ArtifactToolSchemas['artifacts.get'], p => storage.get(p.id))
+        ],
+        [
+            'artifacts.list',
+            checked(ArtifactToolSchemas['artifacts.list'], p => storage.list(p.limit, p.cursor))
+        ],
+        [
+            'artifacts.get_content',
+            checked(ArtifactToolSchemas['artifacts.get_content'], (p, a) => storage.lifecycle.jobs.isValidator(a.id)
+                ? storage.lifecycle.jobs.contentForSession(a.id, p.id, p.offset)
+                : storage.readContent(p.id, p.offset, p.limit))
+        ],
+        [
+            'artifacts.history',
+            checked(ArtifactToolSchemas['artifacts.history'], p => storage.history(p.id, p.afterSeq, p.limit))
+        ],
+        [
+            'artifacts.relations',
+            checked(ArtifactToolSchemas['artifacts.relations'], ({ id, ...options }) => storage.graph.relations(id, options))
+        ],
+        [
+            'artifacts.ancestry',
+            checked(ArtifactToolSchemas['artifacts.ancestry'], p => storage.graph.ancestry(p.id, p.limit, p.cursor))
+        ],
+        [
+            'tasks.list',
+            checked(ArtifactToolSchemas['tasks.list'], p => storage.tasks.list(p.limit, p.cursor))
+        ],
+        [
+            'tasks.get',
+            checked(ArtifactToolSchemas['tasks.get'], p => storage.tasks.get(p.id))
+        ],
+        [
+            'tasks.create',
+            checked(ArtifactToolSchemas['tasks.create'], (p, a) => storage.tasks.create(p.requestId, p.input, a))
+        ],
+        [
+            'tasks.get_context',
+            checked(ArtifactToolSchemas['tasks.get_context'], (_p, a) => storage.tasks.getContext(a))
+        ],
+        [
+            'tasks.activate',
+            checked(ArtifactToolSchemas['tasks.activate'], (p, a) => storage.tasks.activate(p, a))
+        ],
+        [
+            'tasks.create_and_activate',
+            checked(ArtifactToolSchemas['tasks.create_and_activate'], (p, a) => storage.tasks.createAndActivate(p, a))
+        ],
+        [
+            'tasks.update',
+            checked(ArtifactToolSchemas['tasks.update'], (p, a) => storage.tasks.update(p.id, p.requestId, p.expectedVersion, p.input, a))
+        ],
+        [
+            'types.list',
+            checked(ArtifactToolSchemas['types.list'], p => storage.types.list(p.limit, p.cursor))
+        ],
+        [
+            'types.get',
+            checked(ArtifactToolSchemas['types.get'], p => storage.types.get(p.id))
+        ],
+        [
+            'types.create',
+            checked(ArtifactToolSchemas['types.create'], (p, a) => storage.types.create(p.requestId, p.id, p.input, a))
+        ],
+        [
+            'types.update',
+            checked(ArtifactToolSchemas['types.update'], (p, a) => storage.types.update(p.id, p.requestId, p.expectedVersion, p.input, a))
+        ]
+    ]);
+    app.post(ARTIFACT_BRIDGE_ROUTE, {
+        bodyLimit: ARTIFACT_BRIDGE_BODY_LIMIT,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Call a session-scoped artifact tool',
+            params: ArtifactBridgeParams,
+            body: ArtifactBridgeBody,
+            response: {
+                200: ArtifactBridgeResponse,
+                403: ERROR_RESPONSES['4xx'],
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => {
+        // The access hook checked the key before parsing. Check again: the session may close during parsing.
+        const sessionId = registry.authenticateArtifactKey(request.headers.authorization);
+        if (!sessionId) {
+            throw new ForbiddenError('Artifact session access denied.');
+        }
+        storage.lifecycle.jobs.assertOperation(sessionId, request.params.operation, request.body);
+        const operation = operations.get(request.params.operation);
+        if (!operation) {
+            throw new ArtifactInputError('Artifact operation is unavailable.');
+        }
+        return operation(request.body, { kind: 'agent', id: sessionId });
+    });
+}

package/dist/server/routes/artifact-definitions.js

@@ -0,0 +1,163 @@
+import { ArtifactChangeSetPreviewSchema } from "../../shared/artifacts/schemas.js";
+import { TaskSchema, TaskCreateBody, TaskUpdateBody, TaskListSchema, ArtifactTypeSchema, ArtifactTypeCreateBody, ArtifactTypeUpdateBody, ArtifactTypeListSchema, DefinitionParams, DefinitionQuery, definitionHistoryPageSchema, SessionTaskBody, SessionTaskSchema, TaskChatLinksPageSchema, TaskChatHistorySchema } from "../../shared/tasks/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+import { artifactUserActor } from "../utils/artifact-actor.js";
+import { ArtifactAncestrySchema, ArtifactGraphPageSchema, GraphPageQuery, ArtifactChangeSetSchema } from "../../shared/artifacts/schemas.js";
+const response = (schema) => ({
+    200: schema,
+    ...ERROR_RESPONSES
+});
+export async function artifactDefinitionRoutes(app, { storage }) {
+    const typed = app.withTypeProvider();
+    typed.get('/api/tasks', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'List persistent tasks',
+            querystring: DefinitionQuery,
+            response: { 200: TaskListSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.tasks.list(request.query.limit, request.query.cursor, request.query.search));
+    typed.get('/api/tasks/:id', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Read a task',
+            params: DefinitionParams,
+            response: response(TaskSchema)
+        }
+    }, request => storage.tasks.get(request.params.id));
+    typed.post('/api/tasks', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Create a minimal task',
+            body: TaskCreateBody,
+            response: response(TaskSchema)
+        }
+    }, request => storage.tasks.create(request.body.requestId, request.body.input, artifactUserActor(request)));
+    typed.patch('/api/tasks/:id', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Update a task definition with version checking',
+            params: DefinitionParams,
+            body: TaskUpdateBody,
+            response: response(TaskSchema)
+        }
+    }, request => storage.tasks.update(request.params.id, request.body.requestId, request.body.expectedVersion, request.body.input, artifactUserActor(request)));
+    typed.get('/api/tasks/:id/history', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Read task definition history',
+            params: DefinitionParams,
+            querystring: DefinitionQuery,
+            response: {
+                200: definitionHistoryPageSchema(TaskSchema),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => storage.tasks.historyPage(request.params.id, request.query.limit, request.query.cursor));
+    typed.get('/api/tasks/:id/sessions', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Read task session links including unavailable sessions',
+            params: DefinitionParams,
+            querystring: DefinitionQuery,
+            response: { 200: TaskChatLinksPageSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.tasks.linksPage(request.params.id, request.query.limit, request.query.cursor));
+    typed.get('/api/tasks/:id/sessions/history', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Read persistent task-session link history',
+            params: DefinitionParams,
+            querystring: DefinitionQuery,
+            response: { 200: TaskChatHistorySchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.tasks.linkHistoryPage(request.params.id, request.query.limit, request.query.cursor));
+    typed.get('/api/tasks/sessions/:id', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Read live session task assignment',
+            params: DefinitionParams,
+            response: { 200: SessionTaskSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.tasks.assignment(request.params.id));
+    typed.patch('/api/tasks/sessions/:id', {
+        schema: {
+            tags: ['tasks'],
+            summary: 'Assign tasks to a live server session',
+            params: DefinitionParams,
+            body: SessionTaskBody,
+            response: { 200: SessionTaskSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.tasks.assignSession(request.params.id, request.body, artifactUserActor(request)));
+    typed.get('/api/artifact-types', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'List artifact types including inactive definitions',
+            querystring: DefinitionQuery,
+            response: { 200: ArtifactTypeListSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.types.list(request.query.limit, request.query.cursor, request.query.search));
+    typed.get('/api/artifact-types/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read an artifact type',
+            params: DefinitionParams,
+            response: response(ArtifactTypeSchema)
+        }
+    }, request => storage.types.get(request.params.id));
+    typed.post('/api/artifact-types', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Create an artifact type',
+            body: ArtifactTypeCreateBody,
+            response: response(ArtifactTypeSchema)
+        }
+    }, request => storage.types.create(request.body.requestId, request.body.id, request.body.input, artifactUserActor(request)));
+    typed.patch('/api/artifact-types/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Update an artifact type without removing its history',
+            params: DefinitionParams,
+            body: ArtifactTypeUpdateBody,
+            response: response(ArtifactTypeSchema)
+        }
+    }, request => storage.types.update(request.params.id, request.body.requestId, request.body.expectedVersion, request.body.input, artifactUserActor(request)));
+    typed.get('/api/artifact-types/:id/history', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read artifact type history',
+            params: DefinitionParams,
+            querystring: DefinitionQuery,
+            response: {
+                200: definitionHistoryPageSchema(ArtifactTypeSchema),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => storage.types.historyPage(request.params.id, request.query.limit, request.query.cursor));
+    typed.get('/api/artifacts/:id/relations', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read forward or reverse graph edges',
+            params: DefinitionParams,
+            querystring: GraphPageQuery,
+            response: { 200: ArtifactGraphPageSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.graph.relations(request.params.id, request.query));
+    typed.get('/api/artifacts/:id/ancestry', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read immutable revision ancestry',
+            params: DefinitionParams,
+            querystring: DefinitionQuery,
+            response: { 200: ArtifactAncestrySchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.graph.ancestry(request.params.id, request.query.limit, request.query.cursor));
+    typed.post('/api/artifacts/change-sets/preview', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Preview a canonical change set without applying it',
+            body: ArtifactChangeSetSchema,
+            response: { 200: ArtifactChangeSetPreviewSchema, ...ERROR_RESPONSES }
+        }
+    }, request => storage.graph.previewChangeSet(request.body));
+}

package/dist/server/routes/artifact-transitions.js

@@ -0,0 +1,80 @@
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+import { ArtifactParams } from "../../shared/artifacts/schemas.js";
+import { ArtifactTransitionOperationListSchema, ArtifactTransitionOperationSchema, ArtifactTransitionOptionsSchema, ArtifactTransitionParams, ArtifactTransitionPreviewBody, ArtifactTransitionPreviewSchema, ArtifactTransitionStartBody } from "../../shared/artifact-transitions/schemas.js";
+import { artifactUserActor } from "../utils/artifact-actor.js";
+/** Status-change routes of ADR 0107; they accept only user access, never an agent key. */
+export async function artifactTransitionRoutes(app, options) {
+    const { service } = options;
+    app.get('/api/artifacts/:id/transitions', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'List the statuses a user can choose for an artifact',
+            params: ArtifactParams,
+            response: { 200: ArtifactTransitionOptionsSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.options(request.params.id));
+    app.post('/api/artifacts/:id/transition-previews', {
+        preHandler: options.recheckAccess,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Preview the exact consequences of a status change',
+            params: ArtifactParams,
+            body: ArtifactTransitionPreviewBody,
+            response: {
+                200: ArtifactTransitionPreviewSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => service.preview(request.params.id, request.body.targetStatus, artifactUserActor(request)));
+    app.get('/api/artifacts/:id/transition-operations', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'List recent status-change operations of an artifact',
+            params: ArtifactParams,
+            response: {
+                200: ArtifactTransitionOperationListSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => service.list(request.params.id));
+    app.post('/api/artifact-transition-operations', {
+        preHandler: options.recheckAccess,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Confirm a previewed status change and start the operation',
+            body: ArtifactTransitionStartBody,
+            response: {
+                200: ArtifactTransitionOperationSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => service.begin(request.body, artifactUserActor(request), request.access?.device.status === 'device'
+        ? request.access.device.device.id
+        : undefined));
+    app.get('/api/artifact-transition-operations/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read a status-change operation',
+            params: ArtifactTransitionParams,
+            response: {
+                200: ArtifactTransitionOperationSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => service.operation(request.params.id));
+    app.post('/api/artifact-transition-operations/:id/cancel', {
+        preHandler: options.recheckAccess,
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Request cancellation before the change is applied',
+            params: ArtifactTransitionParams,
+            response: {
+                200: ArtifactTransitionOperationSchema,
+                ...ERROR_RESPONSES
+            }
+        }
+    }, request => {
+        artifactUserActor(request);
+        return service.cancel(request.params.id);
+    });
+}

package/dist/server/routes/artifacts.js

@@ -0,0 +1,111 @@
+import { ArtifactExportService } from "../services/artifact-export.service.js";
+import { ArtifactExportQuery, ArtifactOriginalExportSchema, ArtifactMetadataExportSchema, ArtifactSearchBody, ArtifactSearchQuery, ArtifactSearchSchema, ArtifactSearchDiagnosticsSchema, ArtifactContentQuery, ArtifactContentSchema, ArtifactHistoryQuery, ArtifactHistorySchema, ArtifactListQuery, ArtifactListSchema, ArtifactParams, ArtifactSchema } from "../../shared/artifacts/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+export async function artifactRoutes(app, { service }) {
+    const typed = app.withTypeProvider();
+    const exports = new ArtifactExportService(service);
+    // The schema describes the downloaded file; Fastify sends exact buffers or pre-serialized JSON streams.
+    typed.get('/api/artifacts/:id/export', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Download the original bytes or consistent metadata history',
+            params: ArtifactParams,
+            querystring: ArtifactExportQuery,
+            response: {
+                200: {
+                    description: 'Exact original Markdown file or streamed metadata history snapshot.',
+                    content: {
+                        'text/markdown': { schema: ArtifactOriginalExportSchema },
+                        'application/json': { schema: ArtifactMetadataExportSchema }
+                    }
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, (request, reply) => {
+        const id = request.params.id;
+        if (request.query.format === 'original') {
+            const { artifact, content } = exports.original(id);
+            reply.header('Content-Disposition', `attachment; filename="artifact-${id}.md"`);
+            reply.header('X-Artifact-SHA256', artifact.sha256);
+            reply.type('text/markdown; charset=utf-8');
+            reply.send(content);
+            return;
+        }
+        const stream = exports.metadataHistory(id);
+        reply.header('Content-Disposition', `attachment; filename="artifact-${id}.metadata-history.json"`);
+        reply.type('application/json; charset=utf-8');
+        const close = () => stream.destroy();
+        reply.raw.once('close', close);
+        stream.once('close', () => reply.raw.removeListener('close', close));
+        reply.send(stream);
+    });
+    typed.get('/api/artifacts/search', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Search verified artifact titles and body text',
+            querystring: ArtifactSearchQuery,
+            response: { 200: ArtifactSearchSchema, ...ERROR_RESPONSES }
+        }
+    }, request => {
+        const { status, typeId, taskId, tag, ...query } = request.query;
+        return service.search.search({
+            ...query,
+            filters: {
+                ...(status ? { statuses: [status] } : {}),
+                ...(typeId ? { typeIds: [typeId] } : {}),
+                ...(taskId ? { taskIds: [taskId] } : {}),
+                ...(tag ? { tags: [tag] } : {})
+            }
+        });
+    });
+    typed.post('/api/artifacts/search', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Search with multiple metadata filters',
+            body: ArtifactSearchBody,
+            response: { 200: ArtifactSearchSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.search.search(request.body));
+    typed.get('/api/artifacts/search/diagnostics', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read derived search index diagnostics',
+            response: { 200: ArtifactSearchDiagnosticsSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.search.diagnostics());
+    typed.get('/api/artifacts', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'List committed artifacts',
+            querystring: ArtifactListQuery,
+            response: { 200: ArtifactListSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.list(request.query.limit, request.query.cursor));
+    typed.get('/api/artifacts/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read current artifact metadata',
+            params: ArtifactParams,
+            response: { 200: ArtifactSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.get(request.params.id));
+    typed.get('/api/artifacts/:id/content', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read verified immutable artifact content',
+            params: ArtifactParams,
+            querystring: ArtifactContentQuery,
+            response: { 200: ArtifactContentSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.readContent(request.params.id, request.query.offset, request.query.limit));
+    typed.get('/api/artifacts/:id/history', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read immutable artifact history',
+            params: ArtifactParams,
+            querystring: ArtifactHistoryQuery,
+            response: { 200: ArtifactHistorySchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.history(request.params.id, request.query.afterSeq, request.query.limit));
+}