Answer product-owner round 1: name the cycle in its own message and in the error table

src/adf/document.test.ts

@@ -83,18 +83,18 @@ test("reads a node's siblings as a walk rather than as one call's arguments", ()
   assert.equal(fault(wide), 'accepted')
 })
 
-test('refuses a document that holds itself, and accepts one sharing a node or a mark', () => {
-  const notANode = "an ADF document's content holds ADF nodes: one of them is not"
+test('refuses a node or an attribute value holding itself, and accepts one shared', () => {
+  const holdsItself = 'an ADF document is a tree: a node or an attribute value holds itself'
   const paragraph: { content: unknown[]; type: string } = { content: [], type: 'paragraph' }
   paragraph.content.push(paragraph)
-  assert.equal(fault({ content: [paragraph], type: 'doc', version: 1 }), notANode)
+  assert.equal(fault({ content: [paragraph], type: 'doc', version: 1 }), holdsItself)
   const document: { content: unknown[]; type: string; version: number } = { content: [], type: 'doc', version: 1 }
   document.content.push(document)
-  assert.equal(fault(document), notANode)
+  assert.equal(fault(document), holdsItself)
   const attrs: Record<string, unknown> = {}
   attrs['a'] = [attrs]
-  assert.equal(fault({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), notANode)
-  assert.equal(fault({ content: [{ marks: [{ attrs, type: 'link' }], text: 'x', type: 'text' }], type: 'doc', version: 1 }), notANode)
+  assert.equal(fault({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), holdsItself)
+  assert.equal(fault({ content: [{ marks: [{ attrs, type: 'link' }], text: 'x', type: 'text' }], type: 'doc', version: 1 }), holdsItself)
   assert.equal(isAdfDocument({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), false)
   const bold = { type: 'strong' }
   const text = { marks: [bold], text: 'x', type: 'text' }

src/adf/document.ts

@@ -43,6 +43,7 @@ export function adfDocumentFault(value: unknown): ConvertFault | undefined {
   const held: unknown = value['content']
   if (!Array.isArray(held)) return notADocument(`an ADF document's content is an array: found ${describe(held)}`)
   const content: readonly unknown[] = held
+  if (holdsItself(content)) return notADocument('an ADF document is a tree: a node or an attribute value holds itself')
   if (!isNodeArray(content)) return notADocument("an ADF document's content holds ADF nodes: one of them is not")
   return nestingFault(content)
 }
@@ -122,6 +123,23 @@ export function nodeMarks(node: { marks?: AdfMark[] }): readonly AdfMark[] {
   return node.marks ?? []
 }
 
+// Ancestors alone: a tree may share an object, but an object holding itself walks the guards forever.
+function holdsItself(root: object): boolean {
+  const pending = [{ depth: 0, item: root }]
+  const ancestors: object[] = []
+  const onPath = new Set<object>()
+  while (pending.length > 0) {
+    const entry = pending.pop()
+    if (entry === undefined) continue
+    for (const left of ancestors.splice(entry.depth)) onPath.delete(left)
+    if (onPath.has(entry.item)) return true
+    ancestors.push(entry.item)
+    onPath.add(entry.item)
+    for (const child of Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child })
+  }
+  return false
+}
+
 function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] {
   const pending: unknown[] = [...value]
   while (pending.length > 0) {