@undefineds.co/xpod 0.4.20 → 0.4.25

package/dist/api/chatkit/pod-store.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PodChatKitStore = void 0;
+const models_1 = require("@undefineds.co/models");
+const TaskAgentBinding_1 = require("../tasks/TaskAgentBinding");
 /**
  * Pod-based ChatKit Store
  *
@@ -18,6 +20,8 @@ const global_logger_factory_1 = require("global-logger-factory");
 const types_1 = require("./types");
 const schema_1 = require("./schema");
 const schema_2 = require("../runs/schema");
+const ConditionalResourceDocument_1 = require("../runs/ConditionalResourceDocument");
+const RunStateMerge_1 = require("../runs/RunStateMerge");
 const store_1 = require("../runs/store");
 const schema_3 = require("../tasks/schema");
 const store_2 = require("../tasks/store");
@@ -32,11 +36,13 @@ const defaultEmbeddingProfile_1 = require("../../ai/service/defaultEmbeddingProf
 const AiCredentialSecret_1 = require("../../ai/service/AiCredentialSecret");
 const tables_1 = require("../../credential/schema/tables");
 const types_2 = require("../../credential/schema/types");
-const models_1 = require("@undefineds.co/models");
+const models_2 = require("@undefineds.co/models");
 const reconciler_1 = require("../reconciler");
 const protocol_metadata_1 = require("../protocol-metadata");
 const ReaderAiConfig_1 = require("../../document/ReaderAiConfig");
 const schema = {
+    approvalResource: models_1.approvalResource,
+    sessionResource: models_1.sessionResource,
     chat: schema_1.Chat,
     thread: schema_1.Thread,
     message: schema_1.Message,
@@ -63,6 +69,7 @@ class PodChatKitStore {
         // Track recently created message IDs to avoid SELECT cache timing issues
         this.recentlyCreatedIds = new Set();
         this.podAccess = options.podAccess;
+        this.podBaseUrlResolver = options.podBaseUrlResolver;
         this.credentialSecretDecoder = options.credentialSecretDecoder ?? AiCredentialSecret_1.defaultAiCredentialSecretDecoder;
         this.deployment = options.deployment;
         this.serverGroupReconcilerService = options.serverGroupReconcilerService;
@@ -70,7 +77,7 @@ class PodChatKitStore {
     /** Build a Pod-scoped context for trusted internal maintenance jobs. */
     async createTrustedContext(input) {
         const db = (0, drizzle_solid_1.drizzle)({ fetch: input.fetch, info: { webId: input.webId, isLoggedIn: true } }, { schema });
-        await db.init(schema_1.Chat, schema_1.Thread, schema_1.Message, schema_2.Run, schema_2.RunStep, schema_3.Task, config_1.AIConfig, tables_1.Credential);
+        await db.init(schema_1.Chat, schema_1.Thread, schema_1.Message, schema_2.Run, schema_2.RunStep, schema_3.Task, config_1.AIConfig, tables_1.Credential, models_1.approvalResource, models_1.sessionResource);
         const context = {
             webId: input.webId,
             podUrl: input.podUrl,
@@ -92,21 +99,59 @@ class PodChatKitStore {
      * for a Pod it could not open reports a state the user cannot act on.
      */
     async getDb(context) {
-        // Check if we already have a cached db in context
-        if (context._cachedDb) {
+        // Internal contexts may carry a database opened with an already verified explicit binding
+        // (including Standalone). Never reuse that database after the context selects another root.
+        const cachedDb = context._cachedDb;
+        if (cachedDb) {
+            const explicitRoot = this.readExplicitPodBaseUrl(context);
+            const boundRoot = this.readPodUrlFromDatabase(cachedDb) ?? this.getCachedPodBaseUrl(context);
+            if (explicitRoot && boundRoot && explicitRoot !== boundRoot) {
+                throw new Error('Authoritative Pod storage binding changed on cached context');
+            }
+            // A cached database/fetch belongs to one credential binding. If the context now selects a
+            // different caller key or task grant, the old connection must not be reused.
+            const expectedAuth = context._cachedAuth;
+            if (expectedAuth && expectedAuth !== this.podCredentialBinding(context)) {
+                throw new Error('Authoritative Pod credential binding changed on cached context');
+            }
             this.logger.debug('Using cached db from context');
-            return context._cachedDb;
+            return cachedDb;
+        }
+        // A single request fans out with Promise.all (for example `GET /api/tasks`); without an
+        // in-flight guard each concurrent caller would resolve the same credential and open its own
+        // Pod database. The promise is bound to this request's context and cleared once settled, so
+        // it never outlives the request or crosses credentials.
+        const inFlight = context._cachedDbPromise;
+        if (inFlight) {
+            return inFlight;
+        }
+        const opening = this.openDb(context);
+        context._cachedDbPromise = opening;
+        try {
+            return await opening;
+        }
+        finally {
+            if (context._cachedDbPromise === opening) {
+                delete context._cachedDbPromise;
+            }
         }
+    }
+    async openDb(context) {
         const auth = context.auth;
         if (!auth || !(0, AuthContext_1.isSolidAuth)(auth) || !auth.webId) {
             this.logger.warn('No valid solid auth in context, cannot access Pod');
             throw new Error(CallerPodAccess_1.CALLER_POD_ACCESS_UNAVAILABLE);
         }
         // One credential path for every caller: the owner's own Pod key, exchanged for a
-        // token this process can prove, or the caller's reusable token.
+        // token this process can prove, or the caller's reusable token. Unattended work carries a
+        // task-layer grant, which is forwarded so the Pod fetch is bound to that exact grant.
+        const taskCredential = context.taskCredential;
         let podFetch;
         try {
-            podFetch = await this.podAccess?.getPodFetch(auth.webId, { auth });
+            podFetch = await this.podAccess?.getPodFetch(auth.webId, {
+                auth,
+                ...(taskCredential ? { taskCredential } : {}),
+            });
         }
         catch (error) {
             this.logger.error(`Failed to obtain Pod access for ${auth.webId}: ${error}`);
@@ -117,10 +162,15 @@ class PodChatKitStore {
             this.logger.warn(`No usable Pod credential for ${auth.webId}: ${reason}`);
             throw new Error(reason);
         }
-        const db = (0, drizzle_solid_1.drizzle)({ fetch: podFetch, info: { webId: auth.webId, isLoggedIn: true } }, { schema });
+        const podBaseUrl = this.readExplicitPodBaseUrl(context)
+            ?? this.normalizePodBaseUrl(await this.podBaseUrlResolver?.(auth.webId));
+        if (!podBaseUrl) {
+            throw new Error('Authoritative Pod storage binding unavailable');
+        }
+        const db = (0, drizzle_solid_1.drizzle)({ fetch: podFetch, info: { webId: auth.webId, isLoggedIn: true } }, { schema, podUrl: podBaseUrl });
         this.logger.info(`Initializing tables for Pod: ${auth.webId}`);
         try {
-            await db.init(schema_1.Chat, schema_1.Thread, schema_1.Message, schema_2.Run, schema_2.RunStep, schema_3.Task, config_1.AIConfig, tables_1.Credential);
+            await db.init(schema_1.Chat, schema_1.Thread, schema_1.Message, schema_2.Run, schema_2.RunStep, schema_3.Task, config_1.AIConfig, tables_1.Credential, models_1.approvalResource, models_1.sessionResource);
             this.logger.info('Tables initialized successfully');
         }
         catch (initError) {
@@ -129,9 +179,22 @@ class PodChatKitStore {
         context._cachedDb = db;
         context._cachedFetch = podFetch;
         context._cachedWebId = auth.webId;
-        this.ensurePodBaseUrlCache(context, db, auth.webId);
+        context._cachedAuth = this.podCredentialBinding(context);
+        this.ensurePodBaseUrlCache(context, db);
         return db;
     }
+    /** Stable identity of the credential binding behind a cached database, without secrets. */
+    podCredentialBinding(context) {
+        const auth = context.auth;
+        const task = context.taskCredential;
+        return JSON.stringify({
+            webId: auth && (0, AuthContext_1.isSolidAuth)(auth) ? auth.webId : null,
+            clientId: auth && (0, AuthContext_1.isSolidAuth)(auth) ? auth.clientId ?? null : null,
+            taskCredential: task
+                ? { ref: task.credentialRef ?? null, version: task.version ?? null, ownerGrant: task.ownerGrant ?? null }
+                : null,
+        });
+    }
     /**
      * 从 context 获取 webId
      */
@@ -142,42 +205,6 @@ class PodChatKitStore {
         }
         return undefined;
     }
-    derivePodBaseUrl(webId) {
-        if (!webId) {
-            return undefined;
-        }
-        try {
-            const url = new URL(webId);
-            url.hash = '';
-            url.search = '';
-            const normalizedPath = url.pathname.replace(/\/+$/, '');
-            if (!normalizedPath.endsWith('/profile/card')) {
-                return undefined;
-            }
-            const podPath = normalizedPath.slice(0, -'/profile/card'.length) || '/';
-            if (podPath === '/') {
-                return url.origin;
-            }
-            url.pathname = podPath;
-            return url.toString().replace(/\/$/, '');
-        }
-        catch {
-            const withoutHash = webId.split('#')[0]?.replace(/\/+$/, '');
-            if (!withoutHash?.endsWith('/profile/card')) {
-                return undefined;
-            }
-            const podBase = withoutHash.slice(0, -'/profile/card'.length) || '/';
-            if (podBase === '/') {
-                try {
-                    return new URL(webId).origin;
-                }
-                catch {
-                    return undefined;
-                }
-            }
-            return podBase.endsWith('/') ? podBase.slice(0, -1) : podBase;
-        }
-    }
     normalizePodBaseUrl(value) {
         if (typeof value !== 'string') {
             return undefined;
@@ -218,6 +245,8 @@ class PodChatKitStore {
         }
         return undefined;
     }
+    // Only read databases from trusted internal contexts or openDb, which supplies an owned
+    // explicit podUrl before construction. An unconnected WebID-derived SDK root is not authority.
     readPodUrlFromDatabase(db) {
         if (!db || typeof db !== 'object') {
             return undefined;
@@ -259,9 +288,9 @@ class PodChatKitStore {
         }
         return undefined;
     }
-    ensurePodBaseUrlCache(context, db, fallbackWebId) {
+    ensurePodBaseUrlCache(context, db) {
         const authoritativePodBaseUrl = this.readExplicitPodBaseUrl(context)
-            ?? this.readPodUrlFromDatabase(db);
+            ?? this.readPodUrlFromDatabase(db ?? context._cachedDb);
         if (authoritativePodBaseUrl) {
             context._cachedPodBaseUrl = authoritativePodBaseUrl;
             return authoritativePodBaseUrl;
@@ -270,11 +299,7 @@ class PodChatKitStore {
         if (cached) {
             return cached;
         }
-        const podBaseUrl = this.derivePodBaseUrl(fallbackWebId ?? this.getWebId(context));
-        if (podBaseUrl) {
-            context._cachedPodBaseUrl = podBaseUrl;
-        }
-        return podBaseUrl;
+        return undefined;
     }
     /**
      * 将 ThreadStatus 对象转为字符串
@@ -693,6 +718,23 @@ class PodChatKitStore {
         }
         return resource;
     }
+    /**
+     * Report a relation stored in this Pod as the same opaque resource id business code uses.
+     * The ORM's own `parsePodResourceRef` extracts it relative to the relation's resource base
+     * (`/.data/task/`, `/.data/`, ...). Only collapse the reference when that ID resolves
+     * back to the exact original IRI through this context's verified database binding.
+     */
+    toResourceRelation(resource, value, context) {
+        if (!value) {
+            return undefined;
+        }
+        if (!/^https?:\/\//.test(value)) {
+            return value;
+        }
+        const id = (0, drizzle_solid_1.parsePodResourceRef)(resource, value)?.resourceId;
+        const db = context._cachedDb;
+        return id && this.readPodUrlFromDatabase(db) && resource.buildIriForDatabase(db, id) === value ? id : value;
+    }
     baseRelativeIdFromPodPath(resource, context, podPath) {
         const normalizedPath = podPath.replace(/^\/+|\/+$/g, '');
         const podBaseUrl = this.ensurePodBaseUrlCache(context);
@@ -709,15 +751,15 @@ class PodChatKitStore {
         }
         return resource;
     }
-    runRecordToData(record) {
+    runRecordToData(record, context) {
         const metadata = this.parseJsonObject(record.metadata);
         return {
             id: record.id || '',
-            task: record.task || undefined,
-            delivery: record.delivery || undefined,
+            task: this.toResourceRelation(schema_3.Task, record.task, context),
+            delivery: this.toResourceRelation(models_1.deliveryResource, record.delivery, context),
             trigger: record.trigger || undefined,
             input: record.input || undefined,
-            thread: record.thread || '',
+            thread: this.toResourceRelation(schema_1.Thread, record.thread, context) ?? '',
             workspace: record.workspace || '',
             status: (record.status || 'queued'),
             runner: record.runner || '',
@@ -737,26 +779,32 @@ class PodChatKitStore {
     }
     runStepRecordToData(record, context) {
         const payload = this.parseJsonObject(record.payload) ?? this.parseJsonObject(record.data);
-        const runId = record.runId
-            || (record.run ? this.baseRelativeIdFromResource(record.run, context) : '');
+        const run = this.toResourceRelation(schema_2.Run, record.run, context);
         return {
             id: record.id || '',
-            runId,
-            run: record.run || '',
+            runId: record.runId || run || '',
+            run: run || '',
             type: record.type || record.stepType || 'runtime.event',
             message: record.message || undefined,
             data: this.withoutXpodMetadata(payload),
             createdAt: this.isoToTimestamp(record.createdAt) ?? (0, types_1.nowTimestamp)(),
         };
     }
-    taskRecordToData(record) {
+    taskRecordToData(record, context) {
         const metadata = this.parseJsonObject(record.metadata);
         const xpod = this.getXpodMetadata(metadata);
         return {
             id: record.id || '',
             title: record.title || undefined,
-            prompt: record.prompt || '',
-            thread: record.thread || '',
+            prompt: record.instruction || record.prompt || '',
+            // Legacy scheduled tasks predate assignedTo; their binding identifies the default agent.
+            assignedTo: record.assignedTo || (this.parseTaskAuthBinding(metadata?.authBinding) ? TaskAgentBinding_1.DEFAULT_TASK_AGENT.iri : undefined),
+            source: record.source || undefined,
+            dueAt: this.isoToTimestamp(record.dueAt),
+            completedAt: this.isoToTimestamp(record.completedAt),
+            notes: record.notes || undefined,
+            priority: record.priority || undefined,
+            thread: this.toResourceRelation(schema_1.Thread, record.thread, context) ?? '',
             workspace: record.workspace || '',
             runner: record.runner || (typeof xpod?.runner === 'string' ? xpod.runner : ''),
             status: (record.status || 'active'),
@@ -1062,7 +1110,7 @@ class PodChatKitStore {
     async loadThreads(limit, after, order, context) {
         const db = await this.getDb(context);
         try {
-            const threads = await models_1.threadRepository.list(db);
+            const threads = await models_2.threadRepository.list(db);
             const metadataById = new Map();
             for (const thread of threads) {
                 const metadata = this.threadRecordToMetadata(thread);
@@ -1326,13 +1374,18 @@ class PodChatKitStore {
             surfaceId: resolvedThread.surfaceId,
             createdAt: item.created_at,
         });
-        // 如果是最近创建的消息，使用直接 PATCH 更新（避免 drizzle-solid UPDATE 的 bug）
+        const values = { content };
+        if (status !== null)
+            values.status = status;
+        if (metadata !== null)
+            values.metadata = metadata;
+        // 如果是最近创建的消息，其 RDF 已由 addThreadItem 写入，直接条件更新即可
         const wasRecentlyCreated = this.recentlyCreatedIds.has(itemResourceId);
         if (wasRecentlyCreated) {
             this.recentlyCreatedIds.delete(itemResourceId);
             item.id = itemResourceId;
             item.thread_id = resolvedThread.threadId;
-            await this.directPatchMessage(context, itemResourceId, content, status, metadata);
+            await this.updateConditionalMessage(context, itemResourceId, values);
             return;
         }
         // 对于非最近创建的消息，使用普通流程
@@ -1340,10 +1393,9 @@ class PodChatKitStore {
             .filter((message) => message.id === itemResourceId);
         const existing = existingItems.length > 0 ? existingItems[0] : null;
         if (existing) {
-            // 使用直接 PATCH 更新
             item.id = itemResourceId;
             item.thread_id = resolvedThread.threadId;
-            await this.directPatchMessage(context, existing.id, content, status, metadata);
+            await this.updateConditionalMessage(context, existing.id, values);
         }
         else {
             // Create new record
@@ -1351,66 +1403,34 @@ class PodChatKitStore {
         }
     }
     /**
-     * 直接使用 SPARQL UPDATE PATCH 更新消息内容
-     * 避免 drizzle-solid UPDATE 的 bug
+     * Conditionally update a Message through the shared strong-ETag serializer.
+     *
+     * The previous hand-rolled SPARQL UPDATE wrote `metadata` as a flat literal and
+     * never updated the inline child node, so nested metadata (protocols/arguments/
+     * output with quotes) became invalid JSON on the Pod and was lost on reload. See
+     * docs/issues/chatkit-metadata-roundtrip.md. This reuses the ORM INSERT serializer
+     * (which emits the correct nested child triples) inside the existing
+     * `updateConditionalResource` document boundary.
      */
-    async directPatchMessage(context, messageResourceId, content, status, metadata = null) {
-        // 使用缓存的 fetch 和 webId（由 getDb 时创建的 session）
-        const cachedFetch = context._cachedFetch;
-        if (!cachedFetch) {
-            throw new Error('No cached session for direct PATCH - call getDb first');
-        }
-        const messageResource = this.resolveDataResource(messageResourceId, context);
-        const hashIndex = messageResource.lastIndexOf('#');
-        const resourceUrl = hashIndex >= 0 ? messageResource.slice(0, hashIndex) : messageResource;
-        // 构建 SPARQL UPDATE：删除旧值，插入新值
-        const deletePatterns = [];
-        const insertTriples = [];
-        // 转义特殊字符
-        const escapeForSparql = (value) => {
-            const hasQuotes = value.includes('"');
-            const hasNewlines = value.includes('\n') || value.includes('\r');
-            if (hasQuotes || hasNewlines) {
-                // 使用三引号
-                let escaped = value;
-                escaped = escaped.replace(/"""/g, '"\\"\\""');
-                if (escaped.endsWith('"')) {
-                    const match = escaped.match(/"*$/);
-                    const trailingQuotes = match ? match[0].length : 0;
-                    if (trailingQuotes > 0) {
-                        escaped = escaped.slice(0, -trailingQuotes) + '\\"'.repeat(trailingQuotes);
-                    }
+    async updateConditionalMessage(context, messageResourceId, values) {
+        const db = await this.getDb(context);
+        const iri = this.resolveDataResource(messageResourceId, context);
+        await (0, ConditionalResourceDocument_1.updateConditionalResource)({
+            iri, fetch: this.runDocumentFetch(context), columns: schema_1.Message.columns,
+            serialize: insert => db.insert(schema_1.Message).values({ id: messageResourceId, ...insert }).toSPARQL().query,
+            update: quads => {
+                // The ORM serializer applies column defaults (role/createdAt). Carry the existing
+                // values so they are replaced in place rather than appended as a second value.
+                const stable = { ...values };
+                for (const field of ['role', 'createdAt']) {
+                    const predicate = schema_1.Message.columns[field].options.predicate;
+                    const current = predicate ? (0, ConditionalResourceDocument_1.resourceLiteral)(quads, iri, predicate) : undefined;
+                    if (current !== undefined)
+                        stable[field] = current;
                 }
-                return `"""${escaped}"""`;
-            }
-            return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-        };
-        // Content 更新
-        deletePatterns.push(`<${messageResource}> <http://rdfs.org/sioc/ns#content> ?oldContent .`);
-        insertTriples.push(`<${messageResource}> <http://rdfs.org/sioc/ns#content> ${escapeForSparql(content)} .`);
-        // Status 更新
-        if (status) {
-            deletePatterns.push(`<${messageResource}> <https://undefineds.co/ns#messageStatus> ?oldStatus .`);
-            insertTriples.push(`<${messageResource}> <https://undefineds.co/ns#messageStatus> "${status}" .`);
-        }
-        if (metadata) {
-            deletePatterns.push(`<${messageResource}> <https://undefineds.co/ns#metadata> ?oldMetadata .`);
-            insertTriples.push(`<${messageResource}> <https://undefineds.co/ns#metadata> ${escapeForSparql(JSON.stringify(metadata))} .`);
-        }
-        const sparql = `
-DELETE { ${deletePatterns.join(' ')} }
-INSERT { ${insertTriples.join(' ')} }
-WHERE { ${deletePatterns.join(' ')} }
-    `.trim();
-        const response = await cachedFetch(resourceUrl, {
-            method: 'PATCH',
-            headers: { 'Content-Type': 'application/sparql-update' },
-            body: sparql,
+                return { result: undefined, values: stable };
+            },
         });
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(`Direct PATCH failed: ${response.status} ${response.statusText} - ${text}`);
-        }
     }
     async directDeleteMessage(context, resource) {
         if (!resource) {
@@ -1470,7 +1490,51 @@ WHERE { ${deletePatterns.join(' ')} }
         const db = await this.getDb(context);
         run.id = (0, store_1.buildRunResourceId)(run);
         const existing = await db.findById(schema_2.Run, run.id);
-        const values = {
+        if (!existing) {
+            await db.insert(schema_2.Run).values({ id: run.id, ...this.runValues(run) });
+            return;
+        }
+        const merged = await this.updateRunDocument(run, context);
+        Object.assign(run, merged);
+    }
+    async updateRunDocument(run, context, guard) {
+        const db = await this.getDb(context);
+        const iri = this.resolveDataResource(run.id, context);
+        return (0, ConditionalResourceDocument_1.updateConditionalResource)({
+            iri, fetch: this.runDocumentFetch(context), columns: schema_2.Run.columns,
+            serialize: values => db.insert(schema_2.Run).values({ id: run.id, ...values }).toSPARQL().query,
+            update: quads => {
+                const scalar = (field) => (0, ConditionalResourceDocument_1.resourceLiteral)(quads, iri, schema_2.Run.columns[field].options.predicate);
+                const status = scalar('status');
+                if (!status || !Object.values(schema_2.RunStatus).includes(status))
+                    throw new Error('Run has invalid persisted status');
+                const timestamp = (field) => {
+                    const value = scalar(field);
+                    if (value === undefined)
+                        return undefined;
+                    const parsed = Date.parse(value) / 1000;
+                    if (!Number.isFinite(parsed))
+                        throw new Error('Run has invalid persisted timestamp');
+                    return parsed;
+                };
+                const current = { status: status,
+                    cancelRequestedAt: timestamp('cancelRequestedAt'), completedAt: timestamp('completedAt'),
+                    updatedAt: timestamp('updatedAt') ?? run.updatedAt, leaseOwner: scalar('leaseOwner'), leaseExpiresAt: timestamp('leaseExpiresAt') };
+                if (guard && !guard(current))
+                    return { result: undefined };
+                const result = (0, RunStateMerge_1.mergeRunCancellation)(run, current);
+                return { result, values: this.runValues(result) };
+            },
+        });
+    }
+    runDocumentFetch(context) {
+        const authenticatedFetch = context._cachedFetch;
+        if (!authenticatedFetch)
+            throw new Error('Run conditional writes require authenticated Pod access');
+        return authenticatedFetch;
+    }
+    runValues(run) {
+        return {
             task: run.task || null,
             delivery: run.delivery || null,
             trigger: run.trigger || null,
@@ -1492,14 +1556,6 @@ WHERE { ${deletePatterns.join(' ')} }
             completedAt: this.timestampToIso(run.completedAt),
             updatedAt: this.timestampToIso(run.updatedAt) ?? new Date().toISOString(),
         };
-        if (existing) {
-            await db.updateById(schema_2.Run, run.id, values);
-            return;
-        }
-        await db.insert(schema_2.Run).values({
-            id: run.id,
-            ...values,
-        });
     }
     async loadRun(id, context) {
         const db = await this.getDb(context);
@@ -1507,7 +1563,7 @@ WHERE { ${deletePatterns.join(' ')} }
         if (!record) {
             throw new Error(`Run not found: ${id}`);
         }
-        return this.runRecordToData(record);
+        return this.runRecordToData(record, context);
     }
     async listRuns(options, context) {
         const db = await this.getDb(context);
@@ -1528,22 +1584,42 @@ WHERE { ${deletePatterns.join(' ')} }
         const records = conditions.length > 0
             ? await query.where((0, drizzle_solid_1.and)(...conditions))
             : await query;
-        const runs = records.map((record) => this.runRecordToData(record));
+        const runs = records.map((record) => this.runRecordToData(record, context));
         return runs
             .sort((a, b) => b.createdAt - a.createdAt || b.id.localeCompare(a.id))
             .slice(0, options.limit ?? runs.length);
     }
+    async getPodBaseUrl(context) {
+        const db = await this.getDb(context);
+        const root = this.ensurePodBaseUrlCache(context, db);
+        if (!root)
+            throw new Error('Authoritative Pod storage binding unavailable');
+        return root;
+    }
     async appendRunStep(event, context) {
         const db = await this.getDb(context);
         if (!(0, store_1.isRunResourceId)(event.runId)) {
             throw new Error(`RunStep runId must be a complete Run resource id: ${event.runId}`);
         }
         event.id = (0, store_1.buildRunStepResourceId)(event);
-        const runResource = event.run || this.resolveDataResource(event.runId, context);
+        // Relations are opaque base-relative ids; the ORM resolves them against this Pod's configured
+        // storage when it serializes. An explicit absolute relation is only acceptable when it is the
+        // current Run in this Pod: a relation that points at another Pod is rejected, never rebound.
+        const expectedRunId = event.runId;
+        if (event.run) {
+            const currentRunIri = this.resolveDataResource(expectedRunId, context);
+            const matches = /^https?:\/\//.test(event.run)
+                ? event.run === currentRunIri
+                : event.run === expectedRunId;
+            if (!matches) {
+                throw new Error('RunStep run relation does not match the current Pod Run');
+            }
+        }
+        const run = event.run || expectedRunId;
         await db.insert(schema_2.RunStep).values({
             id: event.id,
             stepType: event.type,
-            run: runResource,
+            run,
             message: event.message || null,
             payload: this.jsonObjectOrNull(event.data),
             createdAt: this.timestampToIso(event.createdAt) ?? new Date().toISOString(),
@@ -1554,8 +1630,8 @@ WHERE { ${deletePatterns.join(' ')} }
         if (!(0, store_1.isRunResourceId)(runId)) {
             throw new Error(`loadRunSteps requires a base-relative Run id: ${runId}`);
         }
-        const resolvedRun = this.resolveDataResource(runId, context);
-        const records = await db.select().from(schema_2.RunStep).where((0, drizzle_solid_1.eq)(schema_2.RunStep.run, resolvedRun));
+        // Opaque base-relative id; the ORM resolves it against this Pod's configured storage.
+        const records = await db.select().from(schema_2.RunStep).where((0, drizzle_solid_1.eq)(schema_2.RunStep.run, runId));
         return records
             .map((record) => this.runStepRecordToData(record, context))
             .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
@@ -1569,9 +1645,12 @@ WHERE { ${deletePatterns.join(' ')} }
         run.leaseExpiresAt = input.leaseExpiresAt;
         run.heartbeatAt = input.now;
         run.updatedAt = input.now;
-        await this.saveRun(run, context);
-        const claimed = await this.loadRun(input.runId, context);
-        return claimed.leaseOwner === input.leaseOwner ? claimed : undefined;
+        return this.updateRunDocument(run, context, current => {
+            if (!(0, store_1.canClaimRun)(current, input))
+                return false;
+            run.status = current.status;
+            return true;
+        });
     }
     async claimClientToolContinuation(input, context) {
         const item = await this.loadItem(input.threadRef, input.itemId, context);
@@ -1585,53 +1664,34 @@ WHERE { ${deletePatterns.join(' ')} }
         const run = await this.loadRun(runId, context);
         const waitingTool = run.metadata?.waitingTool;
         if (run.status !== schema_2.RunStatus.WAITING_INPUT
+            || run.cancelRequestedAt !== undefined
             || (run.leaseOwner && run.leaseExpiresAt && run.leaseExpiresAt > input.now)
             || typeof waitingTool !== 'object'
             || waitingTool.itemId !== item.id) {
             return undefined;
         }
-        const db = await this.getDb(context);
-        const updatedAt = this.timestampToIso(input.now);
-        const expectedLease = run.leaseOwner
-            ? (0, drizzle_solid_1.eq)(schema_2.Run.leaseOwner, run.leaseOwner)
-            : (0, drizzle_solid_1.isNull)(schema_2.Run.leaseOwner);
-        const updated = await db.update(schema_2.Run)
-            .set({
-            leaseOwner: input.claimId,
-            leaseExpiresAt: this.timestampToIso(input.leaseExpiresAt),
-            heartbeatAt: updatedAt,
-            updatedAt,
-        })
-            .where((0, drizzle_solid_1.and)((0, drizzle_solid_1.eq)(schema_2.Run.id, run.id), (0, drizzle_solid_1.eq)(schema_2.Run.status, schema_2.RunStatus.WAITING_INPUT), (0, drizzle_solid_1.eq)(schema_2.Run.updatedAt, this.timestampToIso(run.updatedAt)), expectedLease))
-            .returning()
-            .execute();
-        if (updated.length !== 1) {
+        const updated = await this.updateRunDocument({ ...run,
+            leaseOwner: input.claimId, leaseExpiresAt: input.leaseExpiresAt,
+            heartbeatAt: input.now, updatedAt: input.now,
+        }, context, current => current.cancelRequestedAt === undefined && current.status === schema_2.RunStatus.WAITING_INPUT
+            && current.updatedAt === run.updatedAt && current.leaseOwner === run.leaseOwner);
+        if (!updated) {
             return undefined;
         }
         return {
             claimId: input.claimId,
             threadRef: input.threadRef,
             item,
-            run: this.runRecordToData(updated[0]),
+            run: updated,
         };
     }
     async releaseClientToolContinuation(claim, now, context) {
-        const db = await this.getDb(context);
-        const released = await db.update(schema_2.Run)
-            .set({
-            status: schema_2.RunStatus.WAITING_INPUT,
-            leaseOwner: null,
-            leaseExpiresAt: null,
-            heartbeatAt: this.timestampToIso(now),
-            completedAt: null,
-            error: claim.run.error ?? null,
-            metadata: this.jsonObjectOrNull(claim.run.metadata),
-            updatedAt: this.timestampToIso(now),
-        })
-            .where((0, drizzle_solid_1.and)((0, drizzle_solid_1.eq)(schema_2.Run.id, claim.run.id), (0, drizzle_solid_1.eq)(schema_2.Run.leaseOwner, claim.claimId)))
-            .returning()
-            .execute();
-        if (released.length !== 1) {
+        const released = await this.updateRunDocument({ ...claim.run,
+            status: schema_2.RunStatus.WAITING_INPUT, leaseOwner: undefined, leaseExpiresAt: undefined,
+            heartbeatAt: now, completedAt: undefined, updatedAt: now,
+        }, context, current => current.cancelRequestedAt === undefined && current.status !== schema_2.RunStatus.CANCELLED
+            && current.leaseOwner === claim.claimId);
+        if (!released) {
             return false;
         }
         await this.saveItem(claim.threadRef, {
@@ -1644,10 +1704,64 @@ WHERE { ${deletePatterns.join(' ')} }
     // =========================================================================
     // Task Operations
     // =========================================================================
+    sameApprovalThread(db, left, right) {
+        if (!left || !right)
+            return left === right;
+        // Linked RDF reads contain IRIs; callers retain resource IDs. Resolve both through
+        // the shared resource and this database's verified storage binding, preserving foreign IRIs.
+        return schema_1.Thread.buildIriForDatabase(db, left) === schema_1.Thread.buildIriForDatabase(db, right);
+    }
+    async writeTaskApproval(approval, context) {
+        const db = await this.getDb(context);
+        const podBase = this.ensurePodBaseUrlCache(context)?.replace(/\/$/, '');
+        if (!podBase || !approval.target.startsWith(`${podBase}/`))
+            throw new Error('Approval target must belong to the current Pod');
+        const existing = await db.findById(models_1.approvalResource, approval.id);
+        if (existing && (!this.sameApprovalThread(db, existing.thread, approval.thread) || existing.toolCallId !== approval.toolCallId || existing.assignedTo !== approval.assignedTo || existing.session !== approval.session || existing.target !== approval.target || existing.action !== approval.action))
+            throw new Error('Approval checkpoint identity mismatch');
+        if (!existing)
+            await db.insert(models_1.approvalResource).values(approval);
+        return db.resolveRowIri(models_1.approvalResource, approval);
+    }
+    async saveRunApprovalSession(session, context) {
+        const db = await this.getDb(context);
+        const existing = await db.findById(models_1.sessionResource, session.id);
+        if (existing) {
+            if (existing.owner !== session.owner || !this.sameApprovalThread(db, existing.thread, session.thread))
+                throw new Error('Approval session identity mismatch');
+            const iri = db.resolveRowIri(models_1.sessionResource, session);
+            await (0, ConditionalResourceDocument_1.updateConditionalResource)({
+                iri, fetch: this.runDocumentFetch(context), columns: models_1.sessionResource.columns,
+                serialize: values => db.insert(models_1.sessionResource).values({ id: session.id, ...values }).toSPARQL().query,
+                update: quads => {
+                    const status = (0, ConditionalResourceDocument_1.resourceLiteral)(quads, iri, models_1.sessionResource.columns.status.options.predicate);
+                    // A stale start/pause cannot reopen the Session of a terminal Run.
+                    if (status === 'completed' || (status === 'error' && session.status !== 'completed'))
+                        return { result: undefined };
+                    const { id: _id, ...values } = session;
+                    return { result: undefined, values };
+                },
+            });
+        }
+        else {
+            await db.insert(models_1.sessionResource).values(session);
+        }
+        return db.resolveRowIri(models_1.sessionResource, session);
+    }
+    async readTaskApproval(iri, context) {
+        const db = await this.getDb(context);
+        const podBase = this.ensurePodBaseUrlCache(context);
+        if (!podBase || !iri.startsWith(`${podBase.replace(/\/$/, '')}/.data/approvals/`)) {
+            throw new Error('Approval must belong to the current Pod');
+        }
+        const approval = await db.findByIri(models_1.approvalResource, iri);
+        return approval ? { ...approval, thread: this.toResourceRelation(schema_1.Thread, approval.thread, context) ?? approval.thread } : null;
+    }
     async saveTask(task, context) {
         const db = await this.getDb(context);
         task.id = (0, store_2.buildTaskResourceId)(task.id);
         const existing = await db.findById(schema_3.Task, task.id);
+        // Migration boundary: legacy runtime configuration remains in one Pod metadata adapter.
         const metadata = this.withXpodMetadata(this.withTaskAuthBindingMetadata(task.metadata, task.authBinding), {
             runner: task.runner,
             triggerKind: task.triggerKind,
@@ -1659,6 +1773,12 @@ WHERE { ${deletePatterns.join(' ')} }
         });
         const values = {
             title: task.title || null,
+            assignedTo: task.assignedTo || null,
+            source: task.source || null,
+            dueAt: this.timestampToIso(task.dueAt) ?? null,
+            completedAt: this.timestampToIso(task.completedAt) ?? null,
+            notes: task.notes || null,
+            priority: task.priority || null,
             instruction: task.prompt,
             prompt: task.prompt,
             workspace: task.workspace,
@@ -1682,13 +1802,13 @@ WHERE { ${deletePatterns.join(' ')} }
         if (!record) {
             throw new Error(`Task not found: ${taskId}`);
         }
-        return this.taskRecordToData(record);
+        return this.hydrateTaskThread(this.taskRecordToData(record, context), context);
     }
     async listTasks(options, context) {
         const db = await this.getDb(context);
         const records = await db.select().from(schema_3.Task);
         const dueAt = options.dueAt ?? (0, types_1.nowTimestamp)();
-        let tasks = records.map((record) => this.taskRecordToData(record));
+        let tasks = records.map((record) => this.taskRecordToData(record, context));
         if (options.status) {
             tasks = tasks.filter((task) => task.status === options.status);
         }
@@ -1702,7 +1822,17 @@ WHERE { ${deletePatterns.join(' ')} }
             tasks = tasks.filter((task) => typeof task.nextRunAt === 'number' && task.nextRunAt <= dueAt);
         }
         tasks.sort((a, b) => (a.nextRunAt ?? a.createdAt) - (b.nextRunAt ?? b.createdAt) || a.id.localeCompare(b.id));
-        return tasks.slice(0, options.limit ?? tasks.length);
+        return Promise.all(tasks.slice(0, options.limit ?? tasks.length).map(task => this.hydrateTaskThread(task, context)));
+    }
+    /** Thread owns its Task parent relation; do not put the shared link in adapter metadata. */
+    async hydrateTaskThread(task, context) {
+        if (task.thread || !task.authBinding)
+            return task;
+        const db = await this.getDb(context);
+        const parent = this.resolveTaskParentResource(task.id, context);
+        const threads = await db.select().from(schema_1.Thread).where((0, drizzle_solid_1.eq)(schema_1.Thread.parent, parent));
+        const latest = threads.sort((left, right) => (this.isoToTimestamp(right.updatedAt) ?? 0) - (this.isoToTimestamp(left.updatedAt) ?? 0))[0];
+        return { ...task, thread: latest?.id ?? '' };
     }
     async saveTaskAuthCredential(input, context) {
         const db = await this.getDb(context);
@@ -1812,7 +1942,7 @@ WHERE { ${deletePatterns.join(' ')} }
         if (!/^https?:\/\//.test(providerRef)) {
             candidates.add(this.resolvePodResource(context, providerRef));
         }
-        const providerId = (0, models_1.normalizeAIConfigProviderId)(providerRef);
+        const providerId = (0, models_2.normalizeAIConfigProviderId)(providerRef);
         if (providerId) {
             candidates.add(providerId);
             candidates.add(`/settings/providers/${providerId}.ttl`);
@@ -1840,7 +1970,7 @@ WHERE { ${deletePatterns.join(' ')} }
             if (!raw?.trim()) {
                 return undefined;
             }
-            return (0, models_1.normalizeAIConfigModelId)(raw, providerId) || undefined;
+            return (0, models_2.normalizeAIConfigModelId)(raw, providerId) || undefined;
         }
         catch (error) {
             this.logger.debug(`Failed to read configured embedding model: ${error}`);
@@ -1915,8 +2045,8 @@ WHERE { ${deletePatterns.join(' ')} }
             if (leftFailCount !== rightFailCount) {
                 return leftFailCount - rightFailCount;
             }
-            return (0, models_1.normalizeAIConfigResourceId)(left.id ?? '')
-                .localeCompare((0, models_1.normalizeAIConfigResourceId)(right.id ?? ''));
+            return (0, models_2.normalizeAIConfigResourceId)(left.id ?? '')
+                .localeCompare((0, models_2.normalizeAIConfigResourceId)(right.id ?? ''));
         });
     }
     isTruthyValue(value) {
@@ -2067,7 +2197,7 @@ WHERE { ${deletePatterns.join(' ')} }
         const rowIri = row.credentialIri;
         const credentialIri = typeof rowIri === 'string' && rowIri
             ? rowIri
-            : this.resolvePodResource(context, `settings/credentials.ttl#${(0, models_1.normalizeAIConfigResourceId)(String(row.id ?? ''))}`);
+            : this.resolvePodResource(context, `settings/credentials.ttl#${(0, models_2.normalizeAIConfigResourceId)(String(row.id ?? ''))}`);
         try {
             const secret = await this.credentialSecretDecoder(row, {
                 webId: typeof context.webId === 'string' ? context.webId : '',