@xpert-ai/plugin-spaces 0.0.0-stage → 0.3.0

package/dist/catalog.d.ts

@@ -0,0 +1,196 @@
+import { Repository } from 'typeorm';
+import { SpaceResourcePlacement } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { SpacesService } from './spaces.js';
+import { z } from 'zod/v3';
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { type SpaceActor } from './domain.js';
+export declare const catalogQuery: z.ZodObject<{
+    parentId: z.ZodOptional<z.ZodString>;
+    typeId: z.ZodOptional<z.ZodString>;
+    search: z.ZodOptional<z.ZodString>;
+    deleted: z.ZodOptional<z.ZodBoolean>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    offset: number;
+    search?: string | undefined;
+    deleted?: boolean | undefined;
+    parentId?: string | undefined;
+    typeId?: string | undefined;
+}, {
+    search?: string | undefined;
+    deleted?: boolean | undefined;
+    parentId?: string | undefined;
+    offset?: number | undefined;
+    typeId?: string | undefined;
+}>;
+export declare const catalogCreate: z.ZodObject<{
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    providerKey: z.ZodString;
+    implementationKey: z.ZodString;
+    templateId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodString;
+    title: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    providerKey: string;
+    implementationKey: string;
+    requestId: string;
+    parentId?: string | null | undefined;
+    templateId?: string | undefined;
+}, {
+    title: string;
+    providerKey: string;
+    implementationKey: string;
+    requestId: string;
+    parentId?: string | null | undefined;
+    templateId?: string | undefined;
+}>;
+export declare const catalogLifecycle: z.ZodObject<{
+    contentId: z.ZodString;
+    expectedRevision: z.ZodString;
+    action: z.ZodEnum<["trash", "restore"]>;
+}, "strict", z.ZodTypeAny, {
+    contentId: string;
+    expectedRevision: string;
+    action: "trash" | "restore";
+}, {
+    contentId: string;
+    expectedRevision: string;
+    action: "trash" | "restore";
+}>;
+export declare const catalogMove: z.ZodObject<{
+    contentId: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    expectedVersion: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    parentId: string | null;
+    contentId: string;
+    expectedVersion: number;
+}, {
+    parentId: string | null;
+    contentId: string;
+    expectedVersion: number;
+}>;
+export declare const catalogRename: z.ZodObject<{
+    contentId: z.ZodString;
+    expectedRevision: z.ZodString;
+    title: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    contentId: string;
+    expectedRevision: string;
+}, {
+    title: string;
+    contentId: string;
+    expectedRevision: string;
+}>;
+export declare const catalogDuplicate: z.ZodObject<{
+    contentId: z.ZodString;
+    expectedRevision: z.ZodString;
+    title: z.ZodString;
+} & {
+    requestId: z.ZodString;
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    contentId: string;
+    expectedRevision: string;
+    requestId: string;
+    parentId?: string | null | undefined;
+}, {
+    title: string;
+    contentId: string;
+    expectedRevision: string;
+    requestId: string;
+    parentId?: string | null | undefined;
+}>;
+/** Spaces owns discovery UI only. Resource creation, state and permissions belong to providers. */
+export declare class SpaceCatalog {
+    private readonly runtime;
+    private readonly placements;
+    private readonly spaces;
+    private readonly access;
+    constructor(runtime: RuntimeCapabilityRegistry, placements: Repository<SpaceResourcePlacement>, spaces: SpacesService, access: SpaceAccess);
+    private scope;
+    private get api();
+    backup(actor: SpaceActor, contentId: string): Promise<{
+        fileName: string;
+        content: string;
+    }>;
+    preferences(actor: SpaceActor, contentId: string): Promise<import("@xpert-ai/plugin-sdk").ContentEditorPreferenceState[]>;
+    setPreference(actor: SpaceActor, input: {
+        contentId: string;
+        scope: 'resource' | 'project' | 'organization';
+        editorKey: string | null;
+        expectedRevision: number;
+    }): Promise<import("@xpert-ai/plugin-sdk").ContentEditorPreferenceState>;
+    types(actor: SpaceActor): Promise<(import("@xpert-ai/contracts").ContentTypeImplementation & {
+        providerKey: string;
+    })[]>;
+    list(actor: SpaceActor, input: z.infer<typeof catalogQuery>): Promise<{
+        items: {
+            parentId: string | null;
+            placementVersion: number;
+            compatibleEditors: {
+                key: string;
+                title: string;
+            }[];
+            availability?: "available" | "provider-unavailable";
+            contentId: string;
+            resourceRef: {
+                providerKey: string;
+                resourceId: string;
+            };
+            canWrite: boolean;
+            bindingRevision: number;
+            offlineAccess?: "project";
+            sourceSync?: {
+                status: "synced" | "pending" | "failed";
+                revision?: string;
+            };
+            preview?: {
+                kind: "outline";
+                revision: string;
+                lines: string[];
+            };
+            projectId: string;
+            title: string;
+            revision: string;
+            updatedAt: string;
+            deleted: boolean;
+            source: import("@xpert-ai/contracts").ContentSourceLocation;
+            containedPaths?: Array<{
+                path: string;
+                recursive: boolean;
+            }>;
+            defaultEditorKey: string;
+            allowedActions: import("@xpert-ai/contracts").ContentAction[];
+            typeId: string;
+            modelId: string;
+            schemaVersion: string;
+            editProtocol: {
+                id: string;
+                version: string;
+            };
+        }[];
+        hasMore: boolean;
+    }>;
+    lifecycle(actor: SpaceActor, input: z.infer<typeof catalogLifecycle>): Promise<import("@xpert-ai/contracts").ContentCatalogItem>;
+    rename(actor: SpaceActor, input: z.infer<typeof catalogRename>): Promise<import("@xpert-ai/contracts").ContentCatalogItem>;
+    duplicate(actor: SpaceActor, input: z.infer<typeof catalogDuplicate>): Promise<import("@xpert-ai/contracts").ContentCatalogItem>;
+    create(actor: SpaceActor, input: z.infer<typeof catalogCreate>): Promise<import("@xpert-ai/contracts").ContentCatalogItem>;
+    private place;
+    private parent;
+    move(actor: SpaceActor, input: z.infer<typeof catalogMove>): Promise<{
+        parentId: string | null;
+        version: number;
+        spaceId: string;
+        contentId: string;
+        tenantId: string;
+        organizationId: string;
+        id?: string | undefined;
+        createdAt?: Date | undefined;
+        updatedAt?: Date | undefined;
+    } & SpaceResourcePlacement>;
+}

package/dist/catalog.js

@@ -0,0 +1,140 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { contentBackup } from './content-backup.js';
+import { ConflictException, Inject, Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { Space, SpaceResourcePlacement } from './entities.js';
+import { SpaceAccess } from './access.js';
+import { SpacesService } from './spaces.js';
+import { scoped } from './domain.js';
+import { z } from 'zod/v3';
+import { ContentResourcesRuntimeCapability, ContentEditorsRuntimeCapability, supportsContentModel, XPERT_RUNTIME_CAPABILITIES_TOKEN } from '@xpert-ai/plugin-sdk';
+import { denied } from './domain.js';
+export const catalogQuery = z.object({ parentId: z.string().uuid().optional(), typeId: z.string().min(1).max(200).optional(), search: z.string().max(200).optional(), deleted: z.boolean().optional(), offset: z.number().int().min(0).default(0) }).strict();
+export const catalogCreate = z.object({ parentId: z.string().uuid().nullable().optional(), providerKey: z.string().min(1).max(200), implementationKey: z.string().min(1).max(200), templateId: z.string().min(1).max(200).optional(), requestId: z.string().uuid(), title: z.string().trim().min(1).max(200) }).strict();
+export const catalogLifecycle = z.object({ contentId: z.string().uuid(), expectedRevision: z.string().min(1), action: z.enum(['trash', 'restore']) }).strict();
+export const catalogMove = z.object({ contentId: z.string().uuid(), parentId: z.string().uuid().nullable(), expectedVersion: z.number().int().nonnegative() }).strict();
+export const catalogRename = z.object({ contentId: z.string().uuid(), expectedRevision: z.string().min(1), title: z.string().trim().min(1).max(200) }).strict();
+export const catalogDuplicate = catalogRename.extend({ requestId: z.string().uuid(), parentId: z.string().uuid().nullable().optional() });
+/** Spaces owns discovery UI only. Resource creation, state and permissions belong to providers. */
+let SpaceCatalog = class SpaceCatalog {
+    runtime;
+    placements;
+    spaces;
+    access;
+    constructor(runtime, placements, spaces, access) {
+        this.runtime = runtime;
+        this.placements = placements;
+        this.spaces = spaces;
+        this.access = access;
+    }
+    scope(actor) {
+        if (!actor.projectId)
+            throw denied();
+        return { actor, projectId: actor.projectId, assistantId: actor.assistantId };
+    }
+    get api() { return this.runtime.require(ContentResourcesRuntimeCapability).catalog; }
+    backup(actor, contentId) { return contentBackup(this.runtime, this.scope(actor), contentId); }
+    preferences(actor, contentId) { return this.runtime.require(ContentEditorsRuntimeCapability).preferences({ ...this.scope(actor), contentId }); }
+    setPreference(actor, input) {
+        return this.runtime.require(ContentEditorsRuntimeCapability).setPreference({ ...this.scope(actor), ...input });
+    }
+    async types(actor) { return (await this.api.types(this.scope(actor))).filter(type => type.creatable !== false); }
+    async list(actor, input) {
+        const scope = this.scope(actor);
+        const space = await this.spaces.workspace(actor);
+        if (input.parentId)
+            await this.parent(actor, space.id, input.parentId);
+        const placements = await this.placements.findBy({ ...scoped(actor), spaceId: space.id });
+        const page = await this.api.list({ ...scope, ...input, limit: 50, excludedProviderKeys: ['spaces'],
+            ...(input.parentId ? { contentIds: placements.filter(p => p.parentId === input.parentId).map(p => p.contentId) } : {}) });
+        const editors = await this.runtime.require(ContentEditorsRuntimeCapability).list(scope);
+        // Choices are derived from the same compatibility predicate as the platform resolver.
+        // Opening still reauthorizes and resolves; this list is not an access grant.
+        return { ...page, items: page.items.map(item => ({ ...item,
+                parentId: placements.find(p => p.contentId === item.contentId)?.parentId ?? null,
+                placementVersion: placements.find(p => p.contentId === item.contentId)?.version ?? 0,
+                compatibleEditors: editors.filter(editor => editor.kind === 'resource' && supportsContentModel(editor, item, 'view'))
+                    .map(editor => ({ key: editor.key, title: editor.title })).sort((a, b) => a.key.localeCompare(b.key))
+            })) };
+    }
+    lifecycle(actor, input) {
+        return this.api.mutate({ ...this.scope(actor), contentId: input.contentId, expectedRevision: input.expectedRevision, change: { action: input.action } });
+    }
+    rename(actor, input) {
+        return this.api.mutate({ ...this.scope(actor), contentId: input.contentId, expectedRevision: input.expectedRevision, change: { action: 'rename', title: input.title } });
+    }
+    async duplicate(actor, input) {
+        const space = await this.spaces.workspace(actor);
+        await this.parent(actor, space.id, input.parentId ?? null, true);
+        const item = await this.api.mutate({ ...this.scope(actor), contentId: input.contentId, expectedRevision: input.expectedRevision,
+            change: { action: 'duplicate', requestId: input.requestId, title: input.title } });
+        await this.place(actor, space.id, item.contentId, input.parentId ?? null);
+        return item;
+    }
+    async create(actor, input) {
+        const space = await this.spaces.workspace(actor);
+        await this.parent(actor, space.id, input.parentId ?? null, true);
+        const item = await this.api.create({ ...this.scope(actor), ...input });
+        await this.place(actor, space.id, item.contentId, input.parentId ?? null);
+        return item;
+    }
+    async place(actor, spaceId, contentId, parentId) {
+        // Idempotent creation/copy does not reset a resource that someone has already moved.
+        await this.placements.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: spaceId }, lock: { mode: 'pessimistic_write' } });
+            await this.parent(actor, spaceId, parentId, true);
+            await manager.getRepository(SpaceResourcePlacement).createQueryBuilder().insert().values({ ...scoped(actor), spaceId,
+                contentId, parentId }).orIgnore().execute();
+        });
+    }
+    async parent(actor, spaceId, parentId, write = false) {
+        const parent = await this.access.resource(actor, parentId ?? spaceId, write ? 'write' : 'read');
+        if (parent.space.id !== spaceId || (parent.item && parent.item.kind !== 'folder'))
+            throw denied();
+        if (write) {
+            let cursor = parent.item;
+            const seen = new Set();
+            while (cursor) {
+                if (cursor.syncStatus === 'pending' || cursor.deleted || seen.has(cursor.id))
+                    throw new ConflictException('spaces.version_conflict');
+                seen.add(cursor.id);
+                cursor = cursor.parentId ? await this.access.items.findOneByOrFail({ ...scoped(actor), id: cursor.parentId, spaceId }) : null;
+            }
+        }
+    }
+    async move(actor, input) {
+        const space = await this.spaces.workspace(actor);
+        const item = await this.api.get({ ...this.scope(actor), contentId: input.contentId });
+        if (!item.canWrite)
+            throw denied();
+        return this.placements.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: space.id }, lock: { mode: 'pessimistic_write' } });
+            await this.parent(actor, space.id, input.parentId, true);
+            const repo = manager.getRepository(SpaceResourcePlacement), where = { ...scoped(actor), spaceId: space.id, contentId: input.contentId };
+            const current = await repo.findOneBy(where);
+            if ((current?.version ?? 0) !== input.expectedVersion)
+                throw new ConflictException('spaces.version_conflict');
+            return repo.save({ ...current, ...where, parentId: input.parentId, version: (current?.version ?? 0) + 1 });
+        });
+    }
+};
+SpaceCatalog = __decorate([
+    Injectable(),
+    __param(0, Inject(XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __param(1, InjectRepository(SpaceResourcePlacement)),
+    __metadata("design:paramtypes", [Object, Repository,
+        SpacesService, SpaceAccess])
+], SpaceCatalog);
+export { SpaceCatalog };

package/dist/content-backup.d.ts

@@ -0,0 +1,7 @@
+import { type ContentDocumentScope, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+/** Offline access is an explicit provider delegation. Project membership is checked
+ * again by both the catalog and file APIs; an arbitrary cached path is never sufficient. */
+export declare function contentBackup(runtime: RuntimeCapabilityRegistry, scope: ContentDocumentScope, contentId: string): Promise<{
+    fileName: string;
+    content: string;
+}>;

package/dist/content-backup.js

@@ -0,0 +1,35 @@
+import { BadRequestException } from '@nestjs/common';
+import { ContentResourcesRuntimeCapability, ProjectFilesRuntimeCapability } from '@xpert-ai/plugin-sdk';
+/** Offline access is an explicit provider delegation. Project membership is checked
+ * again by both the catalog and file APIs; an arbitrary cached path is never sufficient. */
+export async function contentBackup(runtime, scope, contentId) {
+    const item = await runtime.require(ContentResourcesRuntimeCapability).catalog.get({ ...scope, contentId });
+    if (item.offlineAccess !== 'project' || item.availability !== 'provider-unavailable')
+        throw new BadRequestException('spaces.editor_unavailable');
+    const files = runtime.require(ProjectFilesRuntimeCapability);
+    let paths;
+    if (item.source.kind === 'file')
+        paths = [item.source.path];
+    else if (item.source.kind === 'bundle') {
+        const root = item.source.rootPath;
+        paths = (await files.list({ actor: scope.actor, projectId: scope.projectId, path: root, depth: 16 })).filter(file => file.kind === 'file').map(file => file.path);
+        if (paths.some(path => !path.startsWith(`${root}/`)))
+            throw new BadRequestException('spaces.invalid_path');
+    }
+    else
+        throw new BadRequestException('spaces.editor_unavailable');
+    if (paths.length > 1000)
+        throw new BadRequestException('spaces.file_too_large');
+    const output = [];
+    let total = 0;
+    for (const path of paths.sort()) {
+        const file = await files.read({ actor: scope.actor, projectId: scope.projectId, path });
+        total += file.buffer.length;
+        if (total > 20 * 1024 * 1024)
+            throw new BadRequestException('spaces.file_too_large');
+        output.push({ path, sha256: file.sha256, contentBase64: file.buffer.toString('base64') });
+    }
+    return { fileName: `${contentId}.source-backup.json`, content: JSON.stringify({ format: 'xpert.content.source-backup', schemaVersion: 1,
+            contentId, resourceRef: item.resourceRef, model: { typeId: item.typeId, modelId: item.modelId, schemaVersion: item.schemaVersion },
+            recordedRevision: item.revision, source: item.source, files: output }) };
+}

package/dist/content-coverage.d.ts

@@ -0,0 +1,9 @@
+import type { ContentCatalogItem } from '@xpert-ai/contracts';
+export type ContentPathCoverage = {
+    path: string;
+    recursive: boolean;
+};
+/** The native provider declares coverage. Never infer ownership from type names,
+ * file extensions or plugin-specific folder conventions in the generic library. */
+export declare function contentCoverage(items: ContentCatalogItem[]): ContentPathCoverage[];
+export declare function coveredByContent(path: string, coverage: ContentPathCoverage[]): boolean;

package/dist/content-coverage.js

@@ -0,0 +1,12 @@
+/** The native provider declares coverage. Never infer ownership from type names,
+ * file extensions or plugin-specific folder conventions in the generic library. */
+export function contentCoverage(items) {
+    return items.flatMap(item => [
+        ...(item.containedPaths ?? []),
+        ...(item.source.kind === 'bundle' ? [{ path: item.source.rootPath, recursive: true }] :
+            item.source.kind === 'file' ? [{ path: item.source.path, recursive: false }] : [])
+    ]);
+}
+export function coveredByContent(path, coverage) {
+    return coverage.some(entry => path === entry.path || entry.recursive && path.startsWith(`${entry.path}/`));
+}

package/dist/content-knowledge.d.ts

@@ -0,0 +1,40 @@
+import { Repository } from 'typeorm';
+import { type ContentCatalogItem } from '@xpert-ai/contracts';
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { SpaceContentIndex, Space } from './entities.js';
+import { type SpaceActor } from './domain.js';
+/** Every result rechecks the live ACL, binding and source revision before returning
+ * cached text, a title or an anchor. Interrupted projections remain retryable. */
+export declare class SpaceContentKnowledge {
+    private readonly rows;
+    private readonly runtime;
+    constructor(rows: Repository<SpaceContentIndex>, runtime: RuntimeCapabilityRegistry);
+    private get catalog();
+    private scope;
+    private all;
+    refresh(actor: SpaceActor, space: Space): Promise<void>;
+    refreshItem(actor: SpaceActor, space: Space, item: ContentCatalogItem): Promise<void>;
+    status(actor: SpaceActor, space: Space): Promise<{
+        itemId: string;
+        title: string;
+        status: string;
+        error: string | null;
+        document: null;
+    }[]>;
+    matches(actor: SpaceActor, space: Space, hits: Array<{
+        metadata?: unknown;
+        pageContent: string;
+    }>): Promise<{
+        itemId: string;
+        contentId: string;
+        title: string;
+        text: string;
+        filePath: string;
+        hash: string;
+        anchor: {
+            kind: string;
+            id: string;
+        };
+    }[]>;
+    verify(actor: SpaceActor, contentId: string, hash: string): Promise<boolean>;
+}

package/dist/content-knowledge.js

@@ -0,0 +1,168 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Injectable, Inject, ForbiddenException, NotFoundException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { createHash } from 'node:crypto';
+import { KBDocumentStatusEnum } from '@xpert-ai/contracts';
+import { ContentResourcesRuntimeCapability, KnowledgebaseDocumentsRuntimeCapability, XPERT_RUNTIME_CAPABILITIES_TOKEN } from '@xpert-ai/plugin-sdk';
+import { z } from 'zod/v3';
+import { SpaceContentIndex } from './entities.js';
+import { scoped } from './domain.js';
+const documentMetadata = z.object({ documentId: z.string().uuid() }).passthrough();
+/** Every result rechecks the live ACL, binding and source revision before returning
+ * cached text, a title or an anchor. Interrupted projections remain retryable. */
+let SpaceContentKnowledge = class SpaceContentKnowledge {
+    rows;
+    runtime;
+    constructor(rows, runtime) {
+        this.rows = rows;
+        this.runtime = runtime;
+    }
+    get catalog() { return this.runtime.require(ContentResourcesRuntimeCapability).catalog; }
+    scope(actor, space) { return { actor, projectId: space.projectId, assistantId: actor.assistantId }; }
+    async all(actor, space, deleted = false) {
+        const items = [];
+        for (let offset = 0;; offset += 100) {
+            const page = await this.catalog.list({ ...this.scope(actor, space), offset, limit: 100, deleted, excludedProviderKeys: ['spaces'] });
+            items.push(...page.items);
+            if (!page.hasMore)
+                return items;
+        }
+    }
+    async refresh(actor, space) {
+        if (!space.knowledgebaseId)
+            return;
+        for (const item of [...await this.all(actor, space), ...await this.all(actor, space, true)])
+            await this.refreshItem(actor, space, item);
+    }
+    async refreshItem(actor, space, item) {
+        if (!space.knowledgebaseId || item.resourceRef.providerKey === 'spaces')
+            return;
+        const documents = this.runtime.require(KnowledgebaseDocumentsRuntimeCapability);
+        const where = { ...scoped(actor), spaceId: space.id, contentId: item.contentId };
+        await this.rows.createQueryBuilder().insert().values({ ...where }).orIgnore().execute();
+        // Serialize only this projection; the durable pending row survives an interruption.
+        await this.rows.manager.transaction(async (manager) => {
+            const repo = manager.getRepository(SpaceContentIndex);
+            const row = await repo.findOneOrFail({ where, lock: { mode: 'pessimistic_write' } });
+            try {
+                if (item.deleted) {
+                    if (row.documents.length)
+                        await documents.deleteDocuments({ knowledgebaseId: space.knowledgebaseId, documentIds: row.documents.map(doc => doc.id) });
+                    await repo.update(row.id, { documents: [], revision: item.revision, bindingRevision: item.bindingRevision, status: 'ready' });
+                    return;
+                }
+                if (row.revision === item.revision && row.bindingRevision === item.bindingRevision && row.documents.length) {
+                    const status = await documents.getDocumentStatus({ knowledgebaseId: space.knowledgebaseId, documentIds: row.documents.map(doc => doc.id) });
+                    const failed = status.documents.filter(doc => doc.status === KBDocumentStatusEnum.ERROR).map(doc => doc.id);
+                    if (failed.length)
+                        await documents.startProcessing({ knowledgebaseId: space.knowledgebaseId, documentIds: failed });
+                    return;
+                }
+                const projection = await this.catalog.projectText({ ...this.scope(actor, space), contentId: item.contentId, expectedRevision: item.revision });
+                if (!projection)
+                    return;
+                const next = [];
+                for (const section of projection.sections.filter(section => section.text.trim())) {
+                    const hash = createHash('sha256').update(JSON.stringify([item.bindingRevision, projection.revision, section])).digest('hex');
+                    const file = await documents.uploadFile({ knowledgebaseId: space.knowledgebaseId, path: `content/${item.contentId}/${hash}`,
+                        file: { buffer: Buffer.from(section.text), originalname: `${hash}.txt` } });
+                    const created = await documents.createDocuments({ knowledgebaseId: space.knowledgebaseId, idempotencyKey: `content:${item.contentId}:${hash}`,
+                        documents: [{ name: item.title, filePath: file.filePath, fileUrl: file.fileUrl, mimeType: 'text/plain', size: file.size,
+                                metadata: { contentId: item.contentId, sourceRevision: item.revision, bindingRevision: item.bindingRevision, anchor: section.anchor } }], process: true });
+                    if (!created.documents[0])
+                        throw new Error('spaces.index_document_missing');
+                    next.push({ id: created.documents[0].id, anchor: section.anchor });
+                }
+                const current = await this.catalog.get({ ...this.scope(actor, space), contentId: item.contentId });
+                if (current.deleted || current.revision !== item.revision || current.bindingRevision !== item.bindingRevision) {
+                    if (next.length)
+                        await documents.deleteDocuments({ knowledgebaseId: space.knowledgebaseId, documentIds: next.map(doc => doc.id) });
+                    await repo.update(row.id, { status: 'pending' });
+                    return;
+                }
+                await repo.update(row.id, { documents: next, revision: item.revision, bindingRevision: item.bindingRevision, status: next.length ? 'processing' : 'ready' });
+                const obsolete = row.documents.filter(doc => !next.some(candidate => candidate.id === doc.id));
+                if (obsolete.length)
+                    await documents.deleteDocuments({ knowledgebaseId: space.knowledgebaseId, documentIds: obsolete.map(doc => doc.id) });
+            }
+            catch {
+                await repo.update(row.id, { status: 'failed' });
+            }
+        });
+    }
+    async status(actor, space) {
+        const result = [];
+        for (const row of await this.rows.findBy({ ...scoped(actor), spaceId: space.id })) {
+            let item;
+            try {
+                item = await this.catalog.get({ ...this.scope(actor, space), contentId: row.contentId });
+            }
+            catch (error) {
+                if (error instanceof ForbiddenException || error instanceof NotFoundException)
+                    continue;
+                throw error;
+            }
+            if (item.deleted || item.availability === 'provider-unavailable')
+                continue;
+            let status = row.revision === item.revision && row.bindingRevision === item.bindingRevision ? row.status : 'pending';
+            if (status === 'processing' && space.knowledgebaseId) {
+                const processing = await this.runtime.require(KnowledgebaseDocumentsRuntimeCapability).getDocumentStatus({ knowledgebaseId: space.knowledgebaseId, documentIds: row.documents.map(doc => doc.id) });
+                status = processing.documents.some(doc => doc.status === KBDocumentStatusEnum.ERROR) ? 'failed'
+                    : processing.documents.length === row.documents.length && processing.documents.every(doc => doc.status === KBDocumentStatusEnum.FINISH) ? 'ready' : 'processing';
+            }
+            result.push({ itemId: row.contentId, title: item.title, status, error: status === 'failed' ? 'spaces.index_failed' : null, document: null });
+        }
+        return result;
+    }
+    async matches(actor, space, hits) {
+        const rows = await this.rows.findBy({ ...scoped(actor), spaceId: space.id });
+        const result = [];
+        for (const hit of hits) {
+            const meta = documentMetadata.safeParse(hit.metadata);
+            if (!meta.success)
+                continue;
+            const row = rows.find(row => row.documents.some(doc => doc.id === meta.data.documentId));
+            if (!row)
+                continue;
+            let item;
+            try {
+                item = await this.catalog.get({ ...this.scope(actor, space), contentId: row.contentId });
+            }
+            catch (error) {
+                if (error instanceof ForbiddenException || error instanceof NotFoundException)
+                    continue;
+                throw error;
+            }
+            if (item.deleted || item.availability === 'provider-unavailable' || item.revision !== row.revision || item.bindingRevision !== row.bindingRevision)
+                continue;
+            result.push({ itemId: item.contentId, contentId: item.contentId, title: item.title, text: hit.pageContent, filePath: '',
+                hash: `${item.bindingRevision}:${item.revision}`, anchor: row.documents.find(doc => doc.id === meta.data.documentId).anchor });
+        }
+        return result;
+    }
+    async verify(actor, contentId, hash) {
+        if (!actor.projectId)
+            return false;
+        const item = await this.catalog.get({ actor, projectId: actor.projectId, assistantId: actor.assistantId, contentId });
+        return !item.deleted && `${item.bindingRevision}:${item.revision}` === hash;
+    }
+};
+SpaceContentKnowledge = __decorate([
+    Injectable(),
+    __param(0, InjectRepository(SpaceContentIndex)),
+    __param(1, Inject(XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [Repository, Object])
+], SpaceContentKnowledge);
+export { SpaceContentKnowledge };

package/dist/content.d.ts

@@ -0,0 +1,19 @@
+import type { ContentDocumentProposal } from '@xpert-ai/contracts';
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { SpaceAccess } from './access.js';
+import { type SpaceActor, type PagePatch } from './domain.js';
+/** Spaces owns navigation metadata. The platform exclusively owns document state, sessions and review. */
+export declare class SpaceContent {
+    private readonly access;
+    private readonly runtime;
+    constructor(access: SpaceAccess, runtime: RuntimeCapabilityRegistry);
+    api(): import("@xpert-ai/plugin-sdk").ContentDocumentsApi;
+    scope(actor: SpaceActor, resourceId: string): {
+        actor: SpaceActor;
+        projectId: string;
+        assistantId: string | undefined;
+        resourceId: string;
+    };
+    open(actor: SpaceActor, resourceId: string): Promise<import("@xpert-ai/plugin-sdk").ContentDocumentState>;
+    propose(actor: SpaceActor, patch: PagePatch): Promise<ContentDocumentProposal>;
+}