From 521741ee6ab5556ade4898b7966159b50e5b125a Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Wed, 15 Jul 2026 14:14:18 -0400 Subject: [PATCH 1/2] eng-2036-simplify-the-cross-app-node-contract --- .../convertRoamNodeToFullContent.example.ts | 2 +- .../src/utils/convertRoamNodeToFullContent.ts | 4 +- packages/database/src/crossAppContracts.ts | 27 ++++-------- .../src/crossAppNodeContract.example.ts | 20 ++++----- .../database/src/lib/crossAppConverters.ts | 43 +++---------------- 5 files changed, 26 insertions(+), 70 deletions(-) diff --git a/apps/roam/src/utils/convertRoamNodeToFullContent.example.ts b/apps/roam/src/utils/convertRoamNodeToFullContent.example.ts index fbc0324a9..f425d7d9f 100644 --- a/apps/roam/src/utils/convertRoamNodeToFullContent.example.ts +++ b/apps/roam/src/utils/convertRoamNodeToFullContent.example.ts @@ -229,6 +229,6 @@ export const roamClaimFullMarkdownExample: { full: { contentType: contentTypes.markdown, value: buildFullMarkdown({ title, blocks }), - author: { localId: "someone" }, + authorId: "someone", }, }; diff --git a/apps/roam/src/utils/convertRoamNodeToFullContent.ts b/apps/roam/src/utils/convertRoamNodeToFullContent.ts index 2a31825c8..59a056300 100644 --- a/apps/roam/src/utils/convertRoamNodeToFullContent.ts +++ b/apps/roam/src/utils/convertRoamNodeToFullContent.ts @@ -58,11 +58,11 @@ export const convertRoamNodeToFullContent = ({ const blocks = getFullTreeByParentUid(node.source_local_id).children; const viewType = getPageViewType(title) || "bullet"; const crossAppNode: CrossAppNode = { - author: { localId: node.author_local_id }, + authorId: node.author_local_id, localId: node.source_local_id, createdAt: new Date(node.created || Date.now()), modifiedAt: new Date(node.last_modified || Date.now()), - nodeType: { localId: node.node_type_id }, + nodeType: node.node_type_id, content: { direct: { localId: node.source_local_id, diff --git a/packages/database/src/crossAppContracts.ts b/packages/database/src/crossAppContracts.ts index fcf4bb679..f5c3185f5 100644 --- a/packages/database/src/crossAppContracts.ts +++ b/packages/database/src/crossAppContracts.ts @@ -1,24 +1,15 @@ import type { ContentType } from "@repo/content-model"; import { Enums, type Json } from "./dbTypes"; -export type LocalRef = { - // This localId is expected to be unique within the current space - localId: string; -}; - -type DbRef = { - // Some operations will refer to objects through their database Id - dbId: number; -}; - -// Generalized reference -export type Ref = LocalRef | DbRef; +// An identifier for objects in the platform. Expected to be unique within the platform. +export type LocalId = string; // Common attributes for most types -export type CrossAppBase = LocalRef & { +export type CrossAppBase = { + localId: LocalId; createdAt: Date; modifiedAt?: Date; - author: Ref; + authorId: LocalId; }; export type CrossAppSchemaBase = CrossAppBase & { @@ -48,13 +39,13 @@ export type CrossAppRelationTripleSchema = CrossAppSchemaBase & relation?: never; } | { - relation: Ref; + relation: LocalId; label?: never; complement?: never; } ) & { - sourceType: Ref; - destinationType: Ref; + sourceType: LocalId; + destinationType: LocalId; }; // An inline vector semantic embedding @@ -79,7 +70,7 @@ type InlineCrossAppTypedContent = InlineCrossAppContent & { // A node instance export type CrossAppNode = CrossAppBase & { - nodeType: Ref; + nodeType: LocalId; content: { direct: InlineCrossAppContent; full?: InlineCrossAppTypedContent; diff --git a/packages/database/src/crossAppNodeContract.example.ts b/packages/database/src/crossAppNodeContract.example.ts index b35a7fafe..33bdce9c3 100644 --- a/packages/database/src/crossAppNodeContract.example.ts +++ b/packages/database/src/crossAppNodeContract.example.ts @@ -13,23 +13,21 @@ Multiple studies show that sleep after learning strengthens memory traces. export const roamOriginNodeExample: CrossAppNode = { localId: ROAM_SOURCE_NODE_ID, - nodeType: { - localId: "rCLM0schema", - }, + nodeType: "rCLM0schema", content: { direct: { value: "Sleep improves memory consolidation", - author: { localId: "someone" }, + authorId: "someone", }, full: { contentType: contentTypes.markdown, value: roamFullMarkdown, - author: { localId: "someone" }, + authorId: "someone", }, }, createdAt: new Date("2026-06-12T14:00:00.000Z"), modifiedAt: new Date("2026-06-12T15:00:00.000Z"), - author: { localId: "maparent" }, + authorId: "maparent", }; // const OBSIDIAN_SOURCE_SPACE_ID = "obsidian:9a8b7c6d5e4f3210"; @@ -48,21 +46,19 @@ Participants with more REM sleep showed better next-day recall. export const obsidianOriginNodeExample: CrossAppNode = { localId: OBSIDIAN_SOURCE_NODE_ID, - nodeType: { - localId: OBSIDIAN_SOURCE_NODE_TYPE_ID, - }, + nodeType: OBSIDIAN_SOURCE_NODE_TYPE_ID, content: { direct: { value: "EVD - REM sleep and recall", - author: { localId: "someone" }, + authorId: "someone", }, full: { contentType: contentTypes.markdown, value: obsidianFullMarkdown, - author: { localId: "someone" }, + authorId: "someone", }, }, createdAt: new Date("2026-06-14T10:30:00.000Z"), modifiedAt: new Date("2026-06-14T15:00:00.000Z"), - author: { localId: "maparent" }, + authorId: "maparent", }; diff --git a/packages/database/src/lib/crossAppConverters.ts b/packages/database/src/lib/crossAppConverters.ts index e128bb4a0..00aadad67 100644 --- a/packages/database/src/lib/crossAppConverters.ts +++ b/packages/database/src/lib/crossAppConverters.ts @@ -1,43 +1,12 @@ import { - LocalRef, - Ref, CrossAppEmbedding, InlineCrossAppContent, - CrossAppBase, CrossAppNode, } from "../crossAppContracts"; import { LocalContentDataInput, LocalConceptDataInput } from "../inputTypes"; import { Enums, CompositeTypes } from "../dbTypes"; type InlineEmbeddingInput = CompositeTypes<"inline_embedding_input">; -type InlineAbstractBase = Partial; - -const decodeLocalRef = ( - ref: LocalRef | InlineAbstractBase | undefined, - localVarName: LocalVarName, -): Record | Record => { - if (ref === undefined) return {}; - if ("localId" in ref) { - return { - [localVarName]: ref.localId, - } as Record; - } - return {}; -}; - -const decodeRef = ( - ref: Ref | undefined, - dbVarName: DbVarName, - localVarName: LocalVarName, -): - | Record - | Record - | Record => { - if (ref === undefined) return {}; - if ("dbId" in ref) - return { [dbVarName]: ref.dbId } as Record; - return decodeLocalRef(ref, localVarName); -}; const crossAppEmbeddingToDbEmbedding = ( embedding: CrossAppEmbedding | undefined, @@ -64,14 +33,14 @@ const inlineCrossAppContentToDbContent = ( ): LocalContentDataInput | undefined => { if (content === undefined) return undefined; return filterUndefined({ - ...decodeLocalRef(content, "source_local_id"), + source_local_id: content.localId, text: content.value, scale: content.scale || "document", content_type: content.contentType || "text/plain", variant, created: content.createdAt?.toISOString(), last_modified: content.modifiedAt?.toISOString(), - ...decodeRef(content.author, "author_id", "author_local_id"), + author_local_id: content.authorId, embedding_inline: crossAppEmbeddingToDbEmbedding(content.embedding), }); }; @@ -88,7 +57,7 @@ export const crossAppNodeToDbContent = ( ...content, createdAt: content.createdAt || node.createdAt, modifiedAt: content.modifiedAt || node.modifiedAt, - author: content.author || node.author, + authorId: content.authorId || node.authorId, }, variant, ); @@ -98,10 +67,10 @@ export const crossAppNodeToDbConcept = ( node: CrossAppNode, ): LocalConceptDataInput => { return filterUndefined({ - ...decodeLocalRef(node, "source_local_id"), + source_local_id: node.localId, name: node.content.direct.value, - ...decodeRef(node.author, "author_id", "author_local_id"), - ...decodeRef(node.nodeType, "schema_id", "schema_represented_by_local_id"), + author_local_id: node.authorId, + schema_represented_by_local_id: node.nodeType, contents_inline: filterUndefinedArray([ crossAppNodeToDbContent(node, "direct"), crossAppNodeToDbContent(node, "full"), From 284254abee5d32c25b5e138be4d5f7ad05982416 Mon Sep 17 00:00:00 2001 From: Marc-Antoine Parent Date: Thu, 9 Jul 2026 20:36:33 -0400 Subject: [PATCH 2/2] eng-2017-add-converters-for-schemas --- .../database/src/lib/crossAppConverters.ts | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/packages/database/src/lib/crossAppConverters.ts b/packages/database/src/lib/crossAppConverters.ts index 00aadad67..fbc3d6aa2 100644 --- a/packages/database/src/lib/crossAppConverters.ts +++ b/packages/database/src/lib/crossAppConverters.ts @@ -2,6 +2,9 @@ import { CrossAppEmbedding, InlineCrossAppContent, CrossAppNode, + CrossAppNodeSchema, + CrossAppRelationTypeSchema, + CrossAppRelationTripleSchema, } from "../crossAppContracts"; import { LocalContentDataInput, LocalConceptDataInput } from "../inputTypes"; import { Enums, CompositeTypes } from "../dbTypes"; @@ -79,3 +82,76 @@ export const crossAppNodeToDbConcept = ( last_modified: node.modifiedAt?.toISOString(), }); }; + +export const crossAppNodeSchemaToDbConcept = ( + node: CrossAppNodeSchema, +): LocalConceptDataInput => { + const literalInfo = filterUndefined({ + template: node.templateTitle, + template_content: node.template, + }); + return filterUndefined({ + source_local_id: node.localId, + name: node.label, + author_local_id: node.authorId, + is_schema: true, + literal_content: + Object.keys(literalInfo).length > 0 ? literalInfo : undefined, + created: node.createdAt?.toISOString(), + last_modified: node.modifiedAt?.toISOString(), + }); +}; + +export const crossAppRelationTypeSchemaToDbConcept = ( + node: CrossAppRelationTypeSchema, +): LocalConceptDataInput => { + return filterUndefined({ + source_local_id: node.localId, + name: node.label, + author_local_id: node.authorId, + is_schema: true, + literal_content: { + roles: ["source", "destination"], + label: node.label, + complement: node.complement, + }, + created: node.createdAt?.toISOString(), + last_modified: node.modifiedAt?.toISOString(), + }); +}; + +export const crossAppRelationTripleSchemaToDbConcept = ({ + node, + sourceNodeSchema, + destinationNodeSchema, + relationType, +}: { + node: CrossAppRelationTripleSchema; + sourceNodeSchema: CrossAppNodeSchema; + destinationNodeSchema: CrossAppNodeSchema; + relationType?: CrossAppRelationTypeSchema; +}): LocalConceptDataInput | undefined => { + // relationType must be provided if relation-based triple. + if (!("label" in node) && relationType === undefined) return undefined; + const label = "label" in node ? node.label : relationType!.label; + const complement = + "complement" in node ? node.complement : relationType!.complement; + return filterUndefined({ + source_local_id: node.localId, + name: `${sourceNodeSchema.label} -${label}-> ${destinationNodeSchema.label}`, + author_local_id: node.authorId, + is_schema: true, + literal_content: filterUndefined({ + roles: ["source", "destination"], + label, + complement, + }), + local_reference_content: { + relation_type: node.relation, + source: node.sourceType, + destination: node.destinationType, + }, + created: node.createdAt?.toISOString(), + last_modified: node.modifiedAt?.toISOString(), + }); +};