refactor(concord): control edition (3308) gets its own event package

Second refactor slice (plan: quartz/plans/2026-07-11-concord-event-classes.md). The kind-3308 control edition now follows the nip88Polls per-kind shape: - New cord04Roles/control/ package: ControlEditionEvent (the Event subclass + build{} template + typed accessors), TagArrayBuilderExt (vsk/eid/ev/ep/vac), TagArrayExt (readers), and tags/ classes VskTag/EidTag/EvTag/EpTag/VacTag with parse/assemble/isTag. - ControlEditionBuilder.rumor now delegates to ControlEditionEvent.build + RumorAssembler; the raw stringly-typed tag construction and the ControlEdition.TAG_* constants are gone. Tags stay in the fixed vsk,eid,ev,ep,vac order so chain rumor ids are unchanged. - ControlEdition.fromRumor reads the typed tags, preserving exact validation (present-but-malformed ep/vac still rejected; absent = genesis/owner). - Register kind 3308 -> ControlEditionEvent in EventFactory so decrypted control rumors parse as the typed class. The edition hash is over content fields (not tags), and all Concord tests — ControlEditionTest, the fold/authority suite, and the join-flow round-trip — pass, so the wire format and chain are preserved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CzJ2Cwo8tg4oZq43oRa3ig
2026-10-05 19:28:25 +00:00 · 2026-07-11 04:27:49 +00:00
parent c2cbd602bc
commit dc2abc0e1c
11 changed files with 439 additions and 50 deletions
@@ -20,12 +20,14 @@
 */
 package com.vitorpamplona.quartz.concord.cord04Roles

+import com.vitorpamplona.quartz.concord.cord04Roles.control.ControlEditionEvent
+import com.vitorpamplona.quartz.concord.cord04Roles.control.eid
+import com.vitorpamplona.quartz.concord.cord04Roles.control.ev
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EpTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.VacTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.vsk
 import com.vitorpamplona.quartz.concord.crypto.EditionHash
-import com.vitorpamplona.quartz.concord.events.ConcordKinds
 import com.vitorpamplona.quartz.nip01Core.core.Event
-import com.vitorpamplona.quartz.nip01Core.core.firstTagValue
-import com.vitorpamplona.quartz.nip01Core.core.firstTagValueAsLong
-import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
 import com.vitorpamplona.quartz.nip01Core.core.toHexKey

 /**
@@ -70,43 +72,30 @@ class ControlEdition(
    val hashHex: String get() = hash.toHexKey()

    companion object {
-        const val TAG_VSK = "vsk"
-        const val TAG_EID = "eid"
-        const val TAG_EV = "ev"
-        const val TAG_EP = "ep"
-        const val TAG_VAC = "vac"
-
        /**
         * Parses a decrypted, verified kind-3308 [rumor] (its [author] is the
         * rumor's pubkey) into a [ControlEdition], or returns null if it is not a
         * well-formed control edition (unknown/absent `vsk`, missing `eid`/`ev`,
         * malformed hex, …) so the caller drops it rather than folding garbage.
+         * Reads the typed tags of [ControlEditionEvent].
         */
        fun fromRumor(
            rumor: Event,
            author: String = rumor.pubKey,
        ): ControlEdition? {
-            if (rumor.kind != ConcordKinds.CONTROL) return null
-            val entityKind = rumor.tags.firstTagValue(TAG_VSK)?.let { ControlEntityKind.of(it) } ?: return null
-            val entityId =
-                rumor.tags
-                    .firstTagValue(TAG_EID)
-                    ?.hexToByteArrayOrNull()
-                    ?.takeIf { it.size == 32 } ?: return null
-            val version = rumor.tags.firstTagValueAsLong(TAG_EV) ?: return null
-            if (version < 0) return null
+            if (rumor.kind != ControlEditionEvent.KIND) return null
+            val entityKind = rumor.tags.vsk() ?: return null
+            val entityId = rumor.tags.eid() ?: return null
+            val version = rumor.tags.ev() ?: return null

-            val prevValue = rumor.tags.firstTagValue(TAG_EP)
-            val prevHash = if (prevValue.isNullOrBlank()) null else prevValue.hexToByteArrayOrNull()?.takeIf { it.size == 32 } ?: return null
+            // A present-but-malformed `ep` is a corrupt edition (reject); an absent (or blank)
+            // `ep` is the genesis edition (no previous hash).
+            val epTag = rumor.tags.firstOrNull { it.size >= 2 && it[0] == EpTag.TAG_NAME && it[1].isNotBlank() }
+            val prevHash = if (epTag == null) null else EpTag.parse(epTag) ?: return null

-            val vacTag = rumor.tags.firstOrNull { it.size >= 4 && it[0] == TAG_VAC }
-            val vac =
-                vacTag?.let {
-                    val gid = it[1].hexToByteArrayOrNull()?.takeIf { b -> b.size == 32 } ?: return null
-                    val gver = it[2].toLongOrNull() ?: return null
-                    val ghash = it[3].hexToByteArrayOrNull()?.takeIf { b -> b.size == 32 } ?: return null
-                    AuthorityCitation(gid, gver, ghash)
-                }
+            // Likewise a present-but-malformed `vac` is rejected; absent means owner-authored.
+            val vacTag = rumor.tags.firstOrNull { it.size >= 4 && it[0] == VacTag.TAG_NAME }
+            val vac = if (vacTag == null) null else VacTag.parse(vacTag) ?: return null

            return ControlEdition(
                entityKind = entityKind,
@@ -20,17 +20,17 @@
 */
 package com.vitorpamplona.quartz.concord.cord04Roles

-import com.vitorpamplona.quartz.concord.events.ConcordKinds
+import com.vitorpamplona.quartz.concord.cord04Roles.control.ControlEditionEvent
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
-import com.vitorpamplona.quartz.nip01Core.core.toHexKey
 import com.vitorpamplona.quartz.nip59Giftwrap.rumors.RumorAssembler

 /**
 * Builds unsigned kind-3308 Control Plane edition rumors (the inverse of
 * [ControlEdition.fromRumor]). Seal these with a plaintext (20014) seal and wrap
 * them on the community's Control Plane so the author's signature survives
- * re-encryption across epochs.
+ * re-encryption across epochs. Reuses [ControlEditionEvent.build] for the wire
+ * shape (its typed `vsk`/`eid`/`ev`/`ep`/`vac` tags); this only stamps the author.
 */
 object ControlEditionBuilder {
    /**
@@ -47,22 +47,9 @@ object ControlEditionBuilder {
        content: String,
        createdAt: Long,
        authorityCitation: AuthorityCitation? = null,
-    ): Event {
-        val tags = ArrayList<Array<String>>(5)
-        tags.add(arrayOf(ControlEdition.TAG_VSK, entityKind.wire))
-        tags.add(arrayOf(ControlEdition.TAG_EID, entityId.toHexKey()))
-        tags.add(arrayOf(ControlEdition.TAG_EV, version.toString()))
-        if (prevHash != null) tags.add(arrayOf(ControlEdition.TAG_EP, prevHash.toHexKey()))
-        if (authorityCitation != null) {
-            tags.add(
-                arrayOf(
-                    ControlEdition.TAG_VAC,
-                    authorityCitation.grantId.toHexKey(),
-                    authorityCitation.grantVersion.toString(),
-                    authorityCitation.grantHash.toHexKey(),
-                ),
-            )
-        }
-        return RumorAssembler.assembleRumor(authorPubKey, createdAt, ConcordKinds.CONTROL, tags.toTypedArray(), content)
-    }
+    ): Event =
+        RumorAssembler.assembleRumor(
+            authorPubKey,
+            ControlEditionEvent.build(entityKind, entityId, version, content, prevHash, authorityCitation, createdAt),
+        )
 }
@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control
+
+import com.vitorpamplona.quartz.concord.cord04Roles.AuthorityCitation
+import com.vitorpamplona.quartz.concord.cord04Roles.ControlEntityKind
+import com.vitorpamplona.quartz.concord.events.ConcordKinds
+import com.vitorpamplona.quartz.nip01Core.core.Event
+import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
+import com.vitorpamplona.quartz.utils.TimeUtils
+
+/**
+ * A kind-3308 Control Plane edition (CORD-02/04) — versioned, chainable community
+ * state (metadata, roles, channels, grants, banlist, invites, …). Authored as an
+ * unsigned rumor, plaintext-sealed and wrapped on the community's Control Plane so
+ * the author signature survives re-encryption across epochs.
+ *
+ * The wire shape is the entity content plus the `vsk`/`eid`/`ev`/`ep`/`vac`
+ * binding tags (see this package's `tags/`). The folded domain view — with the
+ * derived [com.vitorpamplona.quartz.concord.crypto.EditionHash] chain — is
+ * [com.vitorpamplona.quartz.concord.cord04Roles.ControlEdition], which reads these
+ * accessors.
+ */
+class ControlEditionEvent(
+    id: HexKey,
+    pubKey: HexKey,
+    createdAt: Long,
+    tags: Array<Array<String>>,
+    content: String,
+    sig: HexKey,
+) : Event(id, pubKey, createdAt, KIND, tags, content, sig) {
+    fun entityKind() = tags.vsk()
+
+    fun entityId() = tags.eid()
+
+    fun version() = tags.ev()
+
+    fun prevHash() = tags.ep()
+
+    fun authorityCitation() = tags.vac()
+
+    companion object {
+        const val KIND = ConcordKinds.CONTROL
+
+        /**
+         * Builds the edition template for [entityKind]/[entityId] at [version].
+         * Tags are emitted in the fixed `vsk, eid, ev, ep?, vac?` order the chain's
+         * rumor ids depend on. Assemble it into a rumor with the author pubkey via
+         * `RumorAssembler`.
+         */
+        fun build(
+            entityKind: ControlEntityKind,
+            entityId: ByteArray,
+            version: Long,
+            content: String,
+            prevHash: ByteArray? = null,
+            authorityCitation: AuthorityCitation? = null,
+            createdAt: Long = TimeUtils.now(),
+            initializer: TagArrayBuilder<ControlEditionEvent>.() -> Unit = {},
+        ) = eventTemplate(KIND, content, createdAt) {
+            vsk(entityKind)
+            eid(entityId)
+            ev(version)
+            prevHash?.let { ep(it) }
+            authorityCitation?.let { vac(it) }
+            initializer()
+        }
+    }
+}
@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control
+
+import com.vitorpamplona.quartz.concord.cord04Roles.AuthorityCitation
+import com.vitorpamplona.quartz.concord.cord04Roles.ControlEntityKind
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EidTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EpTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EvTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.VacTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.VskTag
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+
+fun TagArrayBuilder<ControlEditionEvent>.vsk(kind: ControlEntityKind) = addUnique(VskTag.assemble(kind))
+
+fun TagArrayBuilder<ControlEditionEvent>.eid(entityId: ByteArray) = addUnique(EidTag.assemble(entityId))
+
+fun TagArrayBuilder<ControlEditionEvent>.ev(version: Long) = addUnique(EvTag.assemble(version))
+
+fun TagArrayBuilder<ControlEditionEvent>.ep(prevHash: ByteArray) = addUnique(EpTag.assemble(prevHash))
+
+fun TagArrayBuilder<ControlEditionEvent>.vac(citation: AuthorityCitation) = addUnique(VacTag.assemble(citation))
@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control
+
+import com.vitorpamplona.quartz.concord.cord04Roles.AuthorityCitation
+import com.vitorpamplona.quartz.concord.cord04Roles.ControlEntityKind
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EidTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EpTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.EvTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.VacTag
+import com.vitorpamplona.quartz.concord.cord04Roles.control.tags.VskTag
+import com.vitorpamplona.quartz.nip01Core.core.TagArray
+
+/** The Control Plane entity kind (`vsk`) this edition updates, or null if absent/unknown. */
+fun TagArray.vsk(): ControlEntityKind? = firstNotNullOfOrNull(VskTag::parse)
+
+/** The 32-byte entity id (`eid`), or null if absent/malformed. */
+fun TagArray.eid(): ByteArray? = firstNotNullOfOrNull(EidTag::parse)
+
+/** The edition version (`ev`), or null if absent/malformed/negative. */
+fun TagArray.ev(): Long? = firstNotNullOfOrNull(EvTag::parse)
+
+/** The previous-edition hash (`ep`), or null if absent (genesis) — see also the presence check in `fromRumor`. */
+fun TagArray.ep(): ByteArray? = firstNotNullOfOrNull(EpTag::parse)
+
+/** The authority citation (`vac`), or null if absent (owner-authored). */
+fun TagArray.vac(): AuthorityCitation? = firstNotNullOfOrNull(VacTag::parse)
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.utils.ensure
+
+/**
+ * The `["eid", <hex>]` entity-id tag: the 32-byte id of the Control Plane entity a
+ * kind-3308 edition updates (its version chain is keyed by this id).
+ */
+class EidTag {
+    companion object {
+        const val TAG_NAME = "eid"
+
+        fun isTag(tag: Array<String>) = tag.has(1) && tag[0] == TAG_NAME && tag[1].isNotEmpty()
+
+        fun parse(tag: Array<String>): ByteArray? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            return tag[1].hexToByteArrayOrNull()?.takeIf { it.size == 32 }
+        }
+
+        fun assemble(entityId: ByteArray) = arrayOf(TAG_NAME, entityId.toHexKey())
+    }
+}
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.utils.ensure
+
+/**
+ * The `["ep", <hex>]` edition-prev tag: the 32-byte [hash][com.vitorpamplona.quartz.concord.crypto.EditionHash]
+ * of the previous edition in this entity's chain. Absent on the genesis edition.
+ */
+class EpTag {
+    companion object {
+        const val TAG_NAME = "ep"
+
+        fun isTag(tag: Array<String>) = tag.has(1) && tag[0] == TAG_NAME && tag[1].isNotEmpty()
+
+        fun parse(tag: Array<String>): ByteArray? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            return tag[1].hexToByteArrayOrNull()?.takeIf { it.size == 32 }
+        }
+
+        fun assemble(prevHash: ByteArray) = arrayOf(TAG_NAME, prevHash.toHexKey())
+    }
+}
@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.utils.ensure
+
+/** The `["ev", <n>]` edition-version tag: the monotonically increasing version of a kind-3308 edition. */
+class EvTag {
+    companion object {
+        const val TAG_NAME = "ev"
+
+        fun isTag(tag: Array<String>) = tag.has(1) && tag[0] == TAG_NAME && tag[1].isNotEmpty()
+
+        fun parse(tag: Array<String>): Long? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            return tag[1].toLongOrNull()?.takeIf { it >= 0 }
+        }
+
+        fun assemble(version: Long) = arrayOf(TAG_NAME, version.toString())
+    }
+}
@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control.tags
+
+import com.vitorpamplona.quartz.concord.cord04Roles.AuthorityCitation
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.utils.ensure
+
+/**
+ * The `["vac", <grantId>, <grantVersion>, <grantHash>]` versioned-authority-citation
+ * tag: the exact Grant edition a delegated actor claims authority under (CORD-04).
+ * Absent when the owner authors the edition. Carries three values, so it needs the
+ * full tag (not just a value) to round-trip.
+ */
+class VacTag {
+    companion object {
+        const val TAG_NAME = "vac"
+
+        fun isTag(tag: Array<String>) = tag.has(3) && tag[0] == TAG_NAME
+
+        fun parse(tag: Array<String>): AuthorityCitation? {
+            ensure(tag.has(3)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            val grantId = tag[1].hexToByteArrayOrNull()?.takeIf { it.size == 32 } ?: return null
+            val grantVersion = tag[2].toLongOrNull() ?: return null
+            val grantHash = tag[3].hexToByteArrayOrNull()?.takeIf { it.size == 32 } ?: return null
+            return AuthorityCitation(grantId, grantVersion, grantHash)
+        }
+
+        fun assemble(citation: AuthorityCitation) =
+            arrayOf(
+                TAG_NAME,
+                citation.grantId.toHexKey(),
+                citation.grantVersion.toString(),
+                citation.grantHash.toHexKey(),
+            )
+    }
+}
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.concord.cord04Roles.control.tags
+
+import com.vitorpamplona.quartz.concord.cord04Roles.ControlEntityKind
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.utils.ensure
+
+/**
+ * The `["vsk", <wire>]` versioned-sub-kind tag: which Control Plane entity a
+ * kind-3308 edition updates (metadata `0`, role `1`, channel `2`, grant `3`,
+ * banlist `4`, …). See [ControlEntityKind].
+ */
+class VskTag {
+    companion object {
+        const val TAG_NAME = "vsk"
+
+        fun isTag(tag: Array<String>) = tag.has(1) && tag[0] == TAG_NAME && tag[1].isNotEmpty()
+
+        fun parse(tag: Array<String>): ControlEntityKind? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            return ControlEntityKind.of(tag[1])
+        }
+
+        fun assemble(kind: ControlEntityKind) = arrayOf(TAG_NAME, kind.wire)
+    }
+}
@@ -23,6 +23,7 @@
 package com.vitorpamplona.quartz.utils

 import com.vitorpamplona.quartz.concord.cord02Community.ConcordCommunityListEvent
+import com.vitorpamplona.quartz.concord.cord04Roles.control.ControlEditionEvent
 import com.vitorpamplona.quartz.experimental.agora.FundraiserEvent
 import com.vitorpamplona.quartz.experimental.attestations.attestation.AttestationEvent
 import com.vitorpamplona.quartz.experimental.attestations.proficiency.AttestorProficiencyEvent
@@ -605,6 +606,7 @@ class EventFactory {
                RepostEvent.KIND -> RepostEvent(id, pubKey, createdAt, tags, content, sig)
                RequestToVanishEvent.KIND -> RequestToVanishEvent(id, pubKey, createdAt, tags, content, sig)
                ConcordCommunityListEvent.KIND -> ConcordCommunityListEvent(id, pubKey, createdAt, tags, content, sig)
+                ControlEditionEvent.KIND -> ControlEditionEvent(id, pubKey, createdAt, tags, content, sig)
                SealedRumorEvent.KIND -> SealedRumorEvent(id, pubKey, createdAt, tags, content, sig)
                SearchRelayListEvent.KIND -> SearchRelayListEvent(id, pubKey, createdAt, tags, content, sig)
                SimpleGroupListEvent.KIND -> SimpleGroupListEvent(id, pubKey, createdAt, tags, content, sig)