@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

package/src/utils/entities.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "bun:test"
+import type { RpcEntity } from "../types/rpcSchema"
+import { entityFromRpcResult } from "./entities"
+
+const KEY = `0x${"aa".repeat(32)}` as const
+
+/** A minimal row, with only the field under test varying. */
+function rowWith(creationFlags: RpcEntity["creationFlags"]): RpcEntity {
+  return { key: KEY, creationFlags }
+}
+
+describe("the creationFlags projection", () => {
+  it("decodes the bare byte a pre-spec node sends", () => {
+    expect(entityFromRpcResult(rowWith(0b11)).creationFlags).toEqual({
+      readonly: true,
+      permissionlessExtension: true,
+      raw: 0b11,
+    })
+  })
+
+  it("prefers raw over the booleans sent alongside it", () => {
+    // `raw` is the byte the engine stored, so it is the one reading that cannot disagree with what
+    // is on chain — and it keeps bits this SDK has no name for visible.
+    const flags = entityFromRpcResult(
+      rowWith({ readonly: false, permissionlessExtension: false, raw: 0b101 }),
+    ).creationFlags
+    expect(flags).toEqual({ readonly: true, permissionlessExtension: false, raw: 0b101 })
+  })
+
+  it("reads raw as the 0x quantity every other numeric field already uses", () => {
+    // createdAt, updatedAt and expiresAt are all hex on this surface, so a node rendering the flags
+    // byte the same way is the expected spelling, not a malformed response.
+    expect(
+      entityFromRpcResult(rowWith({ raw: "0x03" } as unknown as RpcEntity["creationFlags"]))
+        .creationFlags,
+    ).toEqual({ readonly: true, permissionlessExtension: true, raw: 3 })
+  })
+
+  it("falls back to the booleans when no byte arrives", () => {
+    expect(
+      entityFromRpcResult(
+        rowWith({ readonly: true, permissionlessExtension: false } as RpcEntity["creationFlags"]),
+      ).creationFlags,
+    ).toEqual({ readonly: true, permissionlessExtension: false, raw: 0b1 })
+  })
+
+  it("drops an unreadable encoding instead of failing the whole read", () => {
+    // Nothing on the decode path catches, so a throw here would not fail this field — it would
+    // fail the entire getEntity/fetch and take every other entity on the page with it.
+    for (const unreadable of [{}, { raw: "nonsense" }, { raw: 999 }, "flags"]) {
+      const entity = entityFromRpcResult(
+        rowWith(unreadable as unknown as RpcEntity["creationFlags"]),
+      )
+      expect(entity.creationFlags).toBeUndefined()
+      expect(entity.key).toBe(KEY)
+    }
+  })
+
+  it("stays undefined when the projection did not ask for it", () => {
+    expect(entityFromRpcResult({ key: KEY }).creationFlags).toBeUndefined()
+  })
+})

package/src/utils/entities.ts

@@ -1,37 +1,119 @@
-import { toBytes } from "viem"
-import { Entity } from "../types/entity"
+import { checksumAddress, type Hex, hexToBytes } from "viem"
+import type { AttributeSchema, Attributes } from "../attr"
+// Internal seam: the JSON-RPC decoder is not part of the package's public surface.
+import { asTypeTag, decodeRpcValue } from "../attr/codec"
+import {
+  decodeCreationFlags,
+  encodeCreationFlags,
+  type ResolvedCreationFlags,
+} from "../entity/flags"
+import { Entity, type EntityFields } from "../types/entity"
 import type { RpcEntity } from "../types/rpcSchema"
 import { getLogger } from "./logger"
 
 const logger = getLogger("utils:entities")
 
-export async function entityFromRpcResult(rpcEntity: RpcEntity) {
+/**
+ * Turns the attribute array a query returns into a name-keyed map of typed values.
+ *
+ * Attribute names are unique per entity, so the map loses nothing and gives callers
+ * `entity.attributes.level.value` instead of a linear search.
+ */
+function decodeAttributes(rpcAttributes: NonNullable<RpcEntity["attributes"]>): Attributes {
+  const attributes: Record<string, ReturnType<typeof decodeRpcValue>> = {}
+  for (const { name, type, value } of rpcAttributes) {
+    attributes[name] = decodeRpcValue(type, value)
+  }
+  return attributes
+}
+
+/** The same, for the values-free `attributeSchema` projection. */
+function decodeSchema(entries: NonNullable<RpcEntity["attributeSchema"]>): AttributeSchema {
+  const schema: Record<string, ReturnType<typeof asTypeTag>> = {}
+  for (const { name, type } of entries) {
+    schema[name] = asTypeTag(type)
+  }
+  return schema
+}
+
+/**
+ * Builds an {@link Entity} from a query result row.
+ *
+ * A field the query did not select is absent from the response and stays `undefined` here — the
+ * decoder never substitutes an empty value for one that was not asked for.
+ */
+export function entityFromRpcResult(rpcEntity: RpcEntity): Entity {
   logger("entityFromRpcResult %o", rpcEntity)
 
-  return new Entity(
-    rpcEntity.key,
-    rpcEntity.contentType,
-    rpcEntity.owner,
-    rpcEntity.creator,
-    rpcEntity.expiresAt !== undefined ? BigInt(rpcEntity.expiresAt) : undefined,
-    rpcEntity.createdAtBlock !== undefined ? BigInt(rpcEntity.createdAtBlock) : undefined,
-    rpcEntity.lastModifiedAtBlock !== undefined ? BigInt(rpcEntity.lastModifiedAtBlock) : undefined,
-    rpcEntity.transactionIndexInBlock !== undefined
-      ? BigInt(rpcEntity.transactionIndexInBlock)
-      : undefined,
-    rpcEntity.operationIndexInTransaction !== undefined
-      ? BigInt(rpcEntity.operationIndexInTransaction)
-      : undefined,
-    rpcEntity.value !== undefined ? toBytes(rpcEntity.value) : undefined,
-    [
-      ...(rpcEntity.stringAttributes ?? []).map(({ key, value }) => ({
-        key,
-        value,
-      })),
-      ...(rpcEntity.numericAttributes ?? []).map(({ key, value }) => ({
-        key,
-        value: Number(value),
-      })),
-    ],
-  )
+  const fields: EntityFields = {
+    key: rpcEntity.key,
+    owner: toAddress(rpcEntity.owner),
+    creator: toAddress(rpcEntity.creator),
+    createdAt: toBlock(rpcEntity.createdAt),
+    updatedAt: toBlock(rpcEntity.updatedAt),
+    expiresAt: toBlock(rpcEntity.expiresAt),
+    creationFlags: decodeFlags(rpcEntity.creationFlags),
+    contentType: rpcEntity.contentType,
+    payload: rpcEntity.payload !== undefined ? hexToBytes(rpcEntity.payload) : undefined,
+    attributeSchema:
+      rpcEntity.attributeSchema !== undefined ? decodeSchema(rpcEntity.attributeSchema) : undefined,
+    attributes:
+      rpcEntity.attributes !== undefined ? decodeAttributes(rpcEntity.attributes) : undefined,
+  }
+
+  return new Entity(fields)
+}
+
+function toBlock(value: string | undefined): bigint | undefined {
+  return value === undefined ? undefined : BigInt(value)
+}
+
+function toAddress(value: Hex | undefined): Hex | undefined {
+  if (value === undefined) return undefined
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    logger("unreadable address %o", value)
+    return value
+  }
+  return checksumAddress(value)
+}
+
+/**
+ * Resolves the `creationFlags` projection, preferring the byte.
+ */
+function decodeFlags(
+  value: NonNullable<RpcEntity["creationFlags"]> | undefined,
+): ResolvedCreationFlags | undefined {
+  if (value === undefined) return undefined
+
+  const raw = toFlagsByte(typeof value === "number" ? value : value.raw)
+  if (raw !== undefined) return decodeCreationFlags(raw)
+
+  if (
+    typeof value === "object" &&
+    (value.readonly ?? value.permissionlessExtension) !== undefined
+  ) {
+    return decodeCreationFlags(
+      encodeCreationFlags({
+        readonly: value.readonly ?? false,
+        permissionlessExtension: value.permissionlessExtension ?? false,
+      }),
+    )
+  }
+
+  logger("unreadable creationFlags %o", value)
+  return undefined
+}
+
+/**
+ * A flags byte in whichever spelling arrived: a JSON number, or the `0x` QUANTITY that every other
+ * numeric field on {@link RpcEntity} already uses. `undefined` for anything that is not a byte.
+ */
+function toFlagsByte(value: unknown): number | undefined {
+  const parsed =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && /^(0x[0-9a-fA-F]+|\d+)$/.test(value)
+        ? Number(value)
+        : Number.NaN
+  return Number.isInteger(parsed) && parsed >= 0 && parsed <= 0xff ? parsed : undefined
 }

package/src/utils/expirationTime.ts

@@ -1,13 +1,156 @@
-import { BLOCK_TIME } from "../consts"
+import { InvalidExpiryError } from "../entity/errors"
+import { type Expiry, type Lifetime, makeExpiry, toBlocks } from "../entity/expiry"
+import { MAX_EXPIRES_AT } from "../entity/params"
 
+/**
+ * The optional floor a deadline can carry.
+ *
+ * `atLeast` takes a duration — one of the `from*` helpers — and never another deadline, so
+ * `atBlock(x, { atLeast: atBlock(y) })` does not compile. Two deadlines are not a thing the engine
+ * can resolve.
+ */
+export type DeadlineOptions = {
+  /** Live at least this long from now, even if the deadline is sooner. */
+  atLeast?: Lifetime | undefined
+}
+
+function lifetimeOf(seconds: number): Lifetime {
+  return makeExpiry(toBlocks(seconds), 0n) as Lifetime
+}
+
+function deadlineOf(expiresAt: bigint | Date, options?: DeadlineOptions): Expiry {
+  return makeExpiry(options?.atLeast?.minLifetime ?? 0n, expiresAt)
+}
+
+/**
+ * Builds the `expires` of a create or an extension.
+ *
+ * Every helper returns the `{ minLifetime, expiresAt }` pair the ABI carries, so what you write is
+ * what goes on the wire. The `from*` helpers fill `minLifetime` and leave `expiresAt` at `0n`;
+ * {@link ExpirationTime.atBlock} and {@link ExpirationTime.atDate} do the reverse. The engine takes
+ * whichever comes later, which is why a deadline can also carry a floor.
+ *
+ * Values are plain data — no methods, no prototype — so they log, clone and compare like any other
+ * object.
+ *
+ * @example The 90% case: a duration, and nothing else to think about.
+ * await client.createEntity({ payload, contentType, expires: ExpirationTime.fromDays(30) })
+ *
+ * @example An exact block, or a wall-clock date.
+ * expires: ExpirationTime.atBlock(1_200_000n)
+ * expires: ExpirationTime.atDate(new Date("2027-01-01"))
+ *
+ * @example A deadline that still guarantees a minimum life.
+ * expires: ExpirationTime.atBlock(1_200_000n, { atLeast: ExpirationTime.fromDays(1) })
+ */
 export const ExpirationTime = {
-  fromSeconds: (seconds: number) => seconds,
-  fromMinutes: (minutes: number) => minutes * 60,
-  fromHours: (hours: number) => hours * 60 * 60,
-  fromDays: (days: number) => days * 24 * 60 * 60,
-  fromWeeks: (weeks: number) => weeks * 7 * 24 * 60 * 60,
-  fromMonths: (months: number) => months * 30 * 24 * 60 * 60,
-  fromYears: (years: number) => years * 365 * 24 * 60 * 60,
-  fromBlocks: (blocks: number) => blocks * BLOCK_TIME,
-  fromDate: (date: Date) => Math.floor(date.getTime() / 1000) - Math.floor(Date.now() / 1000),
+  /**
+   * A raw number of seconds. Must be a whole number of blocks' worth — see the other helpers, which
+   * all produce one by construction.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromSeconds: (seconds: number): Lifetime => lifetimeOf(seconds),
+  /**
+   * A number of minutes.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromMinutes: (minutes: number): Lifetime => lifetimeOf(minutes * 60),
+
+  /**
+   * A number of hours.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromHours: (hours: number): Lifetime => lifetimeOf(hours * 60 * 60),
+
+  /**
+   * A number of days. The everyday form — `fromDays(30)` is what most creates want.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromDays: (days: number): Lifetime => lifetimeOf(days * 24 * 60 * 60),
+
+  /**
+   * A number of weeks, each of 7 days.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromWeeks: (weeks: number): Lifetime => lifetimeOf(weeks * 7 * 24 * 60 * 60),
+
+  /**
+   * A number of months, each of exactly **30 days** — calendar months are not all the same length,
+   * and a lifetime is a duration rather than a date. Use {@link ExpirationTime.atDate} when the
+   * expiry has to land on a particular calendar day.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromMonths: (months: number): Lifetime => lifetimeOf(months * 30 * 24 * 60 * 60),
+
+  /**
+   * A number of years, each of exactly **365 days** — leap days are not counted, so `fromYears(4)`
+   * is a day short of four calendar years. Use {@link ExpirationTime.atDate} for a calendar
+   * deadline.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromYears: (years: number): Lifetime => lifetimeOf(years * 365 * 24 * 60 * 60),
+
+  /**
+   * A number of blocks, for callers who think in the chain's own unit. Always exact — there is no
+   * conversion to be approximate about.
+   *
+   * @throws {InvalidExpiryError} If the count is not a positive whole number.
+   */
+  fromBlocks: (blocks: number): Lifetime => {
+    if (!Number.isInteger(blocks) || blocks <= 0) {
+      throw new InvalidExpiryError(
+        `a lifetime must be a positive whole number of blocks, got ${blocks}`,
+      )
+    }
+    return makeExpiry(BigInt(blocks), 0n) as Lifetime
+  },
+
+  /**
+   * An absolute block height.
+   *
+   * @param block - The block the entity expires at.
+   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
+   * @throws {InvalidExpiryError} If the height is negative.
+   */
+  atBlock: (block: bigint, options?: DeadlineOptions): Expiry => {
+    if (typeof block !== "bigint" || block < 0n) {
+      throw new InvalidExpiryError(`a deadline must be a non-negative block height, got ${block}`)
+    }
+    return deadlineOf(block, options)
+  },
+
+  /**
+   * A wall-clock instant, placed against the block the transaction is built on.
+   *
+   * A date cannot land on a block boundary in general, so it rounds **up** to the next block: the
+   * entity lives until at least the instant asked for. This is why a date is never rejected for
+   * "not being a whole number of blocks" the way a duration is — it becomes a block height, not a
+   * duration.
+   *
+   * @param date - When the entity should expire.
+   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
+   * @throws {InvalidExpiryError} If the value is not a valid `Date`.
+   */
+  atDate: (date: Date, options?: DeadlineOptions): Expiry => {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+      throw new InvalidExpiryError(`a deadline must be a valid Date, got ${String(date)}`)
+    }
+    return deadlineOf(date, options)
+  },
+
+  /**
+   * An entity that should never expire.
+   *
+   * This is `atBlock(MAX_EXPIRES_AT)` — the largest expiry the `uint64` field holds — and the
+   * engine treats it as an ordinary deadline rather than a special case. There is no permanence
+   * flag; a block height no chain will reach is what permanence is.
+   */
+  permanent: (): Expiry => deadlineOf(MAX_EXPIRES_AT),
 }

package/src/utils/logger.ts

@@ -144,8 +144,8 @@ function getColorForNamespace(namespace: string): { css: string; ansi: string }
 
   // Use absolute value and modulo to get index
   const colorIndex = Math.abs(hash) % COLOR_PALETTE.length
-  const cssColor = COLOR_PALETTE[colorIndex]
-  const ansiColor = ANSI_COLORS[colorIndex % ANSI_COLORS.length]
+  const cssColor = COLOR_PALETTE[colorIndex] ?? "inherit"
+  const ansiColor = ANSI_COLORS[colorIndex % ANSI_COLORS.length] ?? ""
 
   const color = { css: cssColor, ansi: ansiColor }
 

package/src/utils/payload.ts

@@ -1,9 +1,36 @@
-import { toBytes } from "viem"
+import { stringToBytes, toBytes } from "viem"
 
+/**
+ * A JSON-serialisable value as an entity payload — `JSON.stringify` then UTF-8.
+ *
+ * Pair it with `contentType: "application/json"`, which is what lets `entity.toJson()` read it back.
+ *
+ * @example
+ * await client.createEntity({
+ *   payload: jsonToPayload({ hello: "world" }),
+ *   contentType: "application/json",
+ *   expires: ExpirationTime.fromDays(30),
+ * })
+ */
 export function jsonToPayload(json: object): Uint8Array {
   return toBytes(JSON.stringify(json))
 }
 
+/**
+ * A string as an entity payload, encoded as UTF-8.
+ *
+ * Hex-looking text is encoded as text: `stringToPayload("0xab")` gives the four bytes of that
+ * string, not the single byte `0xab`. Read it back with `entity.toText()`.
+ *
+ * @example
+ * await client.createEntity({
+ *   payload: stringToPayload("hello"),
+ *   contentType: "text/plain",
+ *   expires: ExpirationTime.fromDays(30),
+ * })
+ */
 export function stringToPayload(data: string): Uint8Array {
-  return toBytes(data)
+  // stringToBytes, not toBytes: toBytes hex-decodes hex-looking strings, which
+  // would corrupt payloads like "0xab" instead of UTF-8 encoding them
+  return stringToBytes(data)
 }

package/src/utils/revert.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "bun:test"
+import { BaseError, ContractFunctionRevertedError, type Hex, toHex } from "viem"
+import { describeEntityRevert } from "./revert"
+
+/**
+ * Wraps a decoded revert the way viem delivers one: the `ContractFunctionRevertedError` is nested
+ * in a cause chain, which is why `describeEntityRevert` walks rather than type-checks the top.
+ */
+function reverted(errorName: string, args: readonly unknown[]): BaseError {
+  const inner = new ContractFunctionRevertedError({
+    abi: [],
+    functionName: "execute",
+  })
+  // The constructor cannot build `data` without a real ABI decode, so it is set directly — the
+  // shape is what matters here, not how viem arrived at it.
+  Object.assign(inner, { data: { errorName, args } })
+  return new BaseError('The contract function "execute" reverted.', { cause: inner })
+}
+
+/** An Ident32 name cell: the name, left-aligned and null-padded to 32 bytes. */
+const ident = (name: string): Hex => toHex(name, { size: 32 })
+
+const KEY = `0x${"ab".repeat(32)}` as Hex
+
+describe("describeEntityRevert", () => {
+  it("ignores anything that is not a decoded engine revert", () => {
+    expect(describeEntityRevert(new Error("boom"))).toBeUndefined()
+    expect(describeEntityRevert("boom")).toBeUndefined()
+    expect(describeEntityRevert(undefined)).toBeUndefined()
+    expect(describeEntityRevert(new BaseError("no cause"))).toBeUndefined()
+  })
+
+  describe("attribute names", () => {
+    it("names the offending character rather than printing the byte alone", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [5n, "0x21"]))
+      expect(message).toContain('"!"')
+      expect(message).toContain("0x21")
+      expect(message).toContain("byte 5")
+    })
+
+    it("quotes the name charset the SDK itself validates against", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [0n, "0x2f"]))
+      expect(message).toContain('"A"-"Z"')
+      expect(message).toContain('"a"-"z"')
+      expect(message).toContain("with a letter first")
+    })
+
+    it("renders an unprintable byte as a byte", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [1n, "0x07"]))
+      expect(message).toContain("byte 0x07")
+    })
+  })
+
+  describe("names carried in a bytes32 cell", () => {
+    it("reads the name back out of its null padding", () => {
+      expect(
+        describeEntityRevert(reverted("SystemAttributeNotWritable", [ident("$owner")])),
+      ).toContain('"$owner"')
+      expect(describeEntityRevert(reverted("TombstoneInCreate", [ident("gone")]))).toContain(
+        '"gone"',
+      )
+      expect(describeEntityRevert(reverted("InvalidValueType", [ident("level"), 99]))).toContain(
+        '"level"',
+      )
+    })
+  })
+
+  describe("entity state", () => {
+    it("abbreviates the key so it does not bury the sentence", () => {
+      const message = describeEntityRevert(reverted("EntityNotFound", [KEY]))
+      expect(message).toContain("…")
+      expect(message).not.toContain(KEY)
+    })
+
+    it("explains a readonly entity in terms of what is still allowed", () => {
+      const message = describeEntityRevert(reverted("ReadOnlyEntity", [KEY]))
+      expect(message).toContain("readonly")
+      expect(message).toContain("extended")
+    })
+
+    it("renders reserved creation flags as the bits they are", () => {
+      const message = describeEntityRevert(reverted("ReservedCreationFlags", [0b100]))
+      expect(message).toContain("0b00000100")
+    })
+  })
+
+  describe("expiry", () => {
+    it("says which way the extension went wrong", () => {
+      const message = describeEntityRevert(reverted("ExpiryNotExtended", [KEY, 100n, 500n]))
+      expect(message).toContain("already expires at block 500")
+      expect(message).toContain("shorten")
+    })
+  })
+
+  it("falls back to naming the error when it has no tailored explanation", () => {
+    const message = describeEntityRevert(reverted("SomeFutureError", []))
+    expect(message).toBe("the engine rejected the batch with SomeFutureError")
+  })
+})

package/src/utils/revert.ts

@@ -0,0 +1,145 @@
+import { BaseError, ContractFunctionRevertedError, type Hex, hexToString } from "viem"
+
+/**
+ * Turns a decoded engine revert into a sentence that says what to change.
+ *
+ * viem decodes the error and then renders it positionally — `Ident32InvalidByte(uint256 position,
+ * bytes1 value)` arrives as `(5, 0x41)`, which is the right data and no help at all. The engine's
+ * errors carry enough to name the actual problem, so this spends the args rather than printing
+ * them.
+ *
+ * @param error - Anything thrown by a write action.
+ * @returns The explanation, or `undefined` if this was not a decodable engine revert — in which
+ * case the caller should fall back to whatever the transport said.
+ */
+export function describeEntityRevert(error: unknown): string | undefined {
+  if (!(error instanceof BaseError)) return undefined
+  const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError)
+  if (!(reverted instanceof ContractFunctionRevertedError)) return undefined
+
+  const name = reverted.data?.errorName
+  if (name === undefined) return undefined
+  const args = (reverted.data?.args ?? []) as readonly unknown[]
+
+  return explain(name, args) ?? `the engine rejected the batch with ${name}`
+}
+
+/** The attribute-name charset, quoted the way an error message should read. */
+const CHARSET = '"A"-"Z", "a"-"z", "0"-"9", ".", "-" and "_", with a letter first'
+
+function explain(name: string, args: readonly unknown[]): string | undefined {
+  switch (name) {
+    // ── attribute names ──────────────────────────────────────────────────────
+    case "Ident32InvalidByte": {
+      const position = Number(args[0] ?? 0)
+      const char = printable(String(args[1] ?? "0x00"))
+      return (
+        `an attribute name holds ${char} at byte ${position}, which is outside the ` +
+        `name charset (${CHARSET})`
+      )
+    }
+    case "Ident32Empty":
+      return "an attribute name is empty"
+
+    // ── the attribute list ───────────────────────────────────────────────────
+    case "SystemAttributeNotWritable":
+      return (
+        `"${identName(args[0])}" is owned by the engine and cannot be written. Only $payload and ` +
+        "$contentType are yours to set"
+      )
+    case "TombstoneInCreate":
+      return (
+        `a create cannot unset "${identName(args[0])}" — nothing exists yet, so leave the name ` +
+        "out instead"
+      )
+    case "TombstoneValueNotEmpty":
+      return `the tombstone for "${identName(args[0])}" carries a value; unsetting takes no value`
+    case "InvalidValueType":
+      return `"${identName(args[0])}" names type id ${String(args[1])}, which is not a known type`
+    case "AttributesNotSorted":
+      return "attributes must be strictly ascending by name, which also makes each name unique"
+    case "TooManyAttributes":
+      return `${String(args[0])} attributes exceeds the limit of ${String(args[1])}`
+    case "EmptyMutations":
+      return `the patch of ${short(args[0])} has no mutations, so it would do nothing`
+
+    // ── entity state and authorisation ───────────────────────────────────────
+    case "EntityNotFound":
+      return `no entity ${short(args[0])} — it may have been deleted, or have expired`
+    case "EntityExpired":
+      return `entity ${short(args[0])} expired at block ${String(args[1])}`
+    case "NotOwner":
+      return `entity ${short(args[0])} is owned by ${String(args[2])}, not ${String(args[1])}`
+    case "ReadOnlyEntity":
+      return (
+        `entity ${short(args[0])} was created readonly, so its contents can never change. Its ` +
+        "expiry can still be extended, and it can be transferred or deleted"
+      )
+    case "ReservedCreationFlags":
+      return (
+        `creation flags 0b${Number(args[0] ?? 0)
+          .toString(2)
+          .padStart(8, "0")} set a reserved ` +
+        "bit; only readonly and permissionlessExtension are defined"
+      )
+
+    // ── expiry ───────────────────────────────────────────────────────────────
+    case "ExpiryDeadOnArrival":
+      return (
+        `the expiry resolves to block ${String(args[0])}, which is not after the current block ` +
+        `${String(args[1])}`
+      )
+    case "ExpiryNotExtended":
+      return (
+        `entity ${short(args[0])} already expires at block ${String(args[2])}, so extending it ` +
+        `to ${String(args[1])} would shorten its life`
+      )
+
+    // ── ownership ────────────────────────────────────────────────────────────
+    case "TransferToZeroAddress":
+      return `entity ${short(args[0])} cannot be transferred to the zero address`
+    case "TransferToSelf":
+      return `entity ${short(args[0])} is already owned by that account`
+
+    // ── batch framing ────────────────────────────────────────────────────────
+    case "EmptyBatch":
+      return "the batch has no operations"
+    case "InvalidOpType":
+      return `operation tag ${String(args[0])} is not one the engine knows`
+    case "NonCanonicalOperationData":
+      return (
+        `the payload for operation tag ${String(args[0])} is not its canonical encoding, so the ` +
+        "engine refused it rather than accept a second spelling of the same operation"
+      )
+
+    default:
+      return undefined
+  }
+}
+
+/** A `bytes32` Ident32 cell as the name it holds — left-aligned, null-padded. */
+function identName(raw: unknown): string {
+  if (typeof raw !== "string") return String(raw)
+  try {
+    // Cut at the first null rather than trimming with a regex: the padding is whatever follows
+    // the name, so everything before it is the name and nothing after it is. Written as an escape
+    // because a literal NUL byte in source is invisible to every reader after you.
+    return hexToString(raw as Hex).split("\u0000")[0] ?? ""
+  } catch {
+    return raw
+  }
+}
+
+/** An entity key, abbreviated */
+function short(raw: unknown): string {
+  const text = String(raw)
+  return text.length > 18 ? `${text.slice(0, 10)}…${text.slice(-6)}` : text
+}
+
+/** A `bytes1` as something readable: the character it is, plus the byte it was. */
+function printable(byte: string): string {
+  const code = Number.parseInt(byte.replace(/^0x/, ""), 16)
+  if (!Number.isFinite(code)) return `byte ${byte}`
+  const char = String.fromCharCode(code)
+  return code >= 0x21 && code <= 0x7e ? `"${char}" (${byte})` : `byte ${byte}`
+}