feat(platform-objects,crm): sys_attachment polymorphic link + CRM storage capability (M10.3)

Polymorphic File ↔ Record Link:

- packages/platform-objects/src/audit/sys-attachment.object.ts
  * New SysAttachment schema (parent_object, parent_id, file_id, share_type,
    visibility, denormalised file_name/mime_type/size for fast list render)
  * Indexes: (parent_object, parent_id, created_at) for record file lists,
    (file_id) for reverse lookup, (uploaded_by) for user libraries
  * Mirrors Salesforce ContentDocumentLink / ServiceNow sys_attachment pattern

- packages/plugins/plugin-audit/src/audit-plugin.ts
  * Registers SysAttachment alongside other sys_* objects so it lives at the
    same architectural tier as sys_audit_log / sys_activity / sys_comment

- examples/app-crm/objectstack.config.ts
  * Adds 'storage' capability to requires[] so CRM auto-loads
    StorageServicePlugin (otherwise /api/v1/storage/* is 404)

Verified end-to-end on examples/app-crm:
  POST /api/v1/storage/upload/presigned → fileId + uploadUrl
  PUT  <uploadUrl> with content         → 200 ok
  POST /api/v1/storage/upload/complete  → sys_file marked committed
  POST /api/v1/data/sys_attachment      → link row written
  GET  /api/v1/data/sys_attachment?filter=parent_object:lead,parent_id:X
                                        → returns the linked file

Validation envelope (M10.4) catches missing file_id at the create call.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hotlong

examples/app-crm/objectstack.config.ts

@@ -46,7 +46,7 @@ export default defineStack({
   // `ui`   serves the Studio shell and CRM apps under /_studio/.
   // Both are required for a clickable login flow when running `objectstack start`
   // off the compiled artifact.
-  requires: ['ai', 'automation', 'analytics', 'auth', 'ui'],
+  requires: ['ai', 'automation', 'analytics', 'auth', 'ui', 'storage'],
 
   objects: Object.values(objects),
   actions: Object.values(actions),

packages/platform-objects/src/audit/index.ts

@@ -8,3 +8,4 @@ export { SysAuditLog } from './sys-audit-log.object.js';
 export { SysPresence } from './sys-presence.object.js';
 export { SysActivity } from './sys-activity.object.js';
 export { SysComment } from './sys-comment.object.js';
+export { SysAttachment } from './sys-attachment.object.js';

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

@@ -0,0 +1,155 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_attachment — Polymorphic File ↔ Record Link
+ *
+ * Generic join row that attaches a previously-uploaded `sys_file` to
+ * any other record. Mirrors the Salesforce "ContentDocumentLink" /
+ * ServiceNow "sys_attachment" pattern: file storage and "where this
+ * file is attached" are separated, so the same `sys_file` row can be
+ * surfaced on multiple records, an org-wide library, or a thread.
+ *
+ * Conventions:
+ *  - `parent_object` is the short object name (e.g. `account`, `lead`,
+ *    `opportunity`, `case`, `sys_comment`).
+ *  - `parent_id` is the parent record's primary key.
+ *  - `(parent_object, parent_id)` is the natural index for the
+ *    "files on this record" lookup.
+ *  - `share_type` follows the Salesforce convention: V = Viewer,
+ *    C = Collaborator, I = Inferred (inherited from parent record).
+ *
+ * @namespace sys
+ */
+export const SysAttachment = ObjectSchema.create({
+  name: 'sys_attachment',
+  label: 'Attachment',
+  pluralLabel: 'Attachments',
+  icon: 'paperclip',
+  isSystem: true,
+  description: 'Polymorphic link between a sys_file and any other record',
+  titleFormat: '{file_name} → {parent_object}/{parent_id}',
+  compactLayout: ['created_at', 'parent_object', 'file_name', 'mime_type', 'size'],
+
+  fields: {
+    id: Field.text({
+      label: 'Attachment ID',
+      required: true,
+      readonly: true,
+      group: 'System',
+    }),
+
+    // ── Parent (polymorphic) ────────────────────────────────────
+    parent_object: Field.text({
+      label: 'Parent Object',
+      required: true,
+      searchable: true,
+      maxLength: 128,
+      description: 'Short object name of the attached-to record (e.g. account, lead)',
+      group: 'Parent',
+    }),
+
+    parent_id: Field.text({
+      label: 'Parent Record',
+      required: true,
+      searchable: true,
+      maxLength: 64,
+      description: 'Primary key of the attached-to record',
+      group: 'Parent',
+    }),
+
+    // ── File reference ──────────────────────────────────────────
+    file_id: Field.lookup('sys_file', {
+      label: 'File',
+      required: true,
+      description: 'The sys_file storage entry being attached',
+      group: 'File',
+    }),
+
+    file_name: Field.text({
+      label: 'File Name',
+      required: false,
+      searchable: true,
+      maxLength: 255,
+      description: 'Denormalised copy of sys_file.name for fast list rendering',
+      group: 'File',
+    }),
+
+    mime_type: Field.text({
+      label: 'MIME Type',
+      required: false,
+      maxLength: 128,
+      group: 'File',
+    }),
+
+    size: Field.number({
+      label: 'Size (bytes)',
+      required: false,
+      group: 'File',
+    }),
+
+    // ── Sharing ────────────────────────────────────────────────
+    share_type: Field.select(
+      ['viewer', 'collaborator', 'inferred'],
+      {
+        label: 'Share Type',
+        defaultValue: 'viewer',
+        description: 'viewer | collaborator | inferred (inherited from parent record)',
+        group: 'Sharing',
+      },
+    ),
+
+    visibility: Field.select(
+      ['internal', 'all_users', 'shared_users'],
+      {
+        label: 'Visibility',
+        defaultValue: 'internal',
+        group: 'Sharing',
+      },
+    ),
+
+    // ── Authoring ──────────────────────────────────────────────
+    uploaded_by: Field.lookup('sys_user', {
+      label: 'Uploaded By',
+      required: false,
+      group: 'System',
+    }),
+
+    description: Field.textarea({
+      label: 'Description',
+      required: false,
+      maxLength: 1024,
+      group: 'File',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+
+    updated_at: Field.datetime({
+      label: 'Updated At',
+      required: false,
+      group: 'System',
+    }),
+  },
+
+  indexes: [
+    { fields: ['parent_object', 'parent_id', 'created_at'] },
+    { fields: ['file_id'] },
+    { fields: ['uploaded_by'] },
+  ],
+
+  enable: {
+    trackHistory: false,
+    searchable: true,
+    apiEnabled: true,
+    trash: true,
+    mru: false,
+    clone: false,
+  },
+});

packages/plugins/plugin-audit/src/audit-plugin.ts

@@ -2,7 +2,7 @@
 
 import type { Plugin, PluginContext } from '@objectstack/core';
 import type { IDataEngine } from '@objectstack/spec/contracts';
-import { SysAuditLog, SysActivity, SysComment } from '@objectstack/platform-objects/audit';
+import { SysAuditLog, SysActivity, SysComment, SysAttachment } from '@objectstack/platform-objects/audit';
 import { installAuditWriters } from './audit-writers.js';
 
 /**
@@ -30,7 +30,7 @@ export class AuditPlugin implements Plugin {
       scope: 'system',
       defaultDatasource: 'cloud',
       namespace: 'sys',
-      objects: [SysAuditLog, SysActivity, SysComment],
+      objects: [SysAuditLog, SysActivity, SysComment, SysAttachment],
     });
 
     ctx.logger.info('Audit Plugin initialized');