From 48cf0383b3311f5e6e8f2c2ac68b17d718f50844 Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent 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 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 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 859d5476ef3e37472ebaed4c38efa6ae27af52f2 Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Thu, 2 Jul 2026 09:21:55 -0400 Subject: [PATCH 4/4] eng-1983 initial stab at crossAppContracts --- packages/database/src/crossAppContracts.ts | 71 ++++++++++++++++++++-- 1 file changed, 67 insertions(+), 4 deletions(-) diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts index f64048453..f45339de5 100644 --- a/packages/database/src/crossAppContracts.ts +++ b/packages/database/src/crossAppContracts.ts @@ -15,12 +15,15 @@ type DbRef = { export type Ref = LocalRef | DbRef; // Common attributes for most types -export type CrossAppBase = LocalRef & { +type BaseAttributes = { createdAt: Date; modifiedAt?: Date; author: Ref; }; +// Common attributes for most types +export type CrossAppBase = LocalRef & BaseAttributes; + export type CrossAppSchemaBase = CrossAppBase & { metadata?: Json; }; @@ -39,6 +42,14 @@ export type LocalOrRemoteRef = rid: string; }; +/* + Note on Inline vs Standalone: + The db `upsert_...` functions allow to put some objects inline inside related objects instead of passing a reference. + Those objects will either get upserted or resolved by the upsert functions. + When we provide an inline object, some shared attributes can be specified in the enclosing object. + Hence, the inline version of the object has less required attributes than the standalone version. +*/ + // A node schema export type CrossAppNodeSchema = CrossAppSchemaBase & { label: string; @@ -68,20 +79,70 @@ export type CrossAppEmbedding = { embedding?: Enums<"EmbeddingName">; }; -// A Content object. It can be put inline inside a concept. -// Missing CrossAppBase attributes are inferred from enclosing object. -export type InlineCrossAppContent = Partial & { +// An asset reference +export type CrossAppAsset = { + content: ArrayBuffer; + mimetype: string; + createdAt: Date; + modifiedAt?: Date; + filepath?: string; +}; + +// Document fields +type CrossAppDocumentExtras = { + // MIME type + contentType: string; +}; + +// An inline document, to put inside Content or Concept. +// Currently, we fully infer Documents (setting content_as_document=true) +// since our nodes are pages; so this is not used yet. +export type InlineCrossAppDocument = Partial & + CrossAppDocumentExtras; + +// A standalone document, for `upsert_documents`. Not currently used. +// eslint-disable-next-line @typescript-eslint/no-unused-vars +type StandaloneCrossAppDocument = LocalRef & + BaseAttributes & + CrossAppDocumentExtras; + +// Content fields +type CrossAppContentExtras = { value: string; embedding?: CrossAppEmbedding; scale?: Enums<"Scale">; + partOf?: Ref; + assets?: CrossAppAsset[]; + document?: InlineCrossAppDocument; contentType?: ContentType; }; +// An inline content object, to be put inside a Concept. +export type InlineCrossAppContent = Partial & + CrossAppContentExtras; + +// A standalone content object, for `upsert_content` +// eslint-disable-next-line @typescript-eslint/no-unused-vars +type StandaloneCrossAppContent = LocalRef & + BaseAttributes & + CrossAppContentExtras; + // An inline Content with obligatory typing type InlineCrossAppTypedContent = InlineCrossAppContent & { contentType: ContentType; }; +// A platform account +// either standalone for `upsert_account_in_space`, +// or inline in Content or Concept +export type CrossAppAccount = { + accountLocalId: string; + name?: string; + email?: string; + // agentType: Enums<"AgentType"> = 'person' // inferred + // dgAccount?: string; // uuid +}; + // A node instance export type CrossAppNode = CrossAppBase & { nodeType: Ref; @@ -89,6 +150,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