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),
+        }
+    }
+}