feat!: replace createdBy with originalVersionId

proto/common/v1.proto

@@ -11,8 +11,7 @@ message Common_1 {
   repeated VersionId_1 links = 2;
   google.protobuf.Timestamp createdAt = 3 [(required) = true];
   google.protobuf.Timestamp updatedAt = 4 [(required) = true];
-  // 32-byte hash of the discovery key of a core
-  bytes createdBy = 5 [(required) = true];
+  VersionId_1 originalVersionId = 5;
   bool deleted = 6 [(required) = true];
 }
 /* ignored fields and differences from common.json jsonSchema

schema/common/v1.json

@@ -13,6 +13,10 @@
       "description": "core discovery id (hex-encoded 32-byte buffer) and core index number, separated by '/'",
       "type": "string"
     },
+    "originalVersionId": {
+      "description": "Version ID of the original version of this document. For the original version, matches `versionId`.",
+      "type": "string"
+    },
     "schemaName": {
       "description": "Name of Mapeo data type / schema",
       "type": "string"
@@ -22,10 +26,6 @@
       "type": "string",
       "format": "date-time"
     },
-    "createdBy": {
-      "description": "discovery id (hex-encoded 32-byte buffer) of the hypercore where the first version of this document is written",
-      "type": "string"
-    },
     "updatedAt": {
       "description": "RFC3339-formatted datetime of when this version of the element was created",
       "type": "string",
@@ -51,7 +51,7 @@
     "updatedAt",
     "links",
     "versionId",
-    "createdBy",
+    "originalVersionId",
     "deleted"
   ]
 }

src/decode.ts

@@ -4,7 +4,7 @@ import {
   type SchemaName,
   type DataTypeId,
   type ValidSchemaDef,
-  type MapeoDocInternal,
+  type MapeoDocDecode,
 } from './types.js'
 
 import { Decode } from './proto/index.js'
@@ -47,7 +47,7 @@ for (const [schemaName, dataTypeId] of Object.entries(dataTypeIds) as Array<
 export function decode(
   buf: Buffer,
   versionObj: VersionIdObject
-): MapeoDocInternal {
+): MapeoDocDecode {
   const schemaDef = decodeBlockPrefix(buf)
 
   const encodedMsg = buf.subarray(

src/encode.ts

@@ -1,6 +1,6 @@
+import type { SetOptional } from 'type-fest'
 import {
-  type MapeoDocInternal,
-  type OmitUnion,
+  type MapeoDocEncode,
   type SchemaName,
   type ValidSchemaDef,
 } from './types.js'
@@ -28,9 +28,7 @@ import { ExhaustivenessError } from './lib/utils.js'
  * Encode a an object validated against a schema as a binary protobuf prefixed
  * with the encoded data type ID and schema version, to send to an hypercore.
  */
-export function encode(
-  mapeoDoc: OmitUnion<MapeoDocInternal, 'versionId'>
-): Buffer {
+export function encode(mapeoDoc: MapeoDocEncode): Buffer {
   const { schemaName } = mapeoDoc
   const schemaVersion = currentSchemaVersions[schemaName]
   const schemaDef = { schemaName, schemaVersion }

src/index.ts

@@ -11,4 +11,4 @@ export {
 
 export * from './schema/index.js'
 export * from './schemas.js'
-export { type MapeoDocInternal } from './types.js'
+export { type MapeoDocDecode, type MapeoDocEncode } from './types.js'

src/lib/decode-conversions.ts

@@ -18,7 +18,7 @@ import {
   type MapeoCommon,
   type TagValuePrimitive,
   type JsonTagValue,
-  type MapeoDocInternal,
+  type MapeoDocDecode,
 } from '../types.js'
 import { ExhaustivenessError, VersionIdObject, getVersionId } from './utils.js'
 import type { Observation, Track } from '../index.js'
@@ -32,7 +32,7 @@ import { ProjectSettings } from '../schema/projectSettings.js'
 type ConvertFunction<TSchemaName extends SchemaName> = (
   message: Extract<ProtoTypesWithSchemaInfo, { schemaName: TSchemaName }>,
   versionObj: VersionIdObject
-) => FilterBySchemaName<MapeoDocInternal, TSchemaName>
+) => FilterBySchemaName<MapeoDocDecode, TSchemaName>
 
 export const convertProjectSettings: ConvertFunction<'projectSettings'> = (
   message,
@@ -402,13 +402,24 @@ function convertCommon(
     throw new Error('Missing required common properties')
   }
 
+  const versionId = getVersionId(versionObj)
+
+  /** @type {string} */ let originalVersionId
+  if (common.originalVersionId) {
+    originalVersionId = getVersionId(common.originalVersionId)
+  } else if (common.links.length === 0) {
+    originalVersionId = versionId
+  } else {
+    throw new Error('Cannot determine original version ID; data is malformed')
+  }
+
   return {
     docId: common.docId.toString('hex'),
-    versionId: getVersionId(versionObj),
+    versionId,
+    originalVersionId,
     links: common.links.map((link) => getVersionId(link)),
     createdAt: common.createdAt,
     updatedAt: common.updatedAt,
-    createdBy: common.createdBy.toString('hex'),
     deleted: common.deleted,
   }
 }

src/lib/encode-conversions.ts

@@ -1,13 +1,13 @@
+import type { SetOptional } from 'type-fest'
 import { CurrentProtoTypes } from '../proto/types.js'
 import {
   ProtoTypesWithSchemaInfo,
   SchemaName,
   MapeoCommon,
   TagValuePrimitive,
   JsonTagValue,
-  OmitUnion,
   CoreOwnershipSignatures,
-  MapeoDocInternal,
+  MapeoDocEncode,
 } from '../types.js'
 import { TagValue_1, type TagValue_1_PrimitiveValue } from '../proto/tags/v1.js'
 import { Icon } from '../schema/icon.js'
@@ -27,10 +27,7 @@ import {
 /** Function type for converting a protobuf type of any version for a particular
  * schema name, and returning the most recent JSONSchema type */
 type ConvertFunction<TSchemaName extends SchemaName> = (
-  mapeoDoc: Extract<
-    OmitUnion<MapeoDocInternal, 'versionId'>,
-    { schemaName: TSchemaName }
-  >
+  mapeoDoc: Extract<MapeoDocEncode, { schemaName: TSchemaName }>
 ) => CurrentProtoTypes[TSchemaName]
 
 export const convertProjectSettings: ConvertFunction<'projectSettings'> = (
@@ -143,7 +140,8 @@ export const convertDeviceInfo: ConvertFunction<'deviceInfo'> = (mapeoDoc) => {
 }
 
 export const convertCoreOwnership = (
-  mapeoDoc: Omit<CoreOwnership, 'versionId'> & CoreOwnershipSignatures
+  mapeoDoc: Omit<CoreOwnership, 'versionId' | 'originalVersionId'> &
+    CoreOwnershipSignatures
 ): CurrentProtoTypes['coreOwnership'] => {
   return {
     common: convertCommon(mapeoDoc),
@@ -242,13 +240,15 @@ export const convertTrack: ConvertFunction<'track'> = (mapeoDoc) => {
 }
 
 function convertCommon(
-  common: Omit<MapeoCommon, 'versionId'>
+  common: SetOptional<MapeoCommon, 'versionId' | 'originalVersionId'>
 ): ProtoTypesWithSchemaInfo['common'] {
   return {
     docId: Buffer.from(common.docId, 'hex'),
+    originalVersionId: common.originalVersionId
+      ? parseVersionId(common.originalVersionId)
+      : undefined,
     createdAt: common.createdAt,
     updatedAt: common.updatedAt,
-    createdBy: Buffer.from(common.createdBy, 'hex'),
     links: common.links.map((link) => parseVersionId(link)),
     deleted: common.deleted,
   }

src/lib/utils.ts

@@ -62,7 +62,7 @@ export function parseVersionId(versionId: string): VersionIdObject {
 /**
  * @template {import('@mapeo/schema').MapeoDoc & { forks?: string[] }} T
  * @param {T} doc
- * @returns {Omit<T, 'docId' | 'versionId' | 'links' | 'forks' | 'createdAt' | 'updatedAt' | 'createdBy' | 'deleted'>}
+ * @returns {Omit<T, 'docId' | 'versionId' | 'originalVersionId' | 'links' | 'forks' | 'createdAt' | 'updatedAt' | 'deleted'>}
  */
 export function valueOf<TDoc extends MapeoDoc>(
   doc: TDoc & { forks?: string[] }
@@ -71,11 +71,11 @@ export function valueOf<TDoc extends MapeoDoc>(
   const {
     docId,
     versionId,
+    originalVersionId,
     links,
     forks,
     createdAt,
     updatedAt,
-    createdBy,
     deleted,
     ...rest
   } = doc

src/types.ts

@@ -59,10 +59,20 @@ export type MapeoValue = FilterBySchemaName<
 /** The decode and encode functions expect core ownership signatures as buffers,
  * but these are not included in the JSON schema definitions because they are
  * stripped before they are indexed */
-export type MapeoDocInternal =
+export type MapeoDocDecode =
   | Exclude<MapeoDoc, CoreOwnership>
   | (CoreOwnership & CoreOwnershipSignatures)
 
+/**
+ * MapeoDoc for encoding does not need a versionId, and if links is an empty
+ * array, it does not need a originalVersionId either.
+ */
+export type MapeoDocEncode =
+  | (OmitUnion<MapeoDocDecode, 'versionId' | 'originalVersionId' | 'links'> & {
+      links: []
+    })
+  | OmitUnion<MapeoDocDecode, 'versionId'>
+
 /** Union of all valid data type ids */
 export type DataTypeId = Values<typeof dataTypeIds>
 

test/fixtures/bad-docs.js

@@ -13,27 +13,49 @@ export const badDocs = [
     doc: {
       docId: cachedValues.docId,
       versionId: cachedValues.versionId,
+      originalVersionId: cachedValues.versionId,
       schemaName: 'observOtion',
       createdAt: cachedValues.createdAt,
       updatedAt: cachedValues.updatedAt,
-      createdBy: cachedValues.createdBy,
       links: [],
       attachments: [],
       tags: {},
       metadata: {},
       deleted: false,
     },
   },
+  {
+    text: 'missing expected originalVersionId',
+    /** @type Omit<import('../../dist/index.js').Observation, 'originalVersionId'> */
+    doc: {
+      docId: cachedValues.docId,
+      versionId: cachedValues.versionId,
+      schemaName: 'observation',
+      createdAt: cachedValues.createdAt,
+      updatedAt: cachedValues.updatedAt,
+      links: [
+        JSON.stringify({
+          coreDiscoveryKey: Buffer.from('abc123'),
+          index: 123,
+        }),
+      ],
+      refs: [],
+      attachments: [],
+      tags: {},
+      metadata: {},
+      deleted: false,
+    },
+  },
   {
     text: 'role doc with empty roleId',
     /** @type {import('../../dist/index.js').Role} */
     doc: {
       docId: cachedValues.docId,
       versionId: cachedValues.versionId,
+      originalVersionId: cachedValues.versionId,
       schemaName: 'role',
       createdAt: cachedValues.createdAt,
       updatedAt: cachedValues.updatedAt,
-      createdBy: cachedValues.createdBy,
       links: [],
       roleId: '',
       fromIndex: 4,
@@ -45,10 +67,10 @@ export const badDocs = [
     doc: {
       docId: cachedValues.docId,
       versionId: cachedValues.versionId,
+      originalVersionId: cachedValues.versionId,
       schemaName: 'icon',
       createdAt: cachedValues.createdAt,
       updatedAt: cachedValues.updatedAt,
-      createdBy: cachedValues.createdBy,
       links: [],
       deleted: false,
       variants: [
@@ -66,10 +88,10 @@ export const badDocs = [
     doc: {
       docId: cachedValues.docId,
       versionId: cachedValues.versionId,
+      originalVersionId: cachedValues.versionId,
       schemaName: 'preset',
       createdAt: cachedValues.createdAt,
       updatedAt: cachedValues.updatedAt,
-      createdBy: cachedValues.createdBy,
       links: [],
       name: 'myPreset',
       geometry: ['point'],

test/fixtures/cached.js

@@ -5,10 +5,10 @@ const date = new Date().toJSON()
 export const cachedValues = {
   docId: randomBytes(32).toString('hex'),
   versionId: `${randomBytes(32).toString('hex')}/0`,
+  originalVersionId: `${randomBytes(32).toString('hex')}/0`,
   projectId: randomBytes(32).toString('hex'),
   authorId: randomBytes(32).toString('hex'),
   coreId: randomBytes(32).toString('hex'),
-  createdBy: randomBytes(32).toString('hex'),
   createdAt: date,
   updatedAt: date,
   attachments: {