jmd-format 0.1.2 → 0.2.1

package/LICENSE

@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 Andreas Ostermeyer <andreas@ostermeyer.de>
-
-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.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -127,4 +127,6 @@ parser side, following §22.1 of the specification.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+Apache 2.0 — see [LICENSE](./LICENSE).
+
+The JMD format specification is licensed separately under [CC BY 4.0](https://github.com/ostermeyer/jmd-spec/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmd-format",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "JMD (JSON Markdown) — structured data format for LLM-driven infrastructure. JavaScript reference implementation.",
   "type": "module",
   "main": "./src/index.js",
@@ -11,7 +11,7 @@
     "name": "Andreas Ostermeyer",
     "email": "andreas@ostermeyer.de"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "homepage": "https://github.com/ostermeyer/jmd-spec",
   "repository": {
     "type": "git",

package/src/index.js

@@ -1,7 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
 // jmd-format — JavaScript reference implementation.
 //
 // Public surface: minimal on purpose. Batch API for the common case,
 // streaming API for large or incremental workloads.
 
-export { parse, createParser, toLines } from './parser.js'
-export { serialize, serializeLines } from './serializer.js'
+export { parse, createParser, toLines, JMDParseError } from './parser.js'
+export { serialize, serializeLines, validateLabel } from './serializer.js'

package/src/parser.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // JMD parser.
 //
 // The parser processes a JMD document line by line, maintaining a scope
@@ -8,11 +9,37 @@
 //
 // Both share the same line-processing core. Events follow the sequence
 // defined in JMD spec §18.2. Parser-tolerant per §22.1.
+//
+// Spec coverage: v0.3.3 — including §7.4 repeated-heading promotion with
+// three structured errors (sigil_conflict, repeated_explicit_array,
+// repeated_scalar_key), §3.5.1 frontmatter `---` marker tolerance, and
+// §5.2 multi-line block scalars (`|` literal, `>` folded).
 
 import { parseScalar, parseKey, parseField } from './value.js'
 
 const HEADING = /^(#+)([!?-])?(?:\s+(.*))?$/
 
+// §7.4 — kinds tracked per object scope to detect repeated-heading
+// conflicts and to drive implicit-array promotion.
+const K_OBJECT_HEADING = 1   // `## foo` opened an object scope
+const K_ARRAY_SIGIL = 2      // `## foo[]` opened an explicit array
+const K_ARRAY_PROMOTED = 3   // two `## foo` collapsed into an array
+const K_SCALAR_BARE = 4      // `foo: 1` at column 0
+const K_SCALAR_HEADING = 5   // `## foo: 1`
+
+// Structured parse error — `kind` lets callers distinguish the §7.4
+// conditions (and any other tagged failures we add later) from generic
+// malformed-input errors. The line number is appended to the message
+// for legibility but also stored separately on the error.
+export class JMDParseError extends Error {
+  constructor(kind, message, line) {
+    super(message + ' (line ' + line + ')')
+    this.name = 'JMDParseError'
+    this.kind = kind
+    this.line = line
+  }
+}
+
 export function createParser() {
   let lineNo = 0
 
@@ -21,19 +48,28 @@ export function createParser() {
   let label = null
   const frontmatter = {}
   let inFrontmatter = true
+  let frontmatterStarted = false  // §3.5.1: have we seen any frontmatter field?
   let seenRoot = false
   let root = null
 
   // Scope stack. Each entry:
-  //   { kind: 'object' | 'array', container, depth, currentItem? }
-  // currentItem lives on array scopes only and holds the object built by
-  // the most recent `- ` line so indented continuations attach to it.
+  //   { kind: 'object' | 'array', container, depth,
+  //     seen: Map<key, K_*>,        // object scopes only
+  //     currentItem?, itemSeen? }   // array scopes only
+  // currentItem lives on array scopes and holds the object built by the
+  // most recent `- ` line so indented continuations attach to it.
+  // itemSeen mirrors `seen` for that per-item object.
   let stack = []
 
   // Pending blockquote state.
   //   { container, key, lines }
   let bq = null
 
+  // Pending block-scalar state (§5.2).
+  //   { container, key, kind: '|' | '>', lines, baseIndent }
+  // baseIndent is null until the first content line establishes it.
+  let block = null
+
   // A blank line may or may not terminate the current scope — it depends on
   // what comes after. We defer the decision: flag the blank, then let the
   // next real line resolve it. A deeper heading re-enters (no reset); a bare
@@ -58,6 +94,11 @@ export function createParser() {
     lineNo++
     const line = rawLine.replace(/\r$/, '')
 
+    if (block !== null) {
+      if (processBlockLine(line)) return drain()
+      // Block ended; fall through to normal line handling.
+    }
+
     if (bq !== null) {
       if (line === '>' || line.startsWith('> ')) {
         const content = line === '>' ? '' : line.slice(2)
@@ -114,11 +155,15 @@ export function createParser() {
 
   function onThematicBreak() {
     blankPending = false
-    // A thematic break is consumed by the innermost enclosing array whose
-    // most-recent item is a dict containing nested structures — this is
-    // the only context where jmd-format emits the break, and the parser
-    // mirrors that rule (spec §8.6). Inner scopes are closed; if no array
-    // on the stack qualifies, the line is tolerated as decoration.
+    // A thematic break closes any sub-scope opened by the most-recent
+    // item, then signals the next item of the enclosing array (spec §8.6).
+    // We search outward for the innermost array whose last item opened a
+    // sub-structure and close down to it. If none qualifies, the break is
+    // a no-op — and that is correct, not lossy: a flat item opens no
+    // sub-scope, so the enclosing array is still current and the next
+    // `- ` item continues it. This is why a `---` after a flat item in a
+    // mixed array (canonical per the v0.3.4 §8.6 clarification) parses
+    // without dropping the following item.
     let targetIdx = -1
     for (let i = stack.length - 1; i >= 0; i--) {
       const s = stack[i]
@@ -148,23 +193,118 @@ export function createParser() {
     bq = null
   }
 
+  // --- Block scalars (§5.2) ------------------------------------------------
+
+  function startBlock(container, key, kind) {
+    block = { container, key, kind, lines: [], baseIndent: null }
+    emit('field_start', { key })
+  }
+
+  // Returns true if the line was consumed by the block scalar, false if it
+  // signals the block has ended and the line must be re-dispatched normally.
+  function processBlockLine(line) {
+    if (line === '') {
+      block.lines.push('')
+      return true
+    }
+    const m = /^(\s*)/.exec(line)
+    const indent = m[0].length
+    if (block.baseIndent === null) {
+      if (indent === 0) {
+        commitBlock()
+        return false
+      }
+      block.baseIndent = indent
+      block.lines.push(line.slice(indent))
+      return true
+    }
+    if (indent < block.baseIndent && /\S/.test(line)) {
+      commitBlock()
+      return false
+    }
+    block.lines.push(line.slice(block.baseIndent))
+    return true
+  }
+
+  function commitBlock() {
+    const lines = block.lines.slice()
+    // Drop trailing blank lines for both kinds — spec §5.2 treats the
+    // trailing newline as a line-terminator, not part of the value.
+    while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+    const value = block.kind === '|' ? lines.join('\n') : foldLines(lines)
+    block.container[block.key] = value
+    emit('field', { key: block.key, value })
+    block = null
+  }
+
+  // Folded block scalar fold (§5.2):
+  //   consecutive non-blank lines  →  joined with single space
+  //   one blank between groups     →  one newline
+  //   N+1 blank lines              →  N newlines
+  function foldLines(lines) {
+    let out = ''
+    let group = []
+    let blanks = 0
+    function flushGroup() {
+      if (group.length > 0) {
+        out += group.join(' ')
+        group = []
+      }
+    }
+    for (const ln of lines) {
+      if (ln === '') {
+        flushGroup()
+        blanks++
+      } else {
+        if (blanks > 0) {
+          out += '\n'.repeat(blanks)
+          blanks = 0
+        }
+        group.push(ln)
+      }
+    }
+    flushGroup()
+    return out
+  }
+
   // --- Root / frontmatter --------------------------------------------------
 
   function onFrontmatter(line) {
+    // §3.5.1: tolerate `---` (or more) marker lines bracketing the
+    // frontmatter block. A marker before any field opens it; a marker
+    // after the last field separates it from the root heading. Both
+    // forms are consumed without emitting a frontmatter event.
+    if (/^-{3,}$/.test(line)) {
+      // Marker is structural-only — no state change beyond ignoring it.
+      return
+    }
     const f = parseField(line)
     if (f) {
-      const v = f.empty ? true : f.value
-      frontmatter[f.key] = v
-      emit('frontmatter', { key: f.key, value: v })
+      if (f.empty) {
+        // D12: multi-line frontmatter value enters a blockquote that
+        // collects subsequent `> ...` lines; commit assigns the joined
+        // string to frontmatter[key] (handled by the bq state machine).
+        frontmatterStarted = true
+        startBlockquote(frontmatter, f.key)
+        return
+      }
+      frontmatter[f.key] = f.value
+      frontmatterStarted = true
+      emit('frontmatter', { key: f.key, value: f.value })
       return
     }
     const pk = parseKey(line)
     if (pk && pk.rest === '') {
       frontmatter[pk.key] = true
+      frontmatterStarted = true
       emit('frontmatter', { key: pk.key, value: true })
       return
     }
-    throw parseError('Unexpected line before root heading')
+    throw new JMDParseError(
+      'malformed_frontmatter',
+      'Unexpected line before root heading',
+      lineNo,
+    )
   }
 
   function openRoot(modeMark, text) {
@@ -179,31 +319,50 @@ export function createParser() {
     if (text === '[]') {
       label = '[]'
       root = []
-      stack = [{ kind: 'array', container: root, depth: 1, currentItem: null }]
+      stack = [arrayScope(root, 1)]
     } else if (text.endsWith('[]')) {
       label = text.slice(0, -2)
       root = []
-      stack = [{ kind: 'array', container: root, depth: 1, currentItem: null }]
+      stack = [arrayScope(root, 1)]
     } else {
       label = text
       root = {}
-      stack = [{ kind: 'object', container: root, depth: 1 }]
+      stack = [objectScope(root, 1)]
     }
     emit('document_start', { mode, label })
   }
 
+  function objectScope(container, depth) {
+    return { kind: 'object', container, depth, seen: new Map() }
+  }
+
+  function arrayScope(container, depth) {
+    return {
+      kind: 'array', container, depth,
+      currentItem: null, itemSeen: null,
+    }
+  }
+
   // --- Headings ------------------------------------------------------------
 
   function onHeading(depth, modeMark, text) {
     if (!seenRoot) {
       if (depth !== 1) {
-        throw parseError('Document must begin with a depth-1 heading')
+        throw new JMDParseError(
+          'malformed_root',
+          'Document must begin with a depth-1 heading',
+          lineNo,
+        )
       }
       openRoot(modeMark, text)
       return
     }
     if (modeMark) {
-      throw parseError('Mode markers (!, ?, -) are only valid on the root heading')
+      throw new JMDParseError(
+        'malformed_heading',
+        'Mode markers (!, ?, -) are only valid on the root heading',
+        lineNo,
+      )
     }
 
     // Depth-qualified array item (§8.6a) or depth+1 item (§8.6b):
@@ -231,22 +390,37 @@ export function createParser() {
     if (text.endsWith('[]')) {
       const keyText = text.slice(0, -2)
       const pk = parseKey(keyText)
-      if (!pk || pk.rest !== '') throw parseError('Malformed array heading key')
+      if (!pk || pk.rest !== '') {
+        throw new JMDParseError(
+          'malformed_heading',
+          'Malformed array heading key',
+          lineNo,
+        )
+      }
       openArrayScope(depth, pk.key)
       return
     }
 
     const field = parseField(text)
-    if (field && !field.empty) {
-      const parent = parentObjectAt(depth)
-      parent[field.key] = field.value
+    if (field && field.value !== undefined) {
+      const { container, seen } = scalarParentAt(depth)
+      checkScalar(seen, field.key, K_SCALAR_HEADING)
+      container[field.key] = field.value
       emit('field', { key: field.key, value: field.value })
       return
     }
 
     if (field && field.empty) {
-      const parent = parentObjectAt(depth)
-      startBlockquote(parent, field.key)
+      const { container, seen } = scalarParentAt(depth)
+      checkScalar(seen, field.key, K_SCALAR_HEADING)
+      startBlockquote(container, field.key)
+      return
+    }
+
+    if (field && field.block) {
+      const { container, seen } = scalarParentAt(depth)
+      checkScalar(seen, field.key, K_SCALAR_HEADING)
+      startBlock(container, field.key, field.block)
       return
     }
 
@@ -256,22 +430,90 @@ export function createParser() {
       return
     }
 
-    throw parseError('Malformed heading')
+    throw new JMDParseError(
+      'malformed_heading',
+      'Malformed heading',
+      lineNo,
+    )
   }
 
   function openObjectScope(depth, key) {
-    const parent = parentObjectAt(depth)
+    const parent = parentScopeAt(depth)
+    const { container, seen } = parentContainerAndSeen(parent)
+    const prior = seen ? seen.get(key) : undefined
+
+    if (prior === K_ARRAY_SIGIL) {
+      throw new JMDParseError(
+        'sigil_conflict',
+        'Repeated heading "' + key + '" mixes [] sigil with bare form',
+        lineNo,
+      )
+    }
+    if (prior === K_SCALAR_BARE || prior === K_SCALAR_HEADING) {
+      throw new JMDParseError(
+        'repeated_scalar_key',
+        'Key "' + key + '" first seen as scalar, then as object heading',
+        lineNo,
+      )
+    }
+    if (prior === K_ARRAY_PROMOTED) {
+      // Third+ occurrence: append a fresh object to the existing array.
+      const arr = container[key]
+      const obj = {}
+      arr.push(obj)
+      stack.push(objectScope(obj, depth))
+      emit('object_start', { key })
+      return
+    }
+    if (prior === K_OBJECT_HEADING) {
+      // §7.4: second occurrence promotes the scalar object to an array.
+      const existing = container[key]
+      const obj = {}
+      const arr = [existing, obj]
+      container[key] = arr
+      if (seen) seen.set(key, K_ARRAY_PROMOTED)
+      stack.push(objectScope(obj, depth))
+      emit('object_start', { key })
+      return
+    }
+    // First occurrence — plain object heading.
     const obj = {}
-    parent[key] = obj
-    stack.push({ kind: 'object', container: obj, depth })
+    container[key] = obj
+    if (seen) seen.set(key, K_OBJECT_HEADING)
+    stack.push(objectScope(obj, depth))
     emit('object_start', { key })
   }
 
   function openArrayScope(depth, key) {
-    const parent = parentObjectAt(depth)
+    const parent = parentScopeAt(depth)
+    const { container, seen } = parentContainerAndSeen(parent)
+    const prior = seen ? seen.get(key) : undefined
+
+    if (prior === K_ARRAY_SIGIL) {
+      throw new JMDParseError(
+        'repeated_explicit_array',
+        'Repeated explicit-array heading "' + key + '"',
+        lineNo,
+      )
+    }
+    if (prior === K_OBJECT_HEADING || prior === K_ARRAY_PROMOTED) {
+      throw new JMDParseError(
+        'sigil_conflict',
+        'Heading "' + key + '" first appeared without [], then with []',
+        lineNo,
+      )
+    }
+    if (prior === K_SCALAR_BARE || prior === K_SCALAR_HEADING) {
+      throw new JMDParseError(
+        'repeated_scalar_key',
+        'Key "' + key + '" first seen as scalar, then as array heading',
+        lineNo,
+      )
+    }
     const arr = []
-    parent[key] = arr
-    stack.push({ kind: 'array', container: arr, depth, currentItem: null })
+    container[key] = arr
+    if (seen) seen.set(key, K_ARRAY_SIGIL)
+    stack.push(arrayScope(arr, depth))
     emit('array_start', { key })
   }
 
@@ -280,25 +522,84 @@ export function createParser() {
     // enclosing array scope.
     const top = stack[stack.length - 1]
     if (!top || top.kind !== 'array') {
-      throw parseError('Anonymous sub-array outside array scope')
+      throw new JMDParseError(
+        'malformed_heading',
+        'Anonymous sub-array outside array scope',
+        lineNo,
+      )
     }
     closeItem(top)
     const inner = []
     top.container.push(inner)
-    stack.push({ kind: 'array', container: inner, depth, currentItem: null })
+    stack.push(arrayScope(inner, depth))
     emit('array_start', {})
   }
 
-  function parentObjectAt(depth) {
+  // Find the scope that should receive a scalar field at the given heading
+  // depth, returning its container plus the `seen` map for §7.4 tracking.
+  function scalarParentAt(depth) {
     for (let i = stack.length - 1; i >= 0; i--) {
       const s = stack[i]
-      if (s.depth < depth) {
-        if (s.kind === 'object') return s.container
-        if (s.kind === 'array' && s.currentItem) return s.currentItem
-        throw parseError('Field has no enclosing object scope')
+      if (s.depth >= depth) continue
+      if (s.kind === 'object') {
+        return { container: s.container, seen: s.seen }
       }
+      if (s.kind === 'array' && s.currentItem) {
+        // Per-item object: track its own seen-keys so repeated keys on
+        // one item still surface as repeated_scalar_key.
+        if (s.itemSeen === null) s.itemSeen = new Map()
+        return { container: s.currentItem, seen: s.itemSeen }
+      }
+      throw new JMDParseError(
+        'malformed_field',
+        'Field has no enclosing object scope',
+        lineNo,
+      )
+    }
+    throw new JMDParseError(
+      'malformed_field',
+      'No enclosing scope for depth ' + depth,
+      lineNo,
+    )
+  }
+
+  function parentScopeAt(depth) {
+    for (let i = stack.length - 1; i >= 0; i--) {
+      if (stack[i].depth < depth) return stack[i]
+    }
+    throw new JMDParseError(
+      'malformed_heading',
+      'No enclosing scope for depth ' + depth,
+      lineNo,
+    )
+  }
+
+  function parentContainerAndSeen(scope) {
+    if (scope.kind === 'object') {
+      return { container: scope.container, seen: scope.seen }
+    }
+    if (scope.kind === 'array' && scope.currentItem) {
+      if (scope.itemSeen === null) scope.itemSeen = new Map()
+      return { container: scope.currentItem, seen: scope.itemSeen }
     }
-    throw parseError('No enclosing scope for depth ' + depth)
+    throw new JMDParseError(
+      'malformed_heading',
+      'Heading inside an array scope needs an active item',
+      lineNo,
+    )
+  }
+
+  function checkScalar(seen, key, kind) {
+    if (!seen) return
+    const prior = seen.get(key)
+    if (prior !== undefined) {
+      throw new JMDParseError(
+        'repeated_scalar_key',
+        'Key "' + key + '" repeated',
+        lineNo,
+      )
+    }
+    seen.set(key, kind)
   }
 
   function popToDepth(targetDepth) {
@@ -321,6 +622,7 @@ export function createParser() {
     if (arrayScope.currentItem !== null) {
       emit('item_end')
       arrayScope.currentItem = null
+      arrayScope.itemSeen = null
     }
   }
 
@@ -334,8 +636,18 @@ export function createParser() {
       const bag = parent.kind === 'array' && parent.currentItem
         ? parent.currentItem
         : parent.container
+      if (Array.isArray(bag)) {
+        // Promoted array: search every parent dict in the bag for the
+        // container reference (rare path; small N).
+        continue
+      }
       for (const k of Object.keys(bag)) {
         if (bag[k] === scope.container) return k
+        // §7.4 promoted: parent[k] may be an array containing scope.container.
+        if (Array.isArray(bag[k])
+            && bag[k][bag[k].length - 1] === scope.container) {
+          return k
+        }
       }
     }
     return undefined
@@ -345,15 +657,39 @@ export function createParser() {
 
   function onField(line) {
     const f = parseField(line)
-    if (!f) throw parseError('Malformed field line')
+    if (!f) {
+      throw new JMDParseError(
+        'malformed_field',
+        'Malformed field line',
+        lineNo,
+      )
+    }
     const top = stack[stack.length - 1]
-    const target = top.kind === 'object'
-      ? top.container
-      : (top.currentItem || throwHere('Bare field inside array scope without an item'))
+    let target, seen
+    if (top.kind === 'object') {
+      target = top.container
+      seen = top.seen
+    } else {
+      if (!top.currentItem) {
+        throw new JMDParseError(
+          'malformed_field',
+          'Bare field inside array scope without an item',
+          lineNo,
+        )
+      }
+      target = top.currentItem
+      if (top.itemSeen === null) top.itemSeen = new Map()
+      seen = top.itemSeen
+    }
+    checkScalar(seen, f.key, K_SCALAR_BARE)
     if (f.empty) {
       startBlockquote(target, f.key)
       return
     }
+    if (f.block) {
+      startBlock(target, f.key, f.block)
+      return
+    }
     target[f.key] = f.value
     emit('field', { key: f.key, value: f.value })
   }
@@ -377,7 +713,11 @@ export function createParser() {
     }
     const targetIdx = sameDepthIdx !== -1 ? sameDepthIdx : parentDepthIdx
     if (targetIdx === -1) {
-      throw parseError('Depth-qualified item has no matching array scope')
+      throw new JMDParseError(
+        'malformed_heading',
+        'Depth-qualified item has no matching array scope',
+        lineNo,
+      )
     }
     // Close any scopes nested inside the target array.
     while (stack.length - 1 > targetIdx) popScope()
@@ -387,7 +727,13 @@ export function createParser() {
 
   function onItem(line) {
     const top = stack[stack.length - 1]
-    if (top.kind !== 'array') throw parseError('Array item outside array scope')
+    if (top.kind !== 'array') {
+      throw new JMDParseError(
+        'malformed_item',
+        'Array item outside array scope',
+        lineNo,
+      )
+    }
 
     closeItem(top)
     const rest = line === '-' ? '' : line.slice(2)
@@ -396,6 +742,7 @@ export function createParser() {
       const item = {}
       top.container.push(item)
       top.currentItem = item
+      top.itemSeen = new Map()
       emit('item_start')
       return
     }
@@ -405,9 +752,13 @@ export function createParser() {
       const item = {}
       top.container.push(item)
       top.currentItem = item
+      top.itemSeen = new Map()
+      top.itemSeen.set(f.key, K_SCALAR_BARE)
       emit('item_start')
       if (f.empty) {
         startBlockquote(item, f.key)
+      } else if (f.block) {
+        startBlock(item, f.key, f.block)
       } else {
         item[f.key] = f.value
         emit('field', { key: f.key, value: f.value })
@@ -418,6 +769,7 @@ export function createParser() {
     const value = parseScalar(rest)
     top.container.push(value)
     top.currentItem = null
+    top.itemSeen = null
     emit('item_value', { value })
   }
 
@@ -425,14 +777,30 @@ export function createParser() {
     const content = line.replace(/^\s+/, '')
     const top = stack[stack.length - 1]
     if (top.kind !== 'array' || !top.currentItem) {
-      throw parseError('Indented continuation without an active array item')
+      throw new JMDParseError(
+        'malformed_field',
+        'Indented continuation without an active array item',
+        lineNo,
+      )
     }
     const f = parseField(content)
-    if (!f) throw parseError('Malformed indented continuation')
+    if (!f) {
+      throw new JMDParseError(
+        'malformed_field',
+        'Malformed indented continuation',
+        lineNo,
+      )
+    }
+    if (top.itemSeen === null) top.itemSeen = new Map()
+    checkScalar(top.itemSeen, f.key, K_SCALAR_BARE)
     if (f.empty) {
       startBlockquote(top.currentItem, f.key)
       return
     }
+    if (f.block) {
+      startBlock(top.currentItem, f.key, f.block)
+      return
+    }
     top.currentItem[f.key] = f.value
     emit('field', { key: f.key, value: f.value })
   }
@@ -440,24 +808,20 @@ export function createParser() {
   // --- Finalization --------------------------------------------------------
 
   function finish() {
+    if (block !== null) commitBlock()
     if (bq !== null) commitBlockquote()
     if (!seenRoot) {
-      throw parseError('Document contained no root heading')
+      throw new JMDParseError(
+        'malformed_root',
+        'Document contained no root heading',
+        lineNo,
+      )
     }
     while (stack.length > 0) popScope()
     emit('document_end')
     return drain()
   }
 
-  // --- Errors --------------------------------------------------------------
-
-  function parseError(msg) {
-    const err = new Error(msg + ' (line ' + lineNo + ')')
-    err.line = lineNo
-    return err
-  }
-  function throwHere(msg) { throw parseError(msg) }
-
   // --- Public surface ------------------------------------------------------
 
   function parse(text) {
@@ -467,6 +831,8 @@ export function createParser() {
     if (lines.length && lines[lines.length - 1] === '') lines.pop()
     for (const line of lines) processLine(line)
     finish()
+    // frontmatterStarted is internal — keep the public shape unchanged.
+    void frontmatterStarted
     return { mode, label, frontmatter, value: root }
   }
 

package/src/serializer.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // JMD serializer.
 //
 // Two surfaces over one implementation:
@@ -19,16 +20,39 @@ import { serializeScalar, serializeKey } from './value.js'
 
 export function serialize(value, label = 'Document', frontmatter = null) {
   const lines = []
-  emitDocument(value, label, frontmatter, lines)
+  emitDocument(value, validateLabel(label), frontmatter, lines)
   return lines.join('\n')
 }
 
 export function* serializeLines(value, label = 'Document', frontmatter = null) {
   const lines = []
-  emitDocument(value, label, frontmatter, lines)
+  emitDocument(value, validateLabel(label), frontmatter, lines)
   for (const ln of lines) yield ln + '\n'
 }
 
+// D11: validate and normalize a root-heading label. Newline characters
+// would split the heading across lines and corrupt the document, so we
+// reject them outright; surrounding whitespace is silently stripped, but
+// a leading mode prefix (`- `, `? `, `! `) is preserved intact.
+export function validateLabel(label) {
+  if (typeof label !== 'string') {
+    throw new TypeError('Label must be a string')
+  }
+  if (label.includes('\n') || label.includes('\r')) {
+    throw new RangeError(
+      'JMD root labels must not contain newline characters; got '
+      + JSON.stringify(label),
+    )
+  }
+  let s = label.replace(/^\s+/, '')
+  if (s.length >= 2
+      && (s[0] === '-' || s[0] === '?' || s[0] === '!')
+      && s[1] === ' ') {
+    return s.slice(0, 2) + s.slice(2).replace(/\s+$/, '')
+  }
+  return s.replace(/\s+$/, '')
+}
+
 // Mode markers attach directly to `#` in the root heading: `#- Order`,
 // `#? Order`, `#! Order`. Callers pass the mark as a `- `, `? ` or `! `
 // prefix on `label`; the serializer attaches it to `#` without a space
@@ -45,8 +69,18 @@ function splitLabel(label) {
 function emitDocument(value, label, frontmatter, lines) {
   if (frontmatter && Object.keys(frontmatter).length > 0) {
     for (const [k, v] of Object.entries(frontmatter)) {
-      if (v === true) lines.push(serializeKey(k))
-      else lines.push(serializeKey(k) + ': ' + serializeScalar(v))
+      const qk = serializeKey(k)
+      if (v === true) {
+        lines.push(qk)
+      } else if (typeof v === 'string' && v.includes('\n')) {
+        // D12: multi-line frontmatter values go in the blockquote form,
+        // matching the body serializer's handling of multi-line scalars
+        // (§9.1) so the value round-trips through frontmatter parsing.
+        lines.push(qk + ':')
+        writeMultiline(v, lines)
+      } else {
+        lines.push(qk + ': ' + serializeScalar(v))
+      }
     }
     lines.push('')
   }
@@ -133,24 +167,36 @@ function writeArrayItems(lst, lines, depth) {
     return
   }
 
-  // Heterogeneous array.
+  // Heterogeneous array — items mixing scalars, dicts, sub-arrays.
   //
-  // The C-accelerated Python reference does not insert thematic breaks
-  // inside a heterogeneous array — items simply follow one another. We
-  // match that form byte-for-byte.
+  // After any item that opens a sub-scope (a nested list, or a dict
+  // with nested fields), the NEXT item needs an explicit depth-qualified
+  // heading `## - ...` (§8.6a same-depth form) so the parser pops out
+  // of the sub-scope and attaches the item to *this* array. The
+  // qualifier uses the array's own scope depth — items[] opened by
+  // `## items[]` at depth 2 take a `## - ...` prefix.
+  const qualifier = heading(depth)
+  let needsQualifier = false
   for (const item of lst) {
     if (isPlainObject(item)) {
-      writeDictItem(item, lines, depth, false)
+      const hasNested = Object.values(item).some(isNested)
+      writeDictItem(item, lines, depth, false, needsQualifier ? qualifier : '')
+      needsQualifier = hasNested
     } else if (Array.isArray(item)) {
+      // Anonymous sub-array still opens at depth+1; only the item-
+      // qualifier shrinks to same-depth.
       lines.push(heading(depth + 1) + '[]')
       writeArrayItems(item, lines, depth + 1)
+      needsQualifier = true
     } else {
-      lines.push('- ' + serializeScalar(item))
+      const pfx = needsQualifier ? qualifier : ''
+      lines.push(pfx + '- ' + serializeScalar(item))
+      needsQualifier = false
     }
   }
 }
 
-function writeDictItem(item, lines, depth, separatorNeeded) {
+function writeDictItem(item, lines, depth, separatorNeeded, qualifierPrefix = '') {
   const scalarFields = []
   const nestedFields = []
   for (const [k, v] of Object.entries(item)) {
@@ -167,14 +213,14 @@ function writeDictItem(item, lines, depth, separatorNeeded) {
   }
 
   if (scalarFields.length === 0) {
-    lines.push('-')
+    lines.push(qualifierPrefix + '-')
   } else {
     let first = true
     for (const [k, v] of scalarFields) {
       const sv = serializeScalar(v)
       const qk = serializeKey(k)
       if (first) {
-        lines.push('- ' + qk + ': ' + sv)
+        lines.push(qualifierPrefix + '- ' + qk + ': ' + sv)
         first = false
       } else {
         lines.push('  ' + qk + ': ' + sv)

package/src/value.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Scalar values and keys.
 //
 // Parsing and serialization of the smallest JMD units: scalar values
@@ -89,8 +90,14 @@ export function serializeKey(key) {
   return JSON.stringify(key)
 }
 
-// Parse `key: value` or `key:` (empty value).
-// Returns { key, value } or { key, empty: true } or null.
+// Parse `key: value`, `key:` (empty / blockquote-opening), or
+// `key: |` / `key: >` (block-scalar opening, §5.2).
+// Returns one of:
+//   { key, value }       — scalar field
+//   { key, empty: true } — empty value, opens a blockquote field
+//   { key, block: '|' }  — literal block scalar
+//   { key, block: '>' }  — folded block scalar
+// or null if the line is not a field.
 export function parseField(line) {
   const pk = parseKey(line)
   if (!pk) return null
@@ -102,5 +109,8 @@ export function parseField(line) {
     return { key: pk.key, empty: true }
   }
   if (after.charCodeAt(0) !== 32 /* space */) return null
-  return { key: pk.key, value: parseScalar(after.slice(1)) }
+  const value = after.slice(1)
+  if (value === '|') return { key: pk.key, block: '|' }
+  if (value === '>') return { key: pk.key, block: '>' }
+  return { key: pk.key, value: parseScalar(value) }
 }