From 48cf0383b3311f5e6e8f2c2ac68b17d718f50844 Mon Sep 17 00:00:00 2001
From: Marc-Antoine Parent <maparent@acm.org>
Date: Thu, 2 Jul 2026 09:21:55 -0400
Subject: [PATCH 1/4] eng-1984 Define cross-app schema contracts

---
 packages/database/src/crossAppContracts.ts | 23 ++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts
index c996332c3..0dd4ed036 100644
--- a/packages/database/src/crossAppContracts.ts
+++ b/packages/database/src/crossAppContracts.ts
@@ -21,6 +21,29 @@ export type CrossAppBase = LocalRef & {
   author: Ref;
 };
 
+// A node schema
+export type CrossAppNodeSchema = CrossAppBase & {
+  label: string;
+  template?: string;
+  templateTitle?: string;
+};
+
+// A relation type schema
+export type CrossAppRelationTypeSchema = CrossAppBase & {
+  label: string;
+  complement: string;
+  // should we add colour? format?
+};
+
+// A relation triple schema
+export type CrossAppRelationTripleSchema = CrossAppBase & {
+  label: string;
+  complement: string;
+  relation?: Ref | CrossAppRelationTypeSchema;
+  sourceType: Ref;
+  destinationType: Ref;
+};
+
 // An inline vector semantic embedding
 export type CrossAppEmbedding = {
   value: number[];

From a11622981b65d2823b18c66365b6f41127063f2a Mon Sep 17 00:00:00 2001
From: Marc-Antoine Parent <maparent@acm.org>
Date: Thu, 9 Jul 2026 14:20:37 -0400
Subject: [PATCH 2/4] Add metadata to cross-app schema and nodes

---
 packages/database/src/crossAppContracts.ts | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts
index 0dd4ed036..63084917b 100644
--- a/packages/database/src/crossAppContracts.ts
+++ b/packages/database/src/crossAppContracts.ts
@@ -1,5 +1,5 @@
 import type { ContentType } from "@repo/content-model";
-import { Enums } from "./dbTypes";
+import { Enums, type Json } from "./dbTypes";
 
 export type LocalRef = {
   // This localId is expected to be unique within the current space
@@ -21,22 +21,26 @@ export type CrossAppBase = LocalRef & {
   author: Ref;
 };
 
+export type CrossAppSchemaBase = CrossAppBase & {
+  metadata?: Json;
+};
+
 // A node schema
-export type CrossAppNodeSchema = CrossAppBase & {
+export type CrossAppNodeSchema = CrossAppSchemaBase & {
   label: string;
   template?: string;
   templateTitle?: string;
 };
 
 // A relation type schema
-export type CrossAppRelationTypeSchema = CrossAppBase & {
+export type CrossAppRelationTypeSchema = CrossAppSchemaBase & {
   label: string;
   complement: string;
   // should we add colour? format?
 };
 
 // A relation triple schema
-export type CrossAppRelationTripleSchema = CrossAppBase & {
+export type CrossAppRelationTripleSchema = CrossAppSchemaBase & {
   label: string;
   complement: string;
   relation?: Ref | CrossAppRelationTypeSchema;

From 43ae6ef53f289768f1f89cae851db5ee2814eccc Mon Sep 17 00:00:00 2001
From: Marc-Antoine Parent <maparent@acm.org>
Date: Thu, 2 Jul 2026 09:21:55 -0400
Subject: [PATCH 3/4] eng-1863 Relation cross-app contract

---
 packages/database/src/crossAppContracts.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts
index 63084917b..f64048453 100644
--- a/packages/database/src/crossAppContracts.ts
+++ b/packages/database/src/crossAppContracts.ts
@@ -25,6 +25,20 @@ export type CrossAppSchemaBase = CrossAppBase & {
   metadata?: Json;
 };
 
+type SpaceRef = DbRef | { url: string; sourceApp: Enums<"Platform"> };
+
+export type LocalOrRemoteRef =
+  | LocalRef
+  | {
+      localId: string;
+      // infer space from context if absent.
+      space?: SpaceRef;
+    }
+  | {
+      // A string that contains combined space and localId
+      rid: string;
+    };
+
 // A node schema
 export type CrossAppNodeSchema = CrossAppSchemaBase & {
   label: string;
@@ -76,3 +90,10 @@ export type CrossAppNode = CrossAppBase & {
     full: InlineCrossAppTypedContent;
   };
 };
+
+// A relation instance
+export type CrossAppRelation = CrossAppBase & {
+  relationType: Ref;
+  source: LocalOrRemoteRef;
+  destination: LocalOrRemoteRef;
+};

From f4e0ac2d97d09926bddee2e566ea5bb45b17fb9e Mon Sep 17 00:00:00 2001
From: Marc-Antoine Parent <maparent@acm.org>
Date: Thu, 2 Jul 2026 09:21:55 -0400
Subject: [PATCH 4/4] eng-2002 CrossAppDocument contract (future)

---
 packages/database/src/crossAppContracts.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts
index f64048453..94f97f9d7 100644
--- a/packages/database/src/crossAppContracts.ts
+++ b/packages/database/src/crossAppContracts.ts
@@ -68,12 +68,20 @@ export type CrossAppEmbedding = {
   embedding?: Enums<"EmbeddingName">;
 };
 
+// An inline document, to put inside Content (or Concept)
+export type InlineCrossAppDocument = Partial<CrossAppBase> & {
+  // MIME type
+  contentType: string;
+};
+
 // A Content object. It can be put inline inside a concept.
 // Missing CrossAppBase attributes are inferred from enclosing object.
 export type InlineCrossAppContent = Partial<CrossAppBase> & {
   value: string;
   embedding?: CrossAppEmbedding;
   scale?: Enums<"Scale">;
+  partOf?: Ref;
+  document?: InlineCrossAppDocument;
   contentType?: ContentType;
 };
 
@@ -89,6 +97,8 @@ export type CrossAppNode = CrossAppBase & {
     direct: InlineCrossAppContent;
     full: InlineCrossAppTypedContent;
   };
+  // This is a way to define document globally for all contents
+  document?: InlineCrossAppDocument;
 };
 
 // A relation instance