Skip to content

ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (5/6) - #1634

Open
sid597 wants to merge 2 commits into
mainfrom
eng-1986-add-color-to-the-cross-app-contracts
Open

sid597 wants to merge 2 commits into
mainfrom
eng-1986-add-color-to-the-cross-app-contracts

Conversation

@sid597

@sid597 sid597 commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Reviewer brief

ENG-1986 moves Obsidian sync off its own converters and onto the shared CrossApp converters, without loss of functionality. It ships as six PRs. PRs 1 to 4 and 6 are stacked on #1575 (ENG-1823). PR 5 targets main:

  1. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (1/6) #1620: tests that pin exactly what Obsidian sync sends to upsert_concepts today. No production change.
  2. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (2/6) #1630: node type, relation type and relation triple schemas go through the shared converters.
  3. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (3/6) #1631: nodes and their Content go through the shared converters.
  4. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (4/6) #1632: relation instances go through the shared converters.
  5. This PR. color becomes a CrossApp field on node types and relation types, in packages/database. It doesn't depend on PRs 1 to 4.
  6. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (6/6) #1633: Obsidian sync sends color through the shared converters. It needs PR 5, and its branch carries PR 5's change until that merges.

Why six and not one: each step changes one kind of row, and #1620's tests show whether a stored value changed. PR 5 changes the shared contract, so it goes first in its own PR and needs its own review. Together the steps are well over the 400-line guideline.

  • Result: color is a CrossApp field on node types and relation types (CrossAppNodeSchema.color, CrossAppRelationTypeSchema.color). crossAppNodeSchemaToDbConcept and crossAppRelationTypeSchemaToDbConcept write it to literal_content.color. dbNodeSchemaToCrossApp and dbRelationTypeSchemaToCrossApp read it back and leave it out of metadata.
  • Result: this is the contract half of the color change. On main alone no stored row and no converter output changes, because nothing sets color and no row has a top-level literal_content.color. ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (6/6) #1633's Obsidian sync is the first code that sets color, and the first production caller of crossAppRelationTypeSchemaToDbConcept.
  • Review focus: no reader changes. color moves out of metadata on the database-to-CrossApp side, and nothing in apps/ or packages/ reads metadata on a node type or relation type. The one consumer of those converters, Roam's shared-relation import (discoverSharedRelations.ts, importSharedRelations.ts), reads identity, labels, the complement and the template.
  • Review focus: why a field. On ENG-2091, Marc-Antoine wrote that values CrossApp carries have to be explicit fields, and named format and colour (2026-10-23, 2026-10-25). format is already a field. sourceData is not in this PR.
  • Review focus: the value differs by type. A node type carries a hex color (#7DA13E) and a relation type carries a tldraw color name (blue). The contract types both as a string, and concept_design.md says which is which.
  • Review focus: crossAppRelationTypeSchemaToDbConcept now builds literal_content through filterUndefined, as the node type converter does, so a relation type with no color sends no color key.
  • Risk or follow-up: no backfill. Obsidian rows written before ENG-1986 Refactor Obsidian sync to use the new cross-app schemas (6/6) #1633 keep their color at literal_content.source_data.color. dbNodeSchemaToCrossApp and dbRelationTypeSchemaToCrossApp read only the top-level key, as they do for format, so they return no color for such a row. Nothing reads CrossApp color yet, so a fallback here would be dead code. The first reader owns the fallback or a backfill, as resolveSchemaFormat did for format. The likely first reader is Roam's import (importSharedRelations.ts:73 has the TODO). Obsidian import reads both places itself.
  • Risk or follow-up: Roam is out of this ticket (decision on ENG-1986, 2026-11-16). Roam's nodeSchemaToCrossApp doesn't set color, and Roam node types keep theirs in canvasSettings.color. No ticket covers the Roam converters yet.
  • Risk or follow-up: the Zod validators on ENG-2005 Zod validators for the cross-app types #1619 (ENG-2005) are strict and type-checked against these contracts. Whichever PR merges second adds color there. The validators are also where a non-string color in a row gets rejected: the converters here cast it, as they do format.

Verification

  • packages/database: vitest run passes (152 tests) and tsc --noEmit --skipLibCheck passes.
  • Repository: turbo check-types and turbo run test:unit pass with --force (Roam 716 tests, Obsidian 234 tests).
  • Prettier is clean on the changed files. eslint --max-warnings 0 reports five no-unnecessary-type-assertion warnings in dbToCrossAppConverters.ts at lines 79 to 140. This PR's first change in that file is at line 171.
  • Not run: the packages/database cucumber features, which need a database.

Loom video

Not recorded yet.

Scope check

  • Ran $scope-check against ENG-1986 and the final diff.
  • Scope beyond Done When: None. Done When asks that the cross-app schemas are complete, and color is the field the contract owner agreed to add.

Standards check

  • Ran $dg-pr-adherence-check against the final diff and PR metadata.

Local delegated full review

  • Ran a comprehensive review of the entire final diff in a subagent with a fresh context. Use $dg-delegated-full-review when no other full-review workflow is available.

@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
discourse-graph Ready Ready Preview Nov 16, 2026 10:01am UTC

Request Review

@linear-code

linear-code Bot commented Nov 16, 2026

Copy link
Copy Markdown

ENG-1986

@supabase

supabase Bot commented Nov 16, 2026

Copy link
Copy Markdown

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.


Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

template?: string;
templateTitle?: string;
format?: string;
color?: string;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

color is the one field ENG-1986 adds to the CrossApp schemas. Marc-Antoine asked on ENG-2091 (2026-10-23, 2026-10-25) that every value CrossApp carries be an explicit field, and named format and colour. It is stored like format, at the top level of literal_content. Both apps already call this setting color.

label: string;
complement: string;
// should we add colour? format?
color?: string;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional because rows Obsidian published before #1633 hold the color in literal_content.source_data, and the database-to-CrossApp converter reads only the top-level key. Obsidian sets it on every write from #1633 on.

author_local_id: node.authorId,
is_schema: true,
literal_content: {
literal_content: filterUndefined({

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

filterUndefined keeps color out of literal_content when the relation type has none, as the node type converter above does for its optional keys. The test "leaves color out of literal_content when the relation type has none" in crossAppConverters.test.ts pins this.

number
>;
const { template, template_content, roles, format, ...other } =
const { template, template_content, roles, format, color, ...other } =

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Destructuring color moves it from metadata to the color field. Nothing in apps/ or packages/ reads metadata on a node type or relation type: the only consumer, Roam's importSharedRelations.ts, reads labels, the complement, the template and identity. No producer on main writes a top-level literal_content.color, so no current output changes.

template: template_content as string | undefined,
templateTitle: template as string | undefined,
format: format as string | undefined,
color: color as string | undefined,

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reads only the top-level key. Obsidian rows published before #1633 keep their color in source_data.color, which stays in metadata. Nothing reads CrossApp color yet. The first reader (likely Roam import, TODO at importSharedRelations.ts:73) owns a fallback or backfill, as resolveSchemaFormat did for format.

Note on metadata: It is read from the database, but currently not written. We will phase it out.

When some specific keys of `literal_content` are mapped to a CrossApp field, those key-value pairs are not included again in the `metadata`. Thus `metadata` is a grab-bag for residual data. (Eg color for now.)
When some specific keys of `literal_content` are mapped to a CrossApp field, those key-value pairs are not included again in the `metadata`. Thus `metadata` is a grab-bag for residual data. (Eg `source_data` for now.)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

color is now a CrossApp field, so it is no longer residual. source_data is what metadata still carries for Obsidian rows.

@sid597
sid597 marked this pull request as ready for review November 17, 2026 07:30
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T07:32:52.347396Z 33c14e7 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

This branch was successfully deployed

1 active deployment
Preview — 33c14e79 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant