feat(attachments): edit-on-parent attach, session lifecycle, trash=false, showcase files (#2970 items 3-6)

- item 3: attach requires EDIT on the parent record (sharing.canEdit),
  not merely read (Salesforce parity); public parents unchanged, private
  owner-scoped parents require own/edit. Read fallback without sharing.
- item 4: sys_upload_session gains an ADR-0057 transient lifecycle (TTL 1d
  past expires_at + 7d retention for terminal statuses) so abandoned
  chunked-upload sessions are reaped. Row reap only; multipart-abort guard
  is a follow-up.
- item 5: sys_attachment enable.trash -> false. The flag is dead in the
  liveness ledger and deletes are hard (reap guard reclaims bytes), so a
  restore would dangle; declare the honest state (ADR-0049).
- item 6: showcase_project opts into enable.files so the attachments panel
  renders for browser dogfooding.
- dogfood: att_readonly (public_read) fixture + matrix cases for
  edit-on-parent (read-but-not-edit → 403, still listable) and
  sys_upload_session reap; access-hook unit tests for the canEdit path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187NT3Qer9oep5dCRb9b8Lt

Author: claude

.changeset/attachment-followups-rest.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/service-storage': minor
+'@objectstack/platform-objects': patch
+---
+
+feat(attachments): edit-on-parent attach, upload-session lifecycle, trash=false (#2970 items 3-5)
+
+Closes the remaining enforce-or-remove / lifecycle items of #2970:
+
+- **Edit-on-parent for attach (item 3, Salesforce parity).** Creating a
+  `sys_attachment` now requires EDIT access to the parent record (via the
+  sharing service's `canEdit`), not merely read — public-model parents are
+  unchanged (canEdit is true for any member), private/owner-scoped parents
+  require the caller to own/edit them. Degrades to read visibility when no
+  sharing service is present.
+- **`sys_upload_session` lifecycle (item 4).** Abandoned / terminal chunked
+  upload sessions are reaped by the platform LifecycleService (`transient`;
+  TTL 1d past `expires_at`; retention 7d for terminal statuses). Row reap
+  only — a reap guard that aborts backend multipart uploads for partial S3
+  sessions is a filed follow-up.
+- **`sys_attachment.enable.trash` → `false` (item 5, ADR-0049).** The flag is
+  `dead` in the liveness ledger (no engine soft-delete reader) and attachment
+  deletes are hard (the reap guard reclaims a file's bytes once its last join
+  row is gone, so a restore would dangle) — declare the honest state rather
+  than claim a restore capability the runtime does not provide.

examples/app-showcase/src/data/objects/project.object.ts

@@ -19,6 +19,12 @@ export const Project = ObjectSchema.create({
   icon: 'folder-kanban',
   description: 'A delivery project for an account.',
 
+  // [#2727 / #2970] Opt in to the generic Attachments panel on the record
+  // detail page — projects carry briefs, SOWs, and deliverable files. This is
+  // the showcase's files-enabled object for browser-dogfooding the attachments
+  // surface (upload / list / download / delete + parent-derived access).
+  enable: { files: true },
+
   fields: {
     name: Field.text({ label: 'Project Name', required: true, searchable: true, maxLength: 200 }),
     // `relatedList*` is the read-side mirror of inline editing: the Account's

packages/dogfood/test/attachments-permission-matrix.dogfood.test.ts

@@ -199,6 +199,31 @@ describe('attachments permission matrix (#2755)', () => {
     expect(allowed.status).toBeLessThan(300);
   });
 
+  // ── (item 3) edit-on-parent: read is not enough to attach ────────────
+  it('(item 3) a member who can READ but not EDIT the parent cannot attach — yet can still list its attachments', async () => {
+    // att_readonly is public_read: every member reads it, only the owner edits.
+    const ro = await ql.insert('att_readonly', { name: 'ro', owner_id: adminId }, { context: { ...SYS } });
+
+    // memberA can READ the record…
+    const canRead = await stack.apiAs(memberATok, 'GET', `/data/att_readonly/${ro.id}`);
+    expect(canRead.status).toBe(200);
+
+    // …but attaching requires EDIT (Salesforce parity) → 403.
+    const file = await uploadFile(stack, memberATok);
+    const denied = await attach(memberATok, 'att_readonly', ro.id, file);
+    expect(denied.status).toBe(403);
+    expect(((await denied.json()) as any).code).toBe('ATTACHMENT_PARENT_ACCESS');
+
+    // The owner (admin) can attach, and memberA — who can read the parent —
+    // then sees that attachment in the list (read-visibility, item 1).
+    const adminFile = await uploadFile(stack, adminTok);
+    const attached = await attach(adminTok, 'att_readonly', ro.id, adminFile);
+    expect(attached.status).toBeLessThan(300);
+    const list = await stack.apiAs(memberATok, 'GET', '/data/sys_attachment');
+    const rows = ((await list.json()) as any).records ?? [];
+    expect(rows.some((r: any) => r.file_id === adminFile)).toBe(true);
+  });
+
   // ── (a) delete gate ──────────────────────────────────────────────────
   it('(a, DOGFOOD FINDING pin) the everyone baseline carries NO delete bit: an ungranted member cannot delete even their OWN attachment (403 PERMISSION_DENIED)', async () => {
     // ADR-0090 D5 / #2753: `member_default` is the anchor-bound baseline and
@@ -450,6 +475,31 @@ describe('attachments permission matrix (#2755)', () => {
       expect(report.errors, JSON.stringify(report.errors)).toEqual([]);
       expect(await ql.findOne('sys_file', { where: { id: data.fileId }, context: SYS })).toBeNull();
     });
+
+    it('(item 4) abandoned sys_upload_session rows are reaped past their expiry window', async () => {
+      // Initiate a chunked upload (creates a sys_upload_session) but never
+      // complete it.
+      const init = await stack.api('/storage/upload/chunked', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${memberATok}` },
+        body: JSON.stringify({ filename: 'big.bin', mimeType: 'application/octet-stream', totalSize: 10_485_760 }),
+      });
+      expect(init.status).toBe(200);
+      const { uploadId } = ((await init.json()) as any).data;
+      const session = await ql.findOne('sys_upload_session', { where: { id: uploadId }, context: SYS });
+      expect(session?.id, 'session row created').toBeTruthy();
+
+      // Backdate expires_at past the 1d TTL grace.
+      await ql.update(
+        'sys_upload_session',
+        { id: uploadId, expires_at: new Date(Date.now() - 2 * DAY_MS) },
+        { context: { ...SYS } },
+      );
+
+      const report = await lifecycle.sweep();
+      expect(report.errors, JSON.stringify(report.errors)).toEqual([]);
+      expect(await ql.findOne('sys_upload_session', { where: { id: uploadId }, context: SYS })).toBeNull();
+    });
   });
 });
 

packages/dogfood/test/fixtures/attachments-fixture.ts

@@ -60,6 +60,20 @@ export const AttNoFiles = ObjectSchema.create({
   },
 });
 
+export const AttReadonly = ObjectSchema.create({
+  name: 'att_readonly',
+  label: 'Attachment Readonly',
+  pluralLabel: 'Attachment Readonlys',
+  // public_read: every member can READ, only the owner can EDIT — the case
+  // that distinguishes edit-on-parent (#2970 item 3) from read visibility.
+  sharingModel: 'public_read',
+  enable: { files: true },
+  fields: {
+    name: Field.text({ label: 'Name', required: true }),
+    owner_id: Field.text({ label: 'Owner' }),
+  },
+});
+
 /**
  * The domain grant a real app ships when it turns the attachments panel on
  * for members: `member_default` (the `everyone` anchor baseline) carries NO
@@ -93,5 +107,5 @@ export const attachmentsFixtureStack = defineStack({
     description:
       'Three-object app exercising the #2755 attachment permission matrix: parent visibility, uploader/editor delete, enable.files gate.',
   },
-  objects: [AttCase, AttSecret, AttNoFiles],
+  objects: [AttCase, AttSecret, AttNoFiles, AttReadonly],
 });

packages/platform-objects/src/audit/sys-attachment.object.ts

@@ -132,7 +132,12 @@ export const SysAttachment = ObjectSchema.create({
     trackHistory: false,
     searchable: true,
     apiEnabled: true,
-    trash: true,
+    // [#2970 item 5 / ADR-0049] `trash` is `dead` in the liveness ledger (no
+    // engine soft-delete reader) and attachment deletes ARE hard (#2755): the
+    // reap guard reclaims a file's bytes once its last join row is gone, so a
+    // "restore" would dangle. Declare `false` — the honest state — rather than
+    // claim a restore capability the runtime does not provide.
+    trash: false,
     mru: false,
     clone: false,
   },

packages/services/service-storage/src/attachment-access-hooks.test.ts

@@ -99,6 +99,31 @@ describe('attachment access — beforeInsert (parent visibility + provenance)',
     ).resolves.toBeUndefined();
     await expect(beforeInsert(insertCtx({ parent_object: 'x', parent_id: 'r' }, {}))).resolves.toBeUndefined();
   });
+
+  // #2970 item 3 — with a sharing service present, attach requires EDIT
+  // (canEdit), not merely read visibility.
+  it('with sharing: rejects attaching when the caller cannot EDIT the parent (even if readable)', async () => {
+    const canEdit = vi.fn(async () => false);
+    const { beforeInsert } = install({ sharing: { canEdit } });
+    const ctx = insertCtx(
+      { parent_object: 'att_readonly', parent_id: 'r1', file_id: 'f1' },
+      { userId: 'u1', visible: ['att_readonly/r1'] }, // readable, but canEdit=false
+    );
+    await expect(beforeInsert(ctx)).rejects.toMatchObject({
+      code: 'ATTACHMENT_PARENT_ACCESS',
+      status: 403,
+    });
+    expect(canEdit).toHaveBeenCalledWith('att_readonly', 'r1', expect.objectContaining({ userId: 'u1' }));
+  });
+
+  it('with sharing: allows attaching when the caller CAN edit the parent', async () => {
+    const { beforeInsert } = install({ sharing: { canEdit: async () => true } });
+    const ctx = insertCtx(
+      { parent_object: 'att_case', parent_id: 'r1', file_id: 'f1' },
+      { userId: 'u1', visible: [] }, // not readable via api, but canEdit=true governs
+    );
+    await expect(beforeInsert(ctx)).resolves.toBeUndefined();
+  });
 });
 
 describe('attachment access — beforeDelete (uploader or parent editor)', () => {

packages/services/service-storage/src/attachment-access-hooks.ts

@@ -118,4 +118,19 @@ export const SystemUploadSession = ObjectSchema.create({
       label: 'Updated At',
     }),
   },
+
+  // ADR-0057 (#2970 item 4): an upload session is ephemeral state, never
+  // business truth — completed, failed, expired, and abandoned in-progress
+  // sessions would otherwise accumulate forever (the sys_file reaper in
+  // #2755 covers files, not sessions). The TTL reaps any row 1d past its own
+  // `expires_at` (abandoned in-progress sessions included); the retention
+  // backstop reaps terminal-status rows by age even if `expires_at` was
+  // never set. NOTE: this reaps the session ROW only — a reap guard that
+  // aborts the backend multipart upload for partial S3 sessions is a filed
+  // follow-up (row reap is the declared scope of this item).
+  lifecycle: {
+    class: 'transient',
+    ttl: { field: 'expires_at', expireAfter: '1d' },
+    retention: { maxAge: '7d', onlyWhen: { status: { $in: ['completed', 'failed', 'expired'] } } },
+  },
 });