convert to dashless UUIDs (Geo ID)

Author: nikgraf

packages/hypergraph/src/cli/services/Model.ts

@@ -2,6 +2,7 @@ import { Schema } from 'effect';
 
 import * as Mapping from '../../mapping/Mapping.js';
 import * as Utils from '../../mapping/Utils.js';
+import { GeoIdSchema } from '../../utils/geo-id.js';
 
 export const TypesyncHypergraphSchemaStatus = Schema.NullOr(
   Schema.Literal(
@@ -65,20 +66,20 @@ export class TypesyncHypergraphSchema extends Schema.Class<TypesyncHypergraphSch
 export const TypesyncHypergraphMapping = Schema.Record({
   key: Schema.NonEmptyTrimmedString,
   value: Schema.Struct({
-    typeIds: Schema.Array(Schema.UUID).pipe(Schema.minItems(1)),
+    typeIds: Schema.Array(GeoIdSchema).pipe(Schema.minItems(1)),
     properties: Schema.optional(
       Schema.UndefinedOr(
         Schema.Record({
           key: Schema.NonEmptyTrimmedString,
-          value: Schema.UUID,
+          value: GeoIdSchema,
         }),
       ),
     ),
     relations: Schema.optional(
       Schema.UndefinedOr(
         Schema.Record({
           key: Schema.NonEmptyTrimmedString,
-          value: Schema.UUID,
+          value: GeoIdSchema,
         }),
       ),
     ),

packages/hypergraph/src/cli/services/Utils.ts

@@ -369,13 +369,13 @@ export function buildMappingFile(mapping: Mapping.Mapping | Model.TypesyncHyperg
  *   types: [
  *     {
  *       name: "User",
- *       knowledgeGraphId: "7f9562d4-034d-4385-bf5c-f02cdebba47a",
+ *       knowledgeGraphId: "7f9562d4034d4385bf5cf02cdebba47a",
  *       status: null,
  *       properties: [
  *         {
  *           name: "name",
  *           dataType: "String",
- *           knowledgeGraphId: "a126ca53-0c8e-48d5-b888-82c734c38935",
+ *           knowledgeGraphId: "a126ca530c8e48d5b88882c734c38935",
  *           optional: null,
  *           status: null
  *         }
@@ -391,9 +391,9 @@ export function buildMappingFile(mapping: Mapping.Mapping | Model.TypesyncHyperg
  *
  * export const mapping: Mapping = {
  *   User: {
- *     typeIds: [Id('7f9562d4-034d-4385-bf5c-f02cdebba47a')],
+ *     typeIds: [Id('7f9562d4034d4385bf5cf02cdebba47a')],
  *     properties: {
- *       name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
+ *       name: Id('a126ca530c8e48d5b88882c734c38935'),
  *     }
  *   }
  * }

packages/hypergraph/src/entity/find-many-public.ts

@@ -77,7 +77,7 @@ const buildEntitiesQuery = (
 query ${queryName}(${variableDefinitions}) {
   entities: ${queryName}(
     ${orderByArgs}filter: { and: [{
-      relations: {some: {typeId: {is: "8f151ba4-de20-4e3c-9cb4-99ddf96f48f1"}, toEntityId: {in: $typeIds}}}, 
+      relations: {some: {typeId: {is: "8f151ba4de204e3c9cb499ddf96f48f1"}, toEntityId: {in: $typeIds}}}, 
       ${entitySpaceFilter}
     }, $filter]}
     first: $first

packages/hypergraph/src/mapping/Mapping.ts

@@ -1,6 +1,6 @@
 import { type CreatePropertyParams, Graph, Id as Grc20Id, type Op } from '@graphprotocol/grc-20';
 import { Data, Array as EffectArray, Schema as EffectSchema, Option, pipe } from 'effect';
-
+import { GeoIdSchema } from '../utils/geo-id.js';
 import { namesAreUnique, toCamelCase, toPascalCase } from './Utils.js';
 
 /**
@@ -46,20 +46,20 @@ export type MappingEntry = {
  *
  * const mapping: Mapping = {
  *   Account: {
- *     typeIds: [Id('a5fd07b1-120f-46c6-b46f-387ef98396a6')],
+ *     typeIds: [Id('a5fd07b1120f46c6b46f387ef98396a6')],
  *     properties: {
- *       username: Id('994edcff-6996-4a77-9797-a13e5e3efad8'),
- *       createdAt: Id('64bfba51-a69b-4746-be4b-213214a879fe')
+ *       username: Id('994edcff69964a779797a13e5e3efad8'),
+ *       createdAt: Id('64bfba51a69b4746be4b213214a879fe')
  *     }
  *   },
  *   Event: {
- *     typeIds: [Id('0349187b-526f-435f-b2bb-9e9caf23127a')],
+ *     typeIds: [Id('0349187b526f435fb2bb9e9caf23127a')],
  *     properties: {
- *       name: Id('3808e060-fb4a-4d08-8069-35b8c8a1902b'),
- *       description: Id('1f0d9007-8da2-4b28-ab9f-3bc0709f4837'),
+ *       name: Id('3808e060fb4a4d08806935b8c8a1902b'),
+ *       description: Id('1f0d90078da24b28ab9f3bc0709f4837'),
  *     },
  *     relations: {
- *       speaker: Id('a5fd07b1-120f-46c6-b46f-387ef98396a6')
+ *       speaker: Id('a5fd07b1120f46c6b46f387ef98396a6')
  *     }
  *   }
  * }
@@ -132,7 +132,7 @@ export function getDataType(val: string): SchemaDataType {
 
 const BaseSchemaTypeProperty = EffectSchema.Struct({
   name: EffectSchema.NonEmptyTrimmedString,
-  knowledgeGraphId: EffectSchema.NullOr(EffectSchema.UUID),
+  knowledgeGraphId: EffectSchema.NullOr(GeoIdSchema),
   /**
    * @since 0.4.0
    */
@@ -181,7 +181,7 @@ export function propertyIsRelation(
  */
 export const SchemaType = EffectSchema.Struct({
   name: EffectSchema.NonEmptyTrimmedString,
-  knowledgeGraphId: EffectSchema.NullOr(EffectSchema.UUID),
+  knowledgeGraphId: EffectSchema.NullOr(GeoIdSchema),
   properties: EffectSchema.Array(EffectSchema.Union(SchemaTypePropertyPrimitive, SchemaTypePropertyRelation)).pipe(
     EffectSchema.minItems(1),
     EffectSchema.filter(namesAreUnique, {
@@ -233,12 +233,12 @@ export const Schema = EffectSchema.Struct({
       types: [
         {
           name: 'Account',
-          knowledgeGraphId: 'a5fd07b1-120f-46c6-b46f-387ef98396a6',
+          knowledgeGraphId: 'a5fd07b1120f46c6b46f387ef98396a6',
           properties: [
             {
               name: 'name',
               optional: true,
-              knowledgeGraphId: 'a126ca53-0c8e-48d5-b888-82c734c38935',
+              knowledgeGraphId: 'a126ca530c8e48d5b88882c734c38935',
               dataType: 'String',
             },
           ],
@@ -530,12 +530,12 @@ function processType(type: SchemaType, typeIdMap: TypeIdMapping): ProcessedType
  *   types: [
  *     {
  *       name: "Account",
- *       knowledgeGraphId: "a5fd07b1-120f-46c6-b46f-387ef98396a6",
+ *       knowledgeGraphId: "a5fd07b1120f46c6b46f387ef98396a6",
  *       properties: [
  *         {
  *           name: "username",
  *           dataType: "String",
- *           knowledgeGraphId: "994edcff-6996-4a77-9797-a13e5e3efad8"
+ *           knowledgeGraphId: "994edcff69964a779797a13e5e3efad8"
  *         },
  *         {
  *           name: "createdAt",
@@ -551,7 +551,7 @@ function processType(type: SchemaType, typeIdMap: TypeIdMapping): ProcessedType
  *         {
  *           name: "name",
  *           dataType: "String",
- *           knowledgeGraphId: "3808e060-fb4a-4d08-8069-35b8c8a1902b"
+ *           knowledgeGraphId: "3808e060fb4a4d08806935b8c8a1902b"
  *         },
  *         {
  *           name: "description",
@@ -572,20 +572,20 @@ function processType(type: SchemaType, typeIdMap: TypeIdMapping): ProcessedType
  *
  * expect(mapping).toEqual({
  *   Account: {
- *     typeIds: [Id("a5fd07b1-120f-46c6-b46f-387ef98396a6")], // comes from input schema
+ *     typeIds: [Id("a5fd07b1120f46c6b46f387ef98396a6")], // comes from input schema
  *     properties: {
- *       username: Id("994edcff-6996-4a77-9797-a13e5e3efad8"), // comes from input schema
- *       createdAt: Id("8cd7d9ac-a878-4287-8000-e71e6f853117"), // generated from Graph.createProperty Op
+ *       username: Id("994edcff69964a779797a13e5e3efad8"), // comes from input schema
+ *       createdAt: Id("8cd7d9aca87842878000e71e6f853117"), // generated from Graph.createProperty Op
  *     }
  *   },
  *   Event: {
- *     typeIds: [Id("20b3fe39-8e62-41a0-b9cb-92743fd760da")], // generated from Graph.createType Op
+ *     typeIds: [Id("20b3fe398e6241a0b9cb92743fd760da")], // generated from Graph.createType Op
  *     properties: {
- *       name: Id("3808e060-fb4a-4d08-8069-35b8c8a1902b"), // comes from input schema
- *       description: Id("8fc4e17c-7581-4d6c-a712-943385afc7b5"), // generated from Graph.createProperty Op
+ *       name: Id("3808e060fb4a4d08806935b8c8a1902b"), // comes from input schema
+ *       description: Id("8fc4e17c75814d6ca712943385afc7b5"), // generated from Graph.createProperty Op
  *     },
  *     relations: {
- *       speaker: Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"), // generated from Graph.createProperty Op
+ *       speaker: Id("651ce59f643b4931bf7a5dc0ca0f5a47"), // generated from Graph.createProperty Op
  *     }
  *   }
  * })
@@ -594,31 +594,31 @@ function processType(type: SchemaType, typeIdMap: TypeIdMapping): ProcessedType
  *   {
  *     type: "CREATE_PROPERTY",
  *     property: {
- *       id: Id("8cd7d9ac-a878-4287-8000-e71e6f853117"),
+ *       id: Id("8cd7d9aca87842878000e71e6f853117"),
  *       dataType: "String"
  *     }
  *   },
  *   // Graph.createProperty Op for Event.description property
  *   {
  *     type: "CREATE_PROPERTY",
  *     property: {
- *       id: Id("8fc4e17c-7581-4d6c-a712-943385afc7b5"),
+ *       id: Id("8fc4e17c75814d6ca712943385afc7b5"),
  *       dataType: "String"
  *     }
  *   },
  *   // Graph.createProperty Op for Event.speaker property
  *   {
  *     type: "CREATE_PROPERTY",
  *     property: {
- *       id: Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"),
+ *       id: Id("651ce59f643b4931bf7a5dc0ca0f5a47"),
  *       dataType: "RELATION"
  *     }
  *   },
  *   // Graph.createType Op for Event type
  *   {
  *     type: "CREATE_PROPERTY",
  *     property: {
- *       id: Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"),
+ *       id: Id("651ce59f643b4931bf7a5dc0ca0f5a47"),
  *       dataType: "RELATION"
  *     }
  *   },

packages/hypergraph/src/utils/automergeId.ts

@@ -1,11 +1,13 @@
 import bs58check from 'bs58check';
 import { parse as parseUuid, stringify as stringifyUuid } from 'uuid';
+import { normalizeGeoId, toUuid } from './geo-id.js';
 
 /**
- * Converts a UUID into Base58Check
+ * Converts a Geo ID (UUID without dashes) into Base58Check
  */
-export function idToAutomergeId(uuid: string) {
-  const payload = parseUuid(uuid);
+export function idToAutomergeId(id: string) {
+  // `id` parsing expects canonical formatting; accept dashless IDs too.
+  const payload = parseUuid(toUuid(id));
   return bs58check.encode(payload);
 }
 
@@ -14,5 +16,6 @@ export function idToAutomergeId(uuid: string) {
  */
 export function automergeIdToId(base58CheckUuid: string) {
   const versionedPayload = bs58check.decode(base58CheckUuid);
-  return stringifyUuid(versionedPayload);
+  // Return dashless IDs to align with GRC-20 / API conventions.
+  return normalizeGeoId(stringifyUuid(versionedPayload));
 }

packages/hypergraph/src/utils/generateId.ts

@@ -1,4 +1,5 @@
 import { v4 as uuidv4 } from 'uuid';
+import { normalizeGeoId } from './geo-id.js';
 
 /**
  * Generate a v4 UUID.
@@ -14,5 +15,6 @@ import { v4 as uuidv4 } from 'uuid';
  * @returns v4 UUID
  */
 export function generateId() {
-  return uuidv4();
+  // GRC-20 now uses UUIDs without dashes; normalize for internal consistency.
+  return normalizeGeoId(uuidv4());
 }

packages/hypergraph/src/utils/geo-id.ts

@@ -0,0 +1,51 @@
+import { Schema } from 'effect';
+
+/**
+ * Hypergraph Geo IDs are UUIDs without dashes (32 hex chars).
+ *
+ * Since older code and tooling may still provide UUIDs with dashes, we accept both
+ * and normalize to the dashless format.
+ */
+export type GeoId = string;
+
+const UUID_WITH_DASHES_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_WITHOUT_DASHES_REGEX = /^[0-9a-f]{32}$/i;
+
+export function normalizeGeoId(id: string): GeoId {
+  return id.replaceAll('-', '').toLowerCase();
+}
+
+export function isGeoId(id: string): boolean {
+  if (UUID_WITHOUT_DASHES_REGEX.test(id)) return true;
+  if (UUID_WITH_DASHES_REGEX.test(id)) return true;
+  return UUID_WITHOUT_DASHES_REGEX.test(normalizeGeoId(id));
+}
+
+export function parseGeoId(id: string): GeoId {
+  const normalized = normalizeGeoId(id);
+  if (!UUID_WITHOUT_DASHES_REGEX.test(normalized)) {
+    throw new Error(`Invalid Geo ID (expected UUID with or without dashes): ${id}`);
+  }
+  return normalized;
+}
+
+export function toUuid(id: string): string {
+  const normalized = parseGeoId(id);
+  return [
+    normalized.slice(0, 8),
+    normalized.slice(8, 12),
+    normalized.slice(12, 16),
+    normalized.slice(16, 20),
+    normalized.slice(20),
+  ].join('-');
+}
+
+/**
+ * An Effect Schema that accepts UUIDs with or without dashes and always decodes/encodes
+ * to the dashless (normalized) `GeoId` format.
+ */
+export const GeoIdSchema = Schema.transform(Schema.String, Schema.String, {
+  strict: true,
+  decode: (value: string) => parseGeoId(value),
+  encode: (value: string) => parseGeoId(value),
+}).pipe(Schema.annotations({ identifier: 'GeoId' }));

packages/hypergraph/src/utils/index.ts

@@ -5,6 +5,7 @@ export * from './base58.js';
 export * from './convert-property-value.js';
 export * from './convert-relations.js';
 export * from './generateId.js';
+export * from './geo-id.js';
 export * from './get-relation-type-ids.js';
 export * from './hexBytesAddressUtils.js';
 export * from './isRelation.js';