@segmentstream-cloud/ontology 0.25.0 → 0.26.0

package/dist/runtime/sql-runtime.js

@@ -1,9 +1,11 @@
-import { Effect, Option } from "effect";
+import { Effect, Exit, Option } from "effect";
 import { beginReplicationWrite } from "../replication/transaction.js";
 import { isSqlError } from "effect/unstable/sql/SqlError";
-import { Conflict } from "../errors.js";
+import { ActionRejected, Conflict } from "../errors.js";
 import { toSnakeCase } from "../names.js";
 import { User } from "../user.js";
+import { ACTION_MAX_BATCH_ROWS, BATCH_MAX_BYTES, BATCH_MAX_ROWS, batchInputBytes, executeBatch, planBatch, } from "./batch.js";
+import { logBatchConflict } from "./batch-diagnostics.js";
 import { InvalidQuery, WriteOutsideAction } from "./errors.js";
 import { entityModel, ontologyModel } from "./model.js";
 import { loadRecord, notFound, readHistory, relatedCondition, runQuery, validateQuery, } from "./reads.js";
@@ -23,7 +25,7 @@ function withoutUndefined(value) {
         .map(([key, entry]) => [key, withoutUndefined(entry)]));
 }
 /** A unique violation becomes Conflict, naming the property when the index covers one column. */
-function uniqueConflict(entity, error) {
+function uniqueConflict(entity, error, batch) {
     const cause = (error.reason.cause ?? {});
     const unique = error.reason._tag === "UniqueViolation" || cause.code === "23505";
     if (!unique) {
@@ -31,17 +33,36 @@ function uniqueConflict(entity, error) {
     }
     const columns = typeof cause.detail === "string" ? /^Key \(([^)]*)\)=/.exec(cause.detail)?.[1] : undefined;
     const field = entity.fields.find((candidate) => candidate.column === columns);
+    const fields = typeof columns === "string"
+        ? columns.split(", ").flatMap((column) => {
+            const candidate = entity.fields.find((entry) => entry.column === column);
+            return candidate === undefined ? [] : [candidate.relationship ?? candidate.name];
+        })
+        : [];
+    const details = batch ? { batch: { indices: [], ...(fields.length > 0 ? { fields } : {}) } } : {};
     const label = entity.label.toLowerCase();
-    return Effect.fail(field === undefined
+    const conflict = field === undefined
         ? new Conflict({
             entity: entity.name,
             message: `The ${label} conflicts with an existing one.`,
+            ...details,
         })
         : new Conflict({
             entity: entity.name,
             property: field.name,
             message: `A ${label} with this ${field.name} already exists.`,
-        }));
+            ...details,
+        });
+    if (batch) {
+        // Keep the driver's complete cause available to operators without serializing SQL or values.
+        Object.defineProperty(conflict, "cause", { value: error, enumerable: false });
+        return logBatchConflict(entity, error, {
+            operation: batch.operation,
+            action: batch.scope.action,
+            actionId: batch.scope.actionId,
+        }).pipe(Effect.andThen(Effect.fail(conflict)));
+    }
+    return Effect.fail(conflict);
 }
 /**
  * Platform identity bookkeeping touches only User properties and their history. User is excluded
@@ -91,6 +112,8 @@ export function makeOntologyRuntime(ontology, sql, scope) {
         run: (text, params) => client.unsafe(text, params.values),
     };
     const entityOf = (name) => Effect.sync(() => entityModel(model, name));
+    let attemptedBatchRows = 0;
+    let attributionInitialized = false;
     const write = (entityName, operation) => Effect.gen(function* () {
         const entity = yield* entityOf(entityName);
         if (scope === undefined) {
@@ -108,14 +131,111 @@ export function makeOntologyRuntime(ontology, sql, scope) {
         for (const edit of edits) {
             scope.onEdit?.(edit);
         }
+        if (edits.length > 0 && scope.execution !== undefined) {
+            attributionInitialized = true;
+        }
         return result;
     });
+    const batch = (entityName, operation, input) => Effect.suspend(() => {
+        const startedAt = Date.now();
+        let statements = 0;
+        let distinctReferences = 0;
+        let counts = { created: 0, updated: 0, unchanged: 0 };
+        const run = Effect.gen(function* () {
+            if (scope === undefined) {
+                return yield* Effect.die(new WriteOutsideAction({
+                    entity: entityName,
+                    message: `Writes to ${entityName} run inside an action, which history records.`,
+                }));
+            }
+            const declared = ontology.entities.find((entity) => entity.name === entityName);
+            if (declared?.builtIn === true || declared?.entity.definition.source !== undefined) {
+                return yield* new ActionRejected({
+                    message: "Batch writes require an ordinary stored entity.",
+                    batch: { indices: [] },
+                });
+            }
+            const entity = yield* entityOf(entityName);
+            const length = input.records.length;
+            if (length > 0) {
+                attemptedBatchRows += length;
+            }
+            if (length > BATCH_MAX_ROWS || (length > 0 && attemptedBatchRows > ACTION_MAX_BATCH_ROWS)) {
+                return yield* new ActionRejected({
+                    message: length > BATCH_MAX_ROWS
+                        ? `A batch accepts at most ${BATCH_MAX_ROWS} records.`
+                        : `An action accepts at most ${ACTION_MAX_BATCH_ROWS} attempted batch records.`,
+                    batch: { indices: [] },
+                });
+            }
+            if (batchInputBytes(input) > BATCH_MAX_BYTES) {
+                return yield* new ActionRejected({
+                    message: `A batch accepts at most ${BATCH_MAX_BYTES} UTF-8 JSON bytes.`,
+                    batch: { indices: [] },
+                });
+            }
+            const plan = yield* planBatch(entity, operation, input);
+            distinctReferences = plan.distinctReferences;
+            if (length === 0) {
+                return plan.returning === "summary" ? counts : { ...counts, items: [] };
+            }
+            const enclosingTransaction = yield* Effect.serviceOption(sql.transactionService);
+            if (Option.isNone(enclosingTransaction)) {
+                return yield* Effect.die(new WriteOutsideAction({
+                    entity: entityName,
+                    message: "Batch writes require the enclosing action transaction.",
+                }));
+            }
+            const edits = [];
+            statements += 1; // The SQL client's nested transaction issues one savepoint.
+            const result = yield* sql
+                .withTransaction((scope.replicationInitialized ? Effect.void : beginReplicationWrite(sql)).pipe(Effect.andThen(executeBatch({
+                ...context,
+                scope,
+                edits,
+                attributionInitialized,
+                run: (text, params) => {
+                    statements += 1;
+                    return context.run(text, params);
+                },
+            }, entity, plan)), Effect.onExit((exit) => Effect.sync(() => {
+                if (Exit.isFailure(exit)) {
+                    statements += 1; // A failed nested transaction rolls back to its savepoint.
+                }
+            }))))
+                .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(entity, error, { operation, scope })));
+            counts = { created: result.created, updated: result.updated, unchanged: result.unchanged };
+            for (const edit of edits) {
+                scope.onEdit?.(edit);
+            }
+            if (edits.length > 0 && scope.execution !== undefined) {
+                attributionInitialized = true;
+            }
+            return result;
+        });
+        return run.pipe(Effect.onExit((exit) => Effect.logDebug("ontology.action.batch_completed").pipe(Effect.annotateLogs({
+            operation,
+            entity: entityName,
+            action: scope?.action,
+            actionId: scope?.actionId,
+            inputCount: input.records.length,
+            distinctReferenceCount: distinctReferences,
+            changedCount: counts.created + counts.updated,
+            unchangedCount: counts.unchanged,
+            sqlStatements: statements,
+            batchMs: Date.now() - startedAt,
+            outcome: Exit.isSuccess(exit) ? "success" : "failure",
+        }))));
+    });
     const query = (input) => Effect.gen(function* () {
         const entity = yield* entityOf(input.entity);
         const validated = yield* validateQuery(entity, input.query);
         return yield* orDieOnSql(runQuery(context, entity, validated));
     });
     return {
+        createMany: ((input) => batch(input.entity, "create", input)),
+        updateMany: ((input) => batch(input.entity, "update", input)),
+        upsertMany: ((input) => batch(input.entity, "upsert", input)),
         get: (input) => orDieOnSql(Effect.gen(function* () {
             const entity = yield* entityOf(input.entity);
             const record = yield* loadRecord(context, entity, input.id, input.forUpdate === true ? "update" : undefined);

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 import { Context, Effect } from "effect";
-import type { Conflict, NotFound } from "./errors.js";
+import type { ActionRejected, Conflict, NotFound } from "./errors.js";
 import type { Where } from "./query.js";
 import type { WorkloadExecution } from "./runtime/workload.js";
 /** Who runs an action: an app member or a service principal, both `user` records. */
@@ -76,6 +76,51 @@ export interface UpsertResult<R = StoredRecord> {
     readonly record: R;
     readonly created: boolean;
 }
+/** Whether a batch returns its records or only outcome counts. Defaults to `records`. */
+export type BatchReturning = "records" | "summary";
+export interface BatchOptions {
+    readonly returning?: BatchReturning;
+}
+/** Outcome counts, which together equal the number of inputs in a successful batch. */
+export interface BatchSummaryResult {
+    readonly created: number;
+    readonly updated: number;
+    readonly unchanged: number;
+}
+/** One result per input, in input order, including records whose values did not change. */
+export interface BatchRecordResult<R = StoredRecord> extends BatchSummaryResult {
+    readonly items: ReadonlyArray<{
+        readonly index: number;
+        readonly status: "created" | "updated" | "unchanged";
+        readonly record: R;
+    }>;
+}
+export type BatchResult<R = StoredRecord> = BatchRecordResult<R> | BatchSummaryResult;
+/** Raw batch inputs use wire entity and field names. */
+export interface CreateManyInput extends BatchOptions {
+    readonly entity: string;
+    readonly records: ReadonlyArray<StoredValues>;
+}
+export interface UpdateManyInput extends BatchOptions {
+    readonly entity: string;
+    readonly records: ReadonlyArray<{
+        readonly id: string;
+        readonly values: StoredValues;
+    }>;
+}
+export interface UpsertManyInput extends CreateManyInput {
+    readonly on: readonly [string, ...string[]];
+}
+type BatchWriteError = ActionRejected | Conflict | NotFound;
+interface BatchWrite<Input extends BatchOptions> {
+    (input: Input & {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError>;
+    (input: Input & {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult, BatchWriteError>;
+    (input: Input): Effect.Effect<BatchResult, BatchWriteError>;
+}
 type ReadsService = {
     readonly get: (input: {
         readonly entity: string;
@@ -88,6 +133,9 @@ type ReadsService = {
     }) => Effect.Effect<ReadonlyArray<StoredRecord>>;
 };
 type WritesService = {
+    readonly createMany: BatchWrite<CreateManyInput>;
+    readonly updateMany: BatchWrite<UpdateManyInput>;
+    readonly upsertMany: BatchWrite<UpsertManyInput>;
     readonly create: (input: {
         readonly entity: string;
         readonly values: StoredValues;
@@ -130,7 +178,8 @@ export declare class OntologyReads extends OntologyReads_base {
 declare const OntologyWrites_base: Context.ServiceClass<OntologyWrites, "@segmentstream-cloud/ontology/OntologyWrites", WritesService>;
 /**
  * The writes an action handler runs, inside the action's transaction: `create`, `update`,
- * `upsertBy`, `delete`, `link` and `unlink` of entity handles require it. `prepare` never has it.
+ * `upsertBy`, the batch methods, `delete`, `link` and `unlink` of entity handles require it.
+ * `prepare` never has it.
  */
 export declare class OntologyWrites extends OntologyWrites_base {
 }

package/dist/runtime.js

@@ -8,7 +8,8 @@ export class OntologyReads extends Context.Service()("@segmentstream-cloud/ontol
 }
 /**
  * The writes an action handler runs, inside the action's transaction: `create`, `update`,
- * `upsertBy`, `delete`, `link` and `unlink` of entity handles require it. `prepare` never has it.
+ * `upsertBy`, the batch methods, `delete`, `link` and `unlink` of entity handles require it.
+ * `prepare` never has it.
  */
 export class OntologyWrites extends Context.Service()("@segmentstream-cloud/ontology/OntologyWrites") {
 }

package/dist/service/agent/attachments.d.ts

@@ -13,9 +13,10 @@ export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.js";
 /**
  * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
  * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
- * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * while they are active. The chat and the agent session come from the agent's runtime in
  * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
- * tool arguments; every operation is confined to that member, chat and session.
+ * tool arguments. Storage checks current group participation or chat administration; private files
+ * remain confined to their sender and session.
  */
 export declare const ATTACHMENTS_PATH = "/api/ontology/agent/attachments";
 export interface AttachmentRoutesOptions {

package/dist/service/agent/attachments.js

@@ -12,9 +12,10 @@ export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.js";
 /**
  * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
  * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
- * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * while they are active. The chat and the agent session come from the agent's runtime in
  * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
- * tool arguments; every operation is confined to that member, chat and session.
+ * tool arguments. Storage checks current group participation or chat administration; private files
+ * remain confined to their sender and session.
  */
 export const ATTACHMENTS_PATH = `${AGENT_PATH}/attachments`;
 const NO_STORE = { "cache-control": "no-store" };
@@ -111,6 +112,7 @@ export function attachmentsLayer(options) {
                 request,
                 agents,
                 verify: verifyRuntime,
+                allowUnpairedMember: true,
             });
             return authenticated.ok
                 ? yield* answer(request, authenticated.caller, attachments)

package/dist/service/agent/authentication.d.ts

@@ -6,11 +6,13 @@ import type { AgentStore } from "../runtime-contract.js";
 import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 export declare const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
 export declare const SESSION_HEADER = "x-segmentstream-agent-session";
-/** Both temporary attachments and stored files require the runtime and its paired member. */
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
 export declare function authenticateAgentCaller(input: {
     readonly request: HttpServerRequest.HttpServerRequest;
     readonly agents: AgentStore;
     readonly verify: RuntimeTokenVerifier;
+    /** Temporary attachments authorize active members against the chat registry, without a pairing. */
+    readonly allowUnpairedMember?: boolean;
 }): Effect.Effect<{
     readonly ok: false;
     readonly response: import("effect/unstable/http/HttpServerResponse").HttpServerResponse;

package/dist/service/agent/authentication.js

@@ -1,13 +1,13 @@
 import { Effect, Redacted } from "effect";
 import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
-import { RequestId, forbidden, toServerResponse, unauthorized, unavailable } from "../errors.js";
+import { RequestId, forbidden, notFound, toServerResponse, unauthorized, unavailable, } from "../errors.js";
 import { ACT_AS_HEADER, logRuntimeRejection, } from "../runtime-identity.js";
 export const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
 export const SESSION_HEADER = "x-segmentstream-agent-session";
 const CONVERSATION = /^[a-z][a-z0-9_-]{0,31}:[A-Za-z0-9:_-]{1,200}$/;
 const SESSION = /^[A-Za-z0-9:_.-]{1,200}$/;
-/** Both temporary attachments and stored files require the runtime and its paired member. */
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
 export function authenticateAgentCaller(input) {
     return Effect.gen(function* () {
         const { request, agents, verify } = input;
@@ -31,9 +31,15 @@ export function authenticateAgentCaller(input) {
         const actAs = request.headers[ACT_AS_HEADER]?.trim() ?? "";
         const conversation = request.headers[CONVERSATION_HEADER]?.trim() ?? "";
         const session = request.headers[SESSION_HEADER]?.trim() ?? "";
-        const member = actAs === "" ? undefined : yield* agents.actingMember(actAs);
+        const member = actAs === ""
+            ? undefined
+            : input.allowUnpairedMember
+                ? (yield* agents.member(actAs))?.principal
+                : yield* agents.actingMember(actAs);
         if (member === undefined) {
-            return denied(forbidden(requestId, "The member is inactive or has not paired with the agent."));
+            return denied(input.allowUnpairedMember
+                ? notFound(requestId, "Attachment not found.")
+                : forbidden(requestId, "The member is inactive or has not paired with the agent."));
         }
         if (!CONVERSATION.test(conversation) || (session !== "" && !SESSION.test(session))) {
             return denied(forbidden(requestId, "The agent names the chat and session of every request."));

package/dist/service/errors.js

@@ -1,6 +1,7 @@
 import { Cause, Context, Effect, Option, Predicate, Schema, SchemaIssue } from "effect";
 import { HttpServerResponse } from "effect/unstable/http";
 import { HttpApiError } from "effect/unstable/httpapi";
+import { BatchErrorDetails } from "../errors.js";
 /** The correlation id of the current request, in every error body and the `x-request-id` header. */
 export class RequestId extends Context.Service()("@segmentstream-cloud/ontology/RequestId") {
 }
@@ -64,6 +65,19 @@ function listed(values) {
         ? values.join("")
         : `${values.slice(0, -1).join(", ")} and ${values.at(-1)}`;
 }
+/** Only the declared safe locations cross a transport, even for structurally tagged failures. */
+function batchDetails(error) {
+    const batch = error.batch;
+    if (!Schema.is(BatchErrorDetails)(batch)) {
+        return {};
+    }
+    return {
+        batch: {
+            indices: batch.indices,
+            ...(batch.fields === undefined ? {} : { fields: batch.fields }),
+        },
+    };
+}
 export function toServerResponse(response) {
     return HttpServerResponse.jsonUnsafe(errorBodyForWire(response.body), {
         status: response.status,
@@ -323,6 +337,7 @@ export function expectedFailure(error, requestId) {
                 detail: message,
                 requestId,
                 issues: [{ path: [], message }],
+                ...batchDetails(error),
             },
         };
     }
@@ -421,6 +436,7 @@ export function expectedFailure(error, requestId) {
                 requestId,
                 ...(typeof entity === "string" ? { entity } : {}),
                 ...(typeof id === "string" ? { id } : {}),
+                ...batchDetails(error),
             },
         };
     }
@@ -434,6 +450,7 @@ export function expectedFailure(error, requestId) {
                 requestId,
                 ...(typeof entity === "string" ? { entity } : {}),
                 ...(typeof property === "string" ? { property } : {}),
+                ...batchDetails(error),
             },
         };
     }

package/dist/service/schemas.js

@@ -1,6 +1,7 @@
 import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
+import { BatchErrorDetails } from "../errors.js";
 import { AGGREGATE_FILTER_OPERATORS, ENTITY_AGGREGATE_FILTER_OPERATORS, filterValuesIssue, MAXIMUM_FILTER_VALUES, } from "../aggregate-filters.js";
 import { isValueMatched, OntologyManifestWire } from "../manifest.js";
 import { entityQuerySchemas, queryLinks } from "../query.js";
@@ -510,14 +511,17 @@ export const ErrorSchemas = {
     notFound: errorBody("NotFound", 404, ["not_found"], {
         entity: Schema.optionalKey(Schema.String),
         id: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     conflict: errorBody("Conflict", 409, ["conflict"], {
         entity: Schema.optionalKey(Schema.String),
         property: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     unsupportedMediaType: errorBody("UnsupportedMediaType", 415, ["unsupported_media_type"]),
     unprocessable: errorBody("Unprocessable", 422, ["invalid_input", "action_rejected"], {
         issues: Schema.Array(ValidationIssue),
+        batch: Schema.optionalKey(BatchErrorDetails),
     }),
     rateLimited: errorBody("RateLimited", 429, ["rate_limited"]),
     internal: errorBody("InternalError", 500, ["internal_error"]),

package/dist/storage/attachments.d.ts

@@ -6,11 +6,12 @@ import type { Principal } from "../runtime.js";
 import type { BlobProvider, TransferGrant } from "./provider.js";
 /**
  * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
- * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
- * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
- * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
- * promote it into a record through an action, which adopts the same stored object without copying
- * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ * `_blobs` revision in the ontology's private file storage. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the agent may read it,
+ * discard it, or promote it into a record through an action, which adopts the same stored object
+ * without copying it. Every operation derives chat access from the caller and registry, never from
+ * tool input.
  */
 /** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
 export declare const MAX_ATTACHMENT_BYTES: number;
@@ -25,8 +26,8 @@ export interface AttachmentCaller {
     /** The chat the attachment arrived in, such as `telegram:12345`. */
     readonly conversation: string;
     /**
-     * The agent session the request comes from. The first session that reads an attachment owns it;
-     * other sessions of the same chat, such as one after a reset, never see it.
+     * The agent session the request comes from. Private attachments stay bound to the first session
+     * that reads them. Group attachments are shared across authorized sessions in the same chat.
      */
     readonly sessionId?: string;
 }

package/dist/storage/attachments.js

@@ -9,11 +9,12 @@ import { authorizeBlobOperation } from "./authorization.js";
 import { ATTACHMENTS_TABLE } from "./tables.js";
 /**
  * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
- * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
- * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
- * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
- * promote it into a record through an action, which adopts the same stored object without copying
- * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ * `_blobs` revision in the ontology's private file storage. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the agent may read it,
+ * discard it, or promote it into a record through an action, which adopts the same stored object
+ * without copying it. Every operation derives chat access from the caller and registry, never from
+ * tool input.
  */
 /** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
 export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
@@ -102,9 +103,34 @@ export function attachmentRuntime(ontology, sql, provider) {
     const binding = provider.binding;
     const missing = (id) => new NotFound({ entity: "attachment", id, message: "Attachment not found." });
     const unavailable = (message) => new Conflict({ entity: "attachment", message });
+    /** The registry contains groups only. Neither a tool argument nor a caller's roles name a group. */
+    const accessScope = (caller) => Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [caller.principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return "denied";
+        }
+        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        const separator = caller.conversation.indexOf(":");
+        const [chat] = yield* sql.unsafe(`SELECT id::text FROM "agent_chat"
+         WHERE provider = $1 AND external_id = $2 FOR SHARE`, [caller.conversation.slice(0, separator), caller.conversation.slice(separator + 1)]);
+        if (chat === undefined) {
+            return "private";
+        }
+        const [participant] = yield* sql.unsafe(`SELECT 1 FROM "agent_chat_members"
+         WHERE agent_chat_id = $1::uuid AND user_id = $2::uuid FOR SHARE`, [chat.id, caller.principal.id]);
+        if (participant !== undefined) {
+            return "group";
+        }
+        // App roles are authored by the workspace. Chat management grants its administrator access;
+        // re-read the roles here rather than trusting permissions cached on the principal.
+        const administrator = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        return administrator ? "group" : "denied";
+    });
     /**
-     * The caller's attachment, locked. Another member's, another chat's or another session's is not
-     * found: it does not exist for this caller. The first session that loads it owns it.
+     * The caller's attachment, locked. Group access follows current chat membership. Private access
+     * requires the sender and their session. Source transfers always require the original sender.
      */
     const load = (id, caller, 
     /** `source`: the webhook redelivering the file it stored, before or after a session read it. */
@@ -112,23 +138,37 @@ export function attachmentRuntime(ontology, sql, provider) {
         if (!/^[0-9a-f-]{36}$/i.test(id)) {
             return yield* missing(id);
         }
-        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND a.owner_id = $2::uuid AND a.conversation = $3
-          AND a.branch_id = $4 FOR UPDATE OF a, b`, [id, caller.principal.id, caller.conversation, binding.branchId]);
+        const access = yield* accessScope(caller);
+        if (access === "denied") {
+            return yield* missing(id);
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND (a.owner_id = $2::uuid OR $5) AND a.conversation = $3
+          AND a.branch_id = $4 FOR UPDATE OF a, b`, [
+            id,
+            caller.principal.id,
+            caller.conversation,
+            binding.branchId,
+            access === "group" && scope === "session",
+        ]);
         const row = rows[0];
         if (!row) {
             return yield* missing(id);
         }
-        if (scope === "session" && row.session_id !== null && row.session_id !== caller.sessionId) {
+        if (access === "private" &&
+            scope === "session" &&
+            row.session_id !== null &&
+            row.session_id !== caller.sessionId) {
             return yield* missing(id);
         }
-        if (scope === "session" && row.session_id === null && caller.sessionId !== undefined) {
+        if (access === "private" &&
+            scope === "session" &&
+            row.session_id === null &&
+            caller.sessionId !== undefined) {
             yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET session_id = $1 WHERE id = $2::uuid`, [
                 caller.sessionId,
                 row.id,
             ]);
         }
-        // The member must still be active; a deactivated member's agent reads nothing.
-        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [], caller.principal.execution);
         return row;
     });
     /**
@@ -203,7 +243,7 @@ export function attachmentRuntime(ontology, sql, provider) {
                 input.size,
                 input.sha256,
             ]);
-            return yield* load(id, caller);
+            return yield* load(id, caller, "source");
         }));
         if (reserved.state !== "received" || reserved.expired) {
             return { attachment: view(reserved) };
@@ -232,7 +272,7 @@ export function attachmentRuntime(ontology, sql, provider) {
     });
     /** Completes the transfer, then verifies the stored bytes against the declared size and digest. */
     const complete = (id, caller) => Effect.gen(function* () {
-        const row = yield* sql.withTransaction(load(id, caller));
+        const row = yield* sql.withTransaction(load(id, caller, "source"));
         if (row.state !== "received") {
             return READABLE.has(row.state) && !row.expired
                 ? view(row)
@@ -267,16 +307,25 @@ export function attachmentRuntime(ontology, sql, provider) {
         return yield* sql.withTransaction(Effect.gen(function* () {
             yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'ready'
              WHERE id = $1::uuid AND state = 'received'`, [row.id]);
-            return view(yield* load(row.id, caller));
+            return view(yield* load(row.id, caller, "source"));
         }));
     });
-    /** The caller's attachments in this chat and session that are still readable, newest first. */
+    /** Accessible attachments in this chat that are still readable, newest first. */
     const list = (caller) => sql.withTransaction(Effect.gen(function* () {
-        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [], caller.principal.execution);
-        const rows = yield* sql.unsafe(`${SELECT} WHERE a.owner_id = $1::uuid AND a.conversation = $2 AND a.branch_id = $3
+        const access = yield* accessScope(caller);
+        if (access === "denied") {
+            return [];
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE (a.owner_id = $1::uuid OR $5) AND a.conversation = $2 AND a.branch_id = $3
              AND a.state IN ('ready', 'promoted') AND a.expires_at > now()
-             AND (a.session_id IS NULL OR a.session_id = $4)
-           ORDER BY a.created_at DESC LIMIT ${MAX_LIVE_ATTACHMENTS}`, [caller.principal.id, caller.conversation, binding.branchId, caller.sessionId ?? null]);
+             AND ($5 OR a.session_id IS NULL OR a.session_id = $4)
+           ORDER BY a.created_at DESC LIMIT ${MAX_LIVE_ATTACHMENTS}`, [
+            caller.principal.id,
+            caller.conversation,
+            binding.branchId,
+            caller.sessionId ?? null,
+            access === "group",
+        ]);
         return rows.map(view);
     }));
     /**
@@ -351,6 +400,7 @@ export function attachmentRuntime(ontology, sql, provider) {
         const qualified = `${target.entity}.${target.action}`;
         const prepared = yield* sql.withTransaction(Effect.gen(function* () {
             const row = yield* load(id, caller);
+            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
             if (row.state === "promoted") {
                 return { kind: "done", row };
             }
@@ -365,11 +415,21 @@ export function attachmentRuntime(ontology, sql, provider) {
                         `${row.content_type}, ${row.size} bytes.`,
                 });
             }
-            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
             const [earlier] = yield* sql.unsafe(`SELECT id::text, promotion FROM "${ATTACHMENTS_TABLE}"
              WHERE sha256 = $1 AND branch_id = $2 AND state = 'promoted' AND id <> $3::uuid
                AND promotion->>'action' = $4 AND promotion->>'deduplicated_from' IS NULL
-             ORDER BY created_at LIMIT 1`, [row.sha256, binding.branchId, row.id, qualified]);
+               AND conversation = $5 AND (owner_id = $6::uuid OR $7)
+               AND ($7 OR session_id IS NULL OR session_id = $8)
+             ORDER BY created_at LIMIT 1`, [
+                row.sha256,
+                binding.branchId,
+                row.id,
+                qualified,
+                caller.conversation,
+                caller.principal.id,
+                (yield* accessScope(caller)) === "group",
+                caller.sessionId ?? null,
+            ]);
             if (earlier) {
                 const promotion = {
                     ...earlier.promotion,