AGENTS.md

@@ -54,6 +54,7 @@ In `docs/decisions.md`:
 - The flavour spec is read as a source
 - The node tables answer to Atlassian's schema
 - Nothing recurses unbounded
+- The guards take what `JSON.parse` or `structuredClone` builds
 - Nothing spreads an unbounded array
 - A retry loop checks its own termination
 - Readers scan by index

CHANGELOG.md

@@ -32,9 +32,7 @@
 - Fix an image inside another image's description: it flattens into the alt text, where it was
   refused.
 - Fix a cyclic document, in which an object holds itself: `adfToMarkdown` and `adfToPlainMarkdown`
-  refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung. A
+  refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung.
-  node or mark whose `attrs`, `content`, `marks`, `text` or `type` is not its own enumerable key is
-  refused alike, where it was read.
 
 ## 0.1.0
 

README.md

@@ -33,7 +33,7 @@ The most useful ADF conversion library available, judged by these goals, in prio
 5. **No surprises: output reads and edits the way its audience expects.**
 6. **Lossy conversion drops form, never content.**
 7. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.**
-8. **Fast, and linear in the document's size.**
+8. **Fast, and linear in the document's size as JSON.**
 9. **Easy to find, and clear at a glance what it does.**
 
 ## Audience
@@ -238,8 +238,8 @@ Serves Goals 1, 3 and 4.
   input.
 - Past that and `~~`, no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist
   is the `taskList` directive — `plainMarkdownToAdf` turns the marker into a `taskList`.
-- A document nested deeper than 500 levels is an error result, not a stack overflow, and no input
+- A document nested deeper than 500 levels is an error result, not a stack overflow, and no value
-  makes a call loop forever.
+  `JSON.parse` or `structuredClone` builds makes a call loop forever.
 - The emitted formats are semver surface
   ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#the-formats-are-api)).
 - **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` deep-equals `doc`; fidelity HTML cannot express rides

docs/decisions.md

@@ -563,6 +563,16 @@ format, as its parser does. A list giving way to the directive form refuses at z
 than walking again; counting every list twice halved the list limit, counting the directive form
 once doubled the parser's frames per level.
 
+## The guards take what `JSON.parse` or `structuredClone` builds
+
+2026-10-04, the maintainer. Goal 1. Valid while every persona hands in a value `JSON.parse`,
+`structuredClone` or an object literal builds.
+
+The guarantees speak of plain data: own enumerable keys and plain arrays, cycles and shared objects
+included. The guards walk it by `Object.values` and refuse a cycle. An inherited or non-enumerable
+key, a getter, a Proxy or a custom iterator is the caller's to rule out: no persona builds one, and
+each guarded shape asked for another.
+
 ## Nothing spreads an unbounded array
 
 2026-09-18, the maintainer. Goal 1. Valid while engines cap a call's arguments.

src/adf/document.test.ts

@@ -83,7 +83,7 @@ test("reads a node's siblings as a walk rather than as one call's arguments", ()
   assert.equal(fault(wide), 'accepted')
 })
 
-test('refuses an object holding itself or a key it does not own, and accepts one shared', () => {
+test('refuses an object holding itself, and accepts one shared', () => {
   const holdsItself = 'an ADF document is a tree: an object in it holds itself'
   const paragraph: { content: unknown[]; type: string } = { content: [], type: 'paragraph' }
   paragraph.content.push(paragraph)
@@ -96,26 +96,6 @@ test('refuses an object holding itself or a key it does not own, and accepts one
   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 notANode = "an ADF document's content holds ADF nodes: one of them is not"
-  const inherits: { content?: unknown[] } = {}
-  const heir: Record<string, unknown> = Object.create(inherits)
-  heir['type'] = 'paragraph'
-  inherits.content = [heir]
-  assert.equal(fault({ content: [heir], type: 'doc', version: 1 }), notANode)
-  const hidden: Record<string, unknown> = { type: 'paragraph' }
-  Object.defineProperty(hidden, 'content', { value: [hidden] })
-  assert.equal(fault({ content: [hidden], type: 'doc', version: 1 }), notANode)
-  const link: Record<string, unknown> = Object.create({ attrs })
-  link['type'] = 'link'
-  assert.equal(fault({ content: [{ marks: [link], text: 'x', type: 'text' }], type: 'doc', version: 1 }), notANode)
-  const indexed: unknown[] = []
-  Object.defineProperty(indexed, 0, { value: indexed })
-  assert.equal(fault({ content: [{ attrs: { a: indexed }, type: 'paragraph' }], type: 'doc', version: 1 }), holdsItself)
-  const inheritedIndex: { content?: unknown[]; type: string } = { type: 'paragraph' }
-  const heirs: unknown[] = Object.setPrototypeOf([], [inheritedIndex])
-  heirs.length = 1
-  inheritedIndex.content = heirs
-  assert.equal(fault({ content: [inheritedIndex], type: 'doc', version: 1 }), holdsItself)
   const bold = { type: 'strong' }
   const text = { marks: [bold], text: 'x', type: 'text' }
   const shared = { content: [text, text], type: 'paragraph' }

src/adf/document.ts

@@ -106,7 +106,7 @@ export function isAdfNode(value: unknown): value is AdfNode {
 }
 
 export function isAdfMark(value: unknown): value is AdfMark {
-  if (!isRecord(value) || !holdsOnly(value, markKeys) || !ownsWhatItHolds(value, markKeys)) return false
+  if (!isRecord(value) || !holdsOnly(value, markKeys)) return false
   if (typeof value['type'] !== 'string') return false
   return !('attrs' in value) || isAttributes(value['attrs'])
 }
@@ -135,7 +135,7 @@ function holdsItself(root: object): boolean {
     if (onPath.has(entry.item)) return true
     ancestors.push(entry.item)
     onPath.add(entry.item)
-    for (const child of Array.isArray(entry.item) ? [...entry.item] : Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child })
+    for (const child of Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child })
   }
   return false
 }
@@ -144,7 +144,7 @@ function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] {
   const pending: unknown[] = [...value]
   while (pending.length > 0) {
     const node = pending.pop()
-    if (!isRecord(node) || !holdsOnly(node, nodeKeys) || !ownsWhatItHolds(node, nodeKeys)) return false
+    if (!isRecord(node) || !holdsOnly(node, nodeKeys)) return false
     if (typeof node['type'] !== 'string') return false
     if ('attrs' in node && !isAttributes(node['attrs'])) return false
     if ('marks' in node && !isArrayOf(node['marks'], isAdfMark)) return false
@@ -219,11 +219,6 @@ function extraKey(value: Record<string, unknown>, keys: readonly string[]): stri
   return Object.keys(value).find((key) => !keys.includes(key))
 }
 
-// holdsItself walks own enumerable keys alone, so a guard reading any other key could walk a cycle forever.
-function ownsWhatItHolds(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  return keys.every((key) => !(key in value) || Object.prototype.propertyIsEnumerable.call(value, key))
-}
-
 function holdsOnly(value: Record<string, unknown>, keys: readonly string[]): boolean {
   return extraKey(value, keys) === undefined
 }