ENG-1977 Add schema import data layer for Obsidian

[trangdoan982]

https://www.loom.com/share/7771ec3f58e749599a5bf406debdb101

Summary

Adds the import data layer — file parsing, match planning, and apply logic. The UI modal is in the next PR.

• specImport.ts
  • buildSchemaImportMatchPlan — pure, no side effects. Maps every id in the schema file to a local id, id match first and name/label fallback second, and records which items already exist locally.
  • applySchemaImportSelection — creates new relation types and relations as provisional, skips existing matches, preserves a node type's template reference when that template is selected for import or already exists locally.
  • parseDgSchemaFile (in specValidation.ts) does full Zod validation against dgSchemaFileSchema, including a version literal guard.
• schemaMatching.ts — matching primitives shared with the Supabase import path (see below).

Planning is deliberately separated from applying. The Supabase import path interleaves them — mapNodeTypeIdToLocal and mapRelationTypeToLocal both find-or-create inline, so side effects happen during what reads like a lookup. Keeping the plan pure means the preview in #1265 can show exact counts without touching settings.

Shared matching with the Supabase import path

Both import paths have to answer "does this incoming type already exist locally?" — and they answered it differently. The Supabase path compared names and labels case-sensitively; specImport lowercased them. The same vault reached through the two paths would dedupe differently.

schemaMatching.ts now holds the shared primitives:

Helper	Replaces duplicated logic in
findLocalNodeTypeMatch	mapNodeTypeIdToLocal, buildSchemaImportMatchPlan
findLocalRelationTypeMatch	mapRelationTypeToLocal, buildSchemaImportMatchPlan
findExistingTriple	findOrCreateTriple, buildSchemaImportMatchPlan
buildSchemaRid	mapNodeTypeIdToLocal, mapRelationTypeToLocal, applySchemaImportSelection

buildSchemaRid pins the "schema" RID subtype in one place so the two paths cannot drift. Node instance ("note") and relation instance ("relation") RIDs are a different concern and are untouched.

Only the finder half of findOrCreateTriple was extracted, not the create half — it calls plugin.saveSettings() per triple, while applySchemaImportSelection batches a single save at the end. Sharing the whole function would have turned one write into N.

⚠️ Behavior change to the shipped Supabase import

Name and label matching is now case-insensitive on both paths. Importing a Claim node type into a vault that already holds claim now reuses the local type instead of creating a near-duplicate. This is a change to an already-shipped code path and is the one thing in this PR worth reviewing on its own merits.

importedFromRid provenance

applySchemaImportSelection sets importedFromRid on created node types, relation types, and relations, derived from the file's vaultId (added in #1263) as orn:obsidian.schema:<appId>/<localId>.

This is byte-identical to what the Supabase path produces for the same vault and local id, so schema imported from a file and content imported from that same vault over Supabase resolve to the same RID.

Like the Supabase path, this records the immediate source vault. If vault B exports a type it originally imported from vault C, the RID points at B, not C — consistent with existing behavior, but it means RIDs are one hop of provenance, not a full chain.

Bug fixed along the way

The apply loop guarded discourse relations against triples that existed at plan time, but not against triples created earlier in the same run. Two schema node types collapsing onto one local type therefore produced duplicate triples. The guard now runs against live settings.

This was latent before this PR, but case-insensitive matching widens the window: Claim and claim in one schema file now collapse onto a single local type where previously they did not.

Stack

PR 4 of 5 for FEE-840. Stacks on #1263.

1. Shared foundation — ENG-1975 (ENG-1975 Define schema file contract and shared foundation for Obsidian export/import #1180)
2. Schema selection panel UI — ENG-2083 (ENG-2083 Add schema selection panel UI for Obsidian export/import #1262)
3. Schema export command — ENG-1976 (ENG-1976 Add schema export to Obsidian #1263)
4. This PR — schema import data layer (ENG-1977)
5. Schema import UI (ENG-2084)

Test plan

Verified:

• pnpm --filter @discourse-graphs/obsidian check-types passes
• pnpm --filter @discourse-graphs/obsidian lint — 0 errors (75 pre-existing warnings, none in touched files)
• RID round-trips: ridToSpaceUriAndLocalId(buildSchemaRid(...)) recovers the original spaceUri/localId pair
• File-import RID is byte-identical to the Supabase-import RID for the same vault and local id
• findLocalNodeTypeMatch / findLocalRelationTypeMatch — id match beats a differing name; name/label fallback folds case and trims whitespace; genuinely new items return undefined
• findExistingTriple — matches on endpoints while ignoring the triple's own id; reversed endpoints and a different relation type both correctly miss

---

[linear-code]

ENG-1977

[supabase]

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 ↗︎.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
discourse-graph	Skipped		Aug 25, 2026 8:55pm

[devin-ai-integration]

Devin Review found 1 potential issue.

View 1 additional finding in Devin Review.

[graphite-app]

PR size/scope check

This PR is over our review-size guideline.

• Recommended: ~200 lines changed
• Acceptable limit: up to 400 lines when well-scoped/self-contained
• Preferred file count: fewer than 5 files

Please split this into smaller PRs unless there is a clear reason the changes need to land together.

If keeping it as one PR, please add a brief justification covering:

• What single problem this PR solves
• Why the files/changes are coupled

[trangdoan982]

Re: size/scope check

Current: +532 −44 across 4 files — within the file-count preference, over the 400-line limit.

Single problem: make an exported schema file importable into a vault, resolving incoming ids against what already exists there.

Why the changes are coupled: specImport.ts (413 of the added lines, a new file) needs to answer "does this incoming type already exist locally?" — a question the Supabase import path already answered, differently. schemaMatching.ts holds the shared answer, and importNodes.ts / importRelations.ts are moved onto it so the two paths cannot drift apart again. Landing the extraction separately from its first consumer would mean knowingly merging duplicated matching logic and then deleting it.

That said, a clean split does exist and I don't want to overstate the coupling:

1. Extract schemaMatching.ts + move the Supabase path onto it — ~120 lines, 3 files, pure refactor, no new feature. Includes the case-sensitivity behavior change, which is the part of this PR that most deserves isolated review.
2. specImport.ts consuming the shared helpers — ~430 lines, 1 file, additive.

Splitting this way would actually improve review quality: the behavior change to the shipped Supabase import currently sits underneath 400+ lines of new file, which is exactly where it's easiest to miss. The cost is one more PR in an already 5-deep stack and a re-stack of #1265.

Happy to do the split if a reviewer prefers it — say the word.

[graphite-app]

Performance bug: O(N²) array copying in loop causes exponential slowdown

The discourse relations loop repeatedly creates new arrays by spreading plugin.settings.discourseRelations on each iteration:

plugin.settings.discourseRelations = [
  ...plugin.settings.discourseRelations,
  newRelation,
];

For N relations, this creates N arrays with progressively larger sizes (1, 2, 3... N items), resulting in O(N²) memory allocations and copies. With 1000+ relations, this will freeze the application.

Fix: Collect relations in a temporary array first:

const newRelations: DiscourseRelation[] = [];
for (const relation of schemaFile.discourseRelations) {
  // ... existing logic ...
  newRelations.push(newRelation);
}
plugin.settings.discourseRelations = [
  ...plugin.settings.discourseRelations,
  ...newRelations,
];

The same pattern exists at lines 477 (nodeTypes) and 531-533 (relationTypes) but those are less likely to hit performance issues due to smaller counts.

Suggested change

	let discourseRelationsCreated = 0;
	for (const relation of schemaFile.discourseRelations) {
	if (!selectedRelationIds.has(relation.id)) {
	continue;
	}
	const mappedSourceId =
	matchPlan.nodeTypeIdMapping.get(relation.sourceId) ?? relation.sourceId;
	const mappedDestinationId =
	matchPlan.nodeTypeIdMapping.get(relation.destinationId) ??
	relation.destinationId;
	const mappedRelationTypeId =
	matchPlan.relationTypeIdMapping.get(relation.relationshipTypeId) ??
	relation.relationshipTypeId;
	// Checked against live settings, not the plan: two file relations can map to one triple after collapsing.
	const alreadyPresent = findExistingTriple({
	discourseRelations: plugin.settings.discourseRelations,
	sourceId: mappedSourceId,
	destinationId: mappedDestinationId,
	relationshipTypeId: mappedRelationTypeId,
	});
	if (alreadyPresent) {
	continue;
	}
	// The selection UI keeps a triple's endpoints selected, but this layer owns settings integrity, so a dangling triple is refused rather than written.
	if (
	!hasNodeType(mappedSourceId) ||
	!hasNodeType(mappedDestinationId) ||
	!hasRelationType(mappedRelationTypeId)
	) {
	const sourceName =
	schemaNodeTypesById.get(relation.sourceId)?.name ?? relation.sourceId;
	const destinationName =
	schemaNodeTypesById.get(relation.destinationId)?.name ??
	relation.destinationId;
	const relationLabel =
	schemaRelationTypesById.get(relation.relationshipTypeId)?.label ??
	relation.relationshipTypeId;
	onWarning(
	`Relation "${sourceName} ${relationLabel} ${destinationName}" skipped: it references a type that is not in this vault.`,
	);
	continue;
	}
	const newRelation: DiscourseRelation = {
	...relation,
	id: uuidv7(),
	sourceId: mappedSourceId,
	destinationId: mappedDestinationId,
	relationshipTypeId: mappedRelationTypeId,
	importedFromRid: buildSchemaRid({
	spaceUri: sourceSpaceUri,
	localId: relation.id,
	}),
	status: "accepted",
	modified: Date.now(),
	};
	plugin.settings.discourseRelations = [
	...plugin.settings.discourseRelations,
	newRelation,
	];
	discourseRelationsCreated += 1;
	}
	const newDiscourseRelations: DiscourseRelation[] = [];
	for (const relation of schemaFile.discourseRelations) {
	if (!selectedRelationIds.has(relation.id)) {
	continue;
	}
	const mappedSourceId =
	matchPlan.nodeTypeIdMapping.get(relation.sourceId) ?? relation.sourceId;
	const mappedDestinationId =
	matchPlan.nodeTypeIdMapping.get(relation.destinationId) ??
	relation.destinationId;
	const mappedRelationTypeId =
	matchPlan.relationTypeIdMapping.get(relation.relationshipTypeId) ??
	relation.relationshipTypeId;
	// Checked against live settings, not the plan: two file relations can map to one triple after collapsing.
	const alreadyPresent = findExistingTriple({
	discourseRelations: plugin.settings.discourseRelations,
	sourceId: mappedSourceId,
	destinationId: mappedDestinationId,
	relationshipTypeId: mappedRelationTypeId,
	});
	if (alreadyPresent) {
	continue;
	}
	// The selection UI keeps a triple's endpoints selected, but this layer owns settings integrity, so a dangling triple is refused rather than written.
	if (
	!hasNodeType(mappedSourceId) ||
	!hasNodeType(mappedDestinationId) ||
	!hasRelationType(mappedRelationTypeId)
	) {
	const sourceName =
	schemaNodeTypesById.get(relation.sourceId)?.name ?? relation.sourceId;
	const destinationName =
	schemaNodeTypesById.get(relation.destinationId)?.name ??
	relation.destinationId;
	const relationLabel =
	schemaRelationTypesById.get(relation.relationshipTypeId)?.label ??
	relation.relationshipTypeId;
	onWarning(
	`Relation "${sourceName} ${relationLabel} ${destinationName}" skipped: it references a type that is not in this vault.`,
	);
	continue;
	}
	const newRelation: DiscourseRelation = {
	...relation,
	id: uuidv7(),
	sourceId: mappedSourceId,
	destinationId: mappedDestinationId,
	relationshipTypeId: mappedRelationTypeId,
	importedFromRid: buildSchemaRid({
	spaceUri: sourceSpaceUri,
	localId: relation.id,
	}),
	status: "accepted",
	modified: Date.now(),
	};
	newDiscourseRelations.push(newRelation);
	discourseRelationsCreated += 1;
	}
	plugin.settings.discourseRelations = [
	...plugin.settings.discourseRelations,
	...newDiscourseRelations,
	];

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.