feat(modules): GroupFilesService + files::shared_collection handle (§11.6 files C3)

- shared/group_files: GroupFilesService trait (mirror FilesService, no
  group id arg — owner resolved from cx.app_id), GroupFilesError (clone of
  FilesError + CollectionNotShared) with From<FilesError>, Noop.
- services: group_files field + with_group_files setter (default Noop).
- group_files_service: GroupFilesServiceImpl — owning_group via the
  registry resolver (kind=files) → CollectionNotShared; reads open
  (script_gate), writes fail closed (script_gate_require_principal);
  reuses validate_files_collection + the NewFile/FileUpdate validators +
  sanitize_stored_content_type + the per-file size cap; no events.
- sdk/files: GroupFilesHandle + files::shared_collection(name) + the
  create/head/get/update/delete/list group methods (Blob in/out).
- picloud: construct FsGroupFilesRepo (sharing the files root + size cap)
  + GroupFilesServiceImpl, .with_group_files(...).

Unit tests: off-chain → CollectionNotShared; anon read OK / anon write
Forbidden; oversize → TooLarge.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/shared/src/group_files.rs

@@ -0,0 +1,203 @@
+//! `GroupFilesService` — the §11.6 shared group-collection FILES contract.
+//!
+//! The cross-app-sharing counterpart to [`crate::FilesService`], analogous to
+//! [`crate::GroupKvService`] / [`crate::GroupDocsService`]. A script reaches it
+//! via the explicit `files::shared_collection("name")` handle. The owner of the
+//! data is not `cx.app_id`: the impl resolves the **owning group** by walking the
+//! calling app's ancestor chain for the nearest group that declares the
+//! collection shared with `kind='files'`. That ancestry walk is the isolation
+//! boundary — the trait surface takes **no** group id (owner derivation stays in
+//! the impl).
+//!
+//! Trust model (§11.6): **reads are open** to any subtree script (anonymous
+//! public HTTP included); **writes require an authenticated principal** with
+//! editor+ on the owning group. Same shape as group KV/docs.
+
+use async_trait::async_trait;
+use thiserror::Error;
+use uuid::Uuid;
+
+use crate::{FileMeta, FileUpdate, FilesListPage, NewFile, SdkCallCx};
+
+#[async_trait]
+pub trait GroupFilesService: Send + Sync {
+    async fn create(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        new: NewFile,
+    ) -> Result<Uuid, GroupFilesError>;
+
+    async fn head(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        id: &str,
+    ) -> Result<Option<FileMeta>, GroupFilesError>;
+
+    async fn get(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        id: &str,
+    ) -> Result<Option<Vec<u8>>, GroupFilesError>;
+
+    async fn update(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        id: &str,
+        upd: FileUpdate,
+    ) -> Result<(), GroupFilesError>;
+
+    async fn delete(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        id: &str,
+    ) -> Result<bool, GroupFilesError>;
+
+    async fn list(
+        &self,
+        cx: &SdkCallCx,
+        collection: &str,
+        cursor: Option<&str>,
+        limit: u32,
+    ) -> Result<FilesListPage, GroupFilesError>;
+}
+
+/// Stub for test bundles that don't exercise shared files collections.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopGroupFilesService;
+
+#[async_trait]
+impl GroupFilesService for NoopGroupFilesService {
+    async fn create(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _new: NewFile,
+    ) -> Result<Uuid, GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+
+    async fn head(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _id: &str,
+    ) -> Result<Option<FileMeta>, GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+
+    async fn get(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _id: &str,
+    ) -> Result<Option<Vec<u8>>, GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+
+    async fn update(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _id: &str,
+        _upd: FileUpdate,
+    ) -> Result<(), GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+
+    async fn delete(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _id: &str,
+    ) -> Result<bool, GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+
+    async fn list(
+        &self,
+        _cx: &SdkCallCx,
+        _collection: &str,
+        _cursor: Option<&str>,
+        _limit: u32,
+    ) -> Result<FilesListPage, GroupFilesError> {
+        Err(GroupFilesError::Backend(
+            "group files is not wired in".into(),
+        ))
+    }
+}
+
+/// Failure modes surfaced to the Rhai bridge. Mirrors [`crate::FilesError`] plus
+/// the §11.6 `CollectionNotShared` boundary.
+#[derive(Debug, Error)]
+pub enum GroupFilesError {
+    #[error("invalid collection name: {0}")]
+    InvalidCollection(String),
+
+    /// No group on the calling app's ancestor chain declares this collection
+    /// shared with `kind='files'` — the structural "not shared with you"
+    /// boundary (also the outcome for a foreign app).
+    #[error("collection {0:?} is not a shared group files collection for this app")]
+    CollectionNotShared(String),
+
+    #[error("missing required field: {0}")]
+    MissingField(&'static str),
+
+    #[error("file too large: {size} bytes exceeds limit of {limit} bytes")]
+    TooLarge { size: usize, limit: usize },
+
+    #[error("file name too long: {0} bytes exceeds 255")]
+    NameTooLong(usize),
+
+    #[error("content_type too long: {0} bytes exceeds 127")]
+    ContentTypeTooLong(usize),
+
+    #[error("file not found")]
+    NotFound,
+
+    #[error("file content corrupted (checksum mismatch)")]
+    Corrupted,
+
+    /// For reads this is only raised when `cx.principal.is_some()`; for WRITES
+    /// it is also raised when the principal is absent (writes fail closed).
+    #[error("forbidden")]
+    Forbidden,
+
+    #[error("group files backend error: {0}")]
+    Backend(String),
+}
+
+/// Map the shared [`crate::FilesError`] — returned by `validate_collection`
+/// (re-exported as `validate_files_collection`) and the `NewFile`/`FileUpdate`
+/// validators that the group-files service reuses — onto the group error. Lives
+/// here (not in manager-core) so the orphan rule is satisfied.
+impl From<crate::FilesError> for GroupFilesError {
+    fn from(e: crate::FilesError) -> Self {
+        use crate::FilesError as F;
+        match e {
+            F::InvalidCollection(c) => Self::InvalidCollection(c),
+            F::MissingField(f) => Self::MissingField(f),
+            F::TooLarge { size, limit } => Self::TooLarge { size, limit },
+            F::NameTooLong(n) => Self::NameTooLong(n),
+            F::ContentTypeTooLong(n) => Self::ContentTypeTooLong(n),
+            F::NotFound => Self::NotFound,
+            F::Corrupted => Self::Corrupted,
+            F::Forbidden => Self::Forbidden,
+            F::Backend(s) => Self::Backend(s),
+        }
+    }
+}

crates/shared/src/lib.rs

@@ -17,6 +17,7 @@ pub mod execution_log;
 pub mod files;
 pub mod group;
 pub mod group_docs;
+pub mod group_files;
 pub mod group_kv;
 pub mod http;
 pub mod ids;
@@ -68,6 +69,7 @@ pub use files::{
 };
 pub use group::Group;
 pub use group_docs::{GroupDocsError, GroupDocsService, NoopGroupDocsService};
+pub use group_files::{GroupFilesError, GroupFilesService, NoopGroupFilesService};
 pub use group_kv::{GroupKvError, GroupKvService, NoopGroupKvService};
 pub use http::{HttpError, HttpRequest, HttpResponse, HttpService, NoopHttpService};
 pub use ids::{

crates/shared/src/services.rs

@@ -20,12 +20,13 @@
 use std::sync::Arc;
 
 use crate::{
-    DeadLetterService, DocsService, EmailService, FilesService, GroupDocsService, GroupKvService,
-    HttpService, InvokeService, KvService, ModuleSource, NoopDeadLetterService, NoopDocsService,
-    NoopEmailService, NoopEventEmitter, NoopFilesService, NoopGroupDocsService, NoopGroupKvService,
-    NoopHttpService, NoopInvokeService, NoopKvService, NoopModuleSource, NoopPubsubService,
-    NoopQueueService, NoopSecretsService, NoopUsersService, NoopVarsService, PubsubService,
-    QueueService, SecretsService, ServiceEventEmitter, UsersService, VarsService,
+    DeadLetterService, DocsService, EmailService, FilesService, GroupDocsService,
+    GroupFilesService, GroupKvService, HttpService, InvokeService, KvService, ModuleSource,
+    NoopDeadLetterService, NoopDocsService, NoopEmailService, NoopEventEmitter, NoopFilesService,
+    NoopGroupDocsService, NoopGroupFilesService, NoopGroupKvService, NoopHttpService,
+    NoopInvokeService, NoopKvService, NoopModuleSource, NoopPubsubService, NoopQueueService,
+    NoopSecretsService, NoopUsersService, NoopVarsService, PubsubService, QueueService,
+    SecretsService, ServiceEventEmitter, UsersService, VarsService,
 };
 
 /// SDK service bundle. See module docs for the lifecycle and the v1.1.x
@@ -127,6 +128,11 @@ pub struct Services {
     /// `docs::shared_collection(name)`. Wired via [`Services::with_group_docs`];
     /// defaults to `NoopGroupDocsService`.
     pub group_docs: Arc<dyn GroupDocsService>,
+
+    /// Shared cross-app group FILES collections (§11.6). Scripts get
+    /// `files::shared_collection(name)`. Wired via [`Services::with_group_files`];
+    /// defaults to `NoopGroupFilesService`.
+    pub group_files: Arc<dyn GroupFilesService>,
 }
 
 impl Services {
@@ -171,6 +177,7 @@ impl Services {
             // (mostly tests) unchanged — a field addition, not a param.
             group_kv: Arc::new(NoopGroupKvService),
             group_docs: Arc::new(NoopGroupDocsService),
+            group_files: Arc::new(NoopGroupFilesService),
         }
     }
 
@@ -189,6 +196,13 @@ impl Services {
         self
     }
 
+    /// Set the §11.6 shared group-FILES service (picloud binary; tests leave noop).
+    #[must_use]
+    pub fn with_group_files(mut self, group_files: Arc<dyn GroupFilesService>) -> Self {
+        self.group_files = group_files;
+        self
+    }
+
     /// All-noop bundle for tests that build an `Engine` but don't
     /// exercise the stateful services. Returns the same shape as
     /// `Services::new` so callers can't accidentally rely on a stub