From f1e49e11bbced9f58f1bc193107fc16d5ba5561b Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Thu, 2 Jul 2026 09:21:55 -0400 Subject: [PATCH 1/3] 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 55633fa96..27c78b00f 100644 --- a/packages/database/src/crossAppContracts.ts +++ b/packages/database/src/crossAppContracts.ts @@ -21,6 +21,29 @@ 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 type CrossAppEmbedding = { value: number[]; From a4c65c34ec95798e89410bf86435005f3e48abc2 Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Thu, 2 Jul 2026 09:21:55 -0400 Subject: [PATCH 2/3] 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 27c78b00f..4188b1698 100644 --- a/packages/database/src/crossAppContracts.ts +++ b/packages/database/src/crossAppContracts.ts @@ -21,6 +21,20 @@ type CrossAppBase = LocalRef & { author: Ref; }; +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 = CrossAppBase & { label: string; @@ -72,3 +86,10 @@ export type CrossAppNode = CrossAppBase & { full: InlineCrossAppTypedContent; }; }; + +// A relation instance +export type CrossAppRelation = CrossAppBase & { + relationType: Ref; + source: LocalOrRemoteRef; + destination: LocalOrRemoteRef; +}; From d3a1f859c007c6b9dfb9c46de2697fb6d69207c2 Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Thu, 2 Jul 2026 09:21:55 -0400 Subject: [PATCH 3/3] 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 4188b1698..47539a76f 100644 --- a/packages/database/src/crossAppContracts.ts +++ b/packages/database/src/crossAppContracts.ts @@ -15,12 +15,15 @@ type DbRef = { type Ref = LocalRef | DbRef; // Common attributes for most types -type CrossAppBase = LocalRef & { +type BaseAttributes = { createdAt: Date; modifiedAt?: Date; author: Ref; }; +// Common attributes for most types +export type CrossAppBase = LocalRef & BaseAttributes; + type SpaceRef = DbRef | { url: string; sourceApp: Enums<"Platform"> }; export type LocalOrRemoteRef = @@ -35,6 +38,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 = CrossAppBase & { label: string; @@ -64,20 +75,70 @@ type CrossAppEmbedding = { embedding?: Enums<"EmbeddingName">; }; -// A Content object. It can be put inline inside a concept. -// Missing CrossAppBase attributes are inferred from enclosing object. -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; @@ -85,6 +146,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