@danmoisan/drm-copilot-mcp 1.0.21 → 1.0.23

package/resources/claude-customizations/.claude/lib/bash/parallel-yaml-emit.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+# parallel-yaml-emit.sh: structural half of the restricted block-YAML parser.
+# Walks the indentation of the frontmatter body lines produced by
+# parallel-yaml-scan.sh and populates that module's node table in document
+# order. Sourcing this file also sources the scanning half, so a consumer needs
+# only this one source line.
+#
+# Algorithm. A stack of open containers is kept, each carrying the indent
+# column its children sit at, its rendered path, whether it is a mapping or a
+# sequence, and how many children it has taken. A `key:` line with no inline
+# value opens a pending node whose kind is not yet known: the next content line
+# decides it, becoming a mapping or sequence when it is indented deeper, and
+# leaving the pending node a null scalar when it is not. That one-line lookahead
+# is the whole of the parser's ambiguity handling.
+#
+# Failure modes are the two the scanning half defines. A malformed line sets
+# YP_STATUS=yaml_error and is rendered by the caller through the M1 message; a
+# construct that is valid YAML but outside the subset sets
+# YP_STATUS=out_of_subset and makes the caller refuse to answer rather than
+# risk disagreeing with the Python authority.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because the node-table and status globals this
+# module writes -- YP_TYPE, YP_COUNT, YP_STATUS -- are declared in
+# parallel-yaml-scan.sh and read by parallel-items-validate.sh and
+# parallel-manifest-validate.sh, which shellcheck analyses as separate files.
+
+# Resolve this file's own directory so the scanning half sources regardless of
+# the caller's working directory.
+YP_EMIT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-yaml-scan.sh
+# shellcheck disable=SC1091
+source "$YP_EMIT_DIR/parallel-yaml-scan.sh"
+
+# Path label for the document root in key-scoped errors.
+YP_ROOT_LABEL="<root>"
+
+# Open-container stack, parallel arrays indexed by depth.
+YP_STACK_INDENT=()
+YP_STACK_PATH=()
+YP_STACK_KIND=()
+YP_STACK_COUNT=()
+
+# The pending node opened by a `key:` or bare `-` line, if any.
+YP_PENDING_PATH=""
+YP_PENDING_INDENT=-1
+YP_PENDING_ACTIVE=0
+
+yp_stack_reset() {
+	# Clear the container stack and the pending-node slot.
+	YP_STACK_INDENT=()
+	YP_STACK_PATH=()
+	YP_STACK_KIND=()
+	YP_STACK_COUNT=()
+	YP_PENDING_PATH=""
+	YP_PENDING_INDENT=-1
+	YP_PENDING_ACTIVE=0
+}
+
+yp_stack_push() {
+	# Push one open container onto the stack.
+	#
+	# Args: $1 = indent column of the container's children, $2 = rendered path,
+	# $3 = kind (map or seq).
+	YP_STACK_INDENT+=("$1")
+	YP_STACK_PATH+=("$2")
+	YP_STACK_KIND+=("$3")
+	YP_STACK_COUNT+=(0)
+}
+
+yp_stack_depth() {
+	# Echo the number of open containers.
+	printf '%s' "${#YP_STACK_INDENT[@]}"
+}
+
+yp_stack_pop() {
+	# Discard the innermost open container by truncating every stack array.
+	local keep=$((${#YP_STACK_INDENT[@]} - 1))
+	((keep >= 0)) || return 0
+	YP_STACK_INDENT=("${YP_STACK_INDENT[@]:0:keep}")
+	YP_STACK_PATH=("${YP_STACK_PATH[@]:0:keep}")
+	YP_STACK_KIND=("${YP_STACK_KIND[@]:0:keep}")
+	YP_STACK_COUNT=("${YP_STACK_COUNT[@]:0:keep}")
+}
+
+yp_stack_bump() {
+	# Increment the innermost container's child count and mirror it into the
+	# node table so yp_count_of reports sequence lengths and key counts.
+	local last=$((${#YP_STACK_INDENT[@]} - 1))
+	((last >= 0)) || return 0
+	YP_STACK_COUNT[last]=$((YP_STACK_COUNT[last] + 1))
+	local path="${YP_STACK_PATH[last]}"
+	if [[ -n $path ]]; then
+		YP_COUNT["$path"]=${YP_STACK_COUNT[last]}
+	fi
+}
+
+yp_render_child_path() {
+	# Echo the path of a mapping key inside a parent container.
+	#
+	# Args: $1 = parent path (empty at the document root), $2 = key name.
+	if [[ -z $1 ]]; then
+		printf '%s' "$2"
+	else
+		printf '%s.%s' "$1" "$2"
+	fi
+}
+
+yp_render_parent_label() {
+	# Echo the path label Python uses for the mapping that owns a key.
+	#
+	# Args: $1 = parent path. The document root renders as `<root>` so
+	# prohibited-key errors reproduce the Python wording exactly.
+	if [[ -z $1 ]]; then
+		printf '%s' "$YP_ROOT_LABEL"
+	else
+		printf '%s' "$1"
+	fi
+}
+
+yp_open_pending() {
+	# Mark a node as awaiting the next line to decide its kind.
+	#
+	# Args: $1 = node path, $2 = indent column of the line that opened it.
+	YP_PENDING_PATH="$1"
+	YP_PENDING_INDENT="$2"
+	YP_PENDING_ACTIVE=1
+}
+
+yp_resolve_pending() {
+	# Decide the kind of a pending node using the next content line.
+	#
+	# Args: $1 = indent of the next content line, $2 = 1 when that line is a
+	# sequence entry. Returns 0 always; the pending slot is cleared.
+	local indent="$1" is_seq="$2"
+	((YP_PENDING_ACTIVE == 1)) || return 0
+	# A deeper line, or a sequence entry at the same column, opens a container;
+	# anything else means the key carried no value and reads as null.
+	if ((indent > YP_PENDING_INDENT)) || ((indent == YP_PENDING_INDENT && is_seq == 1)); then
+		local kind="map"
+		((is_seq == 1)) && kind="seq"
+		YP_TYPE["$YP_PENDING_PATH"]="$kind"
+		YP_COUNT["$YP_PENDING_PATH"]=0
+		yp_stack_push "$indent" "$YP_PENDING_PATH" "$kind"
+	else
+		YP_TYPE["$YP_PENDING_PATH"]="null"
+	fi
+	YP_PENDING_ACTIVE=0
+	YP_PENDING_PATH=""
+	YP_PENDING_INDENT=-1
+}
+
+yp_emit_map_entry() {
+	# Parse one `key: value` or `key:` line into the node table.
+	#
+	# Args: $1 = owning mapping path (empty at the root), $2 = line content
+	# with indentation stripped, $3 = indent column of the line.
+	# Returns 0 on success, 1 with YP_STATUS set on a malformed or refused line.
+	local parent="$1" content="$2" indent="$3"
+	local key rest
+	if [[ $content == *": "* ]]; then
+		key=${content%%": "*}
+		rest=$(yp_trim "${content#*": "}")
+	elif [[ $content == *":" ]]; then
+		key=${content%":"}
+		rest=""
+	else
+		yp_yaml_error "line is neither a mapping entry nor a sequence entry: $content"
+		return 1
+	fi
+	# Keys in a machine-authored manifest are bare identifiers; a quoted or
+	# otherwise exotic key is refused rather than guessed at.
+	if [[ ! $key =~ ^[A-Za-z_][A-Za-z0-9_-]*$ ]]; then
+		yp_reject "mapping keys must be bare identifiers; found: $key"
+		return 1
+	fi
+	local path parent_label
+	path=$(yp_render_child_path "$parent" "$key")
+	parent_label=$(yp_render_parent_label "$parent")
+
+	# An inline empty flow collection is a complete container; an empty value
+	# defers the decision to the next line; anything else is a scalar.
+	if [[ $rest == "[]" ]]; then
+		yp_node_add "$path" "seq" "" "$parent_label" "$key"
+	elif [[ $rest == "{}" ]]; then
+		yp_node_add "$path" "map" "" "$parent_label" "$key"
+	elif [[ -z $rest && $content == *":" ]]; then
+		yp_node_add "$path" "null" "" "$parent_label" "$key"
+		yp_open_pending "$path" "$indent"
+	else
+		yp_classify_scalar "$rest" || return 1
+		yp_node_add "$path" "$YP_SCALAR_TYPE" "$YP_SCALAR_VALUE" "$parent_label" "$key"
+	fi
+	yp_stack_bump
+	return 0
+}
+
+yp_emit_seq_entry() {
+	# Parse one `- ...` line into the node table.
+	#
+	# Args: $1 = owning sequence path, $2 = the sequence index to use, $3 = the
+	# text after the dash with surrounding whitespace trimmed, $4 = indent
+	# column of the dash. Returns 0 on success, 1 with YP_STATUS set otherwise.
+	local parent="$1" index="$2" rest="$3" indent="$4"
+	local path="${parent}[${index}]"
+
+	# A bare dash defers to the next line; a `key: value` payload opens a
+	# compact mapping whose entries sit two columns right of the dash; anything
+	# else is a scalar element.
+	if [[ -z $rest ]]; then
+		yp_node_add "$path" "null" "" "" ""
+		yp_open_pending "$path" "$indent"
+		return 0
+	fi
+	if [[ $rest == *": "* || $rest == *":" ]]; then
+		yp_node_add "$path" "map" "" "" ""
+		yp_stack_push $((indent + 2)) "$path" "map"
+		yp_emit_map_entry "$path" "$rest" $((indent + 2)) || return 1
+		return 0
+	fi
+	yp_classify_scalar "$rest" || return 1
+	yp_node_add "$path" "$YP_SCALAR_TYPE" "$YP_SCALAR_VALUE" "" ""
+	return 0
+}
+
+yp_scan_line_guards() {
+	# Reject the line-level constructs the subset does not model.
+	#
+	# Args: $1 = the raw line, $2 = the line with indentation stripped.
+	# Returns 0 when the line may be parsed, 1 with YP_STATUS set otherwise.
+	local line="$1" content="$2"
+	if [[ $line == *$'\t'* ]]; then
+		yp_yaml_error "tab characters are not permitted in YAML indentation"
+		return 1
+	fi
+	if [[ $content == *' #'* ]]; then
+		yp_reject "trailing comments are outside the subset: $content"
+		return 1
+	fi
+	if [[ $content == '---' || $content == '...' ]]; then
+		yp_reject "multi-document streams are outside the subset"
+		return 1
+	fi
+	return 0
+}
+
+yp_close_deeper_containers() {
+	# Pop every open container whose children sit right of the given column.
+	#
+	# Args: $1 = the current line's indent column.
+	local indent="$1" top
+	# Unwinding stops at the first container whose child column is at or left
+	# of this line, which is the container the line belongs to.
+	while ((${#YP_STACK_INDENT[@]} > 0)); do
+		top=$((${#YP_STACK_INDENT[@]} - 1))
+		((indent < YP_STACK_INDENT[top])) || break
+		yp_stack_pop
+	done
+}
+
+yp_parse_body() {
+	# Parse YP_BODY_LINES into the node table.
+	#
+	# Returns 0 when YP_STATUS is ok. Sets YP_STATUS to not_a_mapping when the
+	# body is empty or its root is a sequence, and to yaml_error or
+	# out_of_subset for the failure modes the module header documents.
+	yp_reset
+	yp_stack_reset
+	local root_seen=0
+	local total=${#YP_BODY_LINES[@]}
+	local index line content indent is_seq rest depth seq_index
+
+	# Walk every body line, resolving the pending node from the previous line
+	# before deciding what the current line contributes.
+	for ((index = 0; index < total; index++)); do
+		line="${YP_BODY_LINES[index]}"
+		[[ -n $(yp_trim "$line") ]] || continue
+		content=${line#"${line%%[![:space:]]*}"}
+		[[ $content == '#'* ]] && continue
+		yp_scan_line_guards "$line" "$content" || return 1
+		indent=$((${#line} - ${#content}))
+		is_seq=0
+		[[ $content == "-" || $content == "- "* ]] && is_seq=1
+
+		yp_resolve_pending "$indent" "$is_seq"
+
+		# The first content line fixes the document's root kind; a sequence
+		# root is reported as not-a-mapping rather than parsed.
+		if ((root_seen == 0)); then
+			root_seen=1
+			if ((is_seq == 1)); then
+				YP_STATUS="not_a_mapping"
+				return 1
+			fi
+			((${#YP_STACK_INDENT[@]} > 0)) || yp_stack_push "$indent" "" "map"
+		fi
+
+		yp_close_deeper_containers "$indent"
+		if ((${#YP_STACK_INDENT[@]} == 0)); then
+			yp_yaml_error "indentation closes the document root: $content"
+			return 1
+		fi
+		depth=$((${#YP_STACK_INDENT[@]} - 1))
+		if ((indent != YP_STACK_INDENT[depth])); then
+			yp_yaml_error "inconsistent indentation at column $indent: $content"
+			return 1
+		fi
+
+		# Route the line against the container it belongs to; a mismatch means
+		# the document mixes a sequence entry into a mapping or the reverse.
+		if ((is_seq == 1)); then
+			if [[ ${YP_STACK_KIND[depth]} != seq ]]; then
+				yp_yaml_error "sequence entry inside a mapping: $content"
+				return 1
+			fi
+			rest=$(yp_trim "${content#-}")
+			seq_index="${YP_STACK_COUNT[depth]}"
+			yp_stack_bump
+			yp_emit_seq_entry "${YP_STACK_PATH[depth]}" "$seq_index" "$rest" "$indent" || return 1
+		else
+			if [[ ${YP_STACK_KIND[depth]} != map ]]; then
+				yp_yaml_error "mapping entry inside a sequence: $content"
+				return 1
+			fi
+			yp_emit_map_entry "${YP_STACK_PATH[depth]}" "$content" "$indent" || return 1
+		fi
+	done
+
+	# A pending node left open at end of input carried no value.
+	if ((YP_PENDING_ACTIVE == 1)); then
+		YP_TYPE["$YP_PENDING_PATH"]="null"
+		YP_PENDING_ACTIVE=0
+	fi
+	if ((root_seen == 0)); then
+		YP_STATUS="not_a_mapping"
+		return 1
+	fi
+	YP_STATUS="ok"
+	return 0
+}

package/resources/claude-customizations/.claude/lib/bash/parallel-yaml-scan.sh

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+# parallel-yaml-scan.sh: scanning half of the hand-written parser for the
+# restricted block-YAML subset that a machine-authored parallel-run manifest is
+# written in. It owns line splitting, frontmatter fence extraction, scalar
+# lexing, and the node-table storage and accessors; the structural half that
+# walks indentation and populates the table lives in parallel-yaml-emit.sh,
+# which sources this file. The pair exists so the manifest validator can run in
+# a destination workspace that has no Python, no yq, and no Node; it is
+# deliberately NOT a general YAML implementation and fails closed on every
+# construct outside the subset.
+#
+# The module is split across two files because the combined implementation
+# exceeds the 500-line ceiling in .claude/rules/general-code-change.md.
+#
+# Accepted subset:
+#   - block mappings `key: value` and `key:` followed by an indented block,
+#   - block sequences `- scalar`, `- key: value` (compact mapping), and `-`
+#     followed by an indented block,
+#   - two-space indentation steps, spaces only,
+#   - empty flow collections `[]` and `{}`,
+#   - scalars: null (`~`, `null`, empty), the YAML 1.1 boolean words, decimal
+#     integers matching `[-+]?(0|[1-9][0-9]*)`, single-quoted and double-quoted
+#     strings without escape sequences, and plain strings,
+#   - full-line `#` comments and blank lines.
+#
+# Rejected fail-closed (YP_STATUS=out_of_subset): non-empty flow collections,
+# anchors, aliases, tags, block scalars (`|`, `>`), floats, unquoted dates and
+# timestamps, `.inf`/`.nan`, escape sequences inside double-quoted scalars,
+# trailing comments, and multi-document streams. Rejecting these is the point:
+# silently mis-parsing one would produce a validator verdict that disagrees with
+# the Python authority, which is worse than refusing to answer.
+#
+# Reported as a YAML error (YP_STATUS=yaml_error): unterminated quotes, tab
+# indentation, misaligned indentation, and lines that are neither a mapping
+# entry nor a sequence entry. The manifest validator renders these through the
+# M1 "frontmatter is not valid YAML" message, whose text is a declared
+# divergence class scoped to its prefix.
+#
+# Output model. A successful parse populates a node table addressed by path:
+# `parallel`, `items`, `items[0]`, `items[0].blast_radius.paths[1]`. Document
+# order is preserved in the indexed array YP_ORDER; the associative arrays are
+# used for lookup only and are never iterated, so no hash order reaches output.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because this module is the storage half of a
+# two-file library: the node table and the parse-status globals declared below
+# are written here and read by parallel-yaml-emit.sh, parallel-items-validate.sh,
+# and parallel-manifest-validate.sh, which shellcheck analyses as separate
+# files and therefore cannot see the use.
+
+# Node paths in document order. Every ordered traversal walks this array.
+YP_ORDER=()
+
+# Lexical type per path: map, seq, null, bool, int, float, or str.
+declare -gA YP_TYPE=()
+
+# Decoded scalar value per path; empty string for container nodes.
+declare -gA YP_VALUE=()
+
+# Mapping-key name per path, for nodes that came from a `key:` entry.
+declare -gA YP_KEY=()
+
+# Rendered path of the mapping that owns each key node; `<root>` at the top.
+declare -gA YP_PARENT=()
+
+# Child count per container path: sequence length or mapping key count.
+declare -gA YP_COUNT=()
+
+# Parse outcome: ok, not_a_mapping, yaml_error, or out_of_subset.
+YP_STATUS="ok"
+
+# Human-readable detail for a yaml_error or out_of_subset outcome.
+YP_DETAIL=""
+
+# Source lines produced by yp_split_lines.
+YP_LINES=()
+
+# Frontmatter body lines produced by yp_extract_frontmatter_body.
+YP_BODY_LINES=()
+
+# The single M1 error produced by a failed fence extraction.
+YP_FENCE_ERROR=""
+
+# Scratch outputs of yp_classify_scalar.
+YP_SCALAR_TYPE=""
+YP_SCALAR_VALUE=""
+
+# The fence line that opens and closes a frontmatter block.
+YP_FENCE="---"
+
+yp_trim() {
+	# Echo a string with leading and trailing whitespace removed.
+	#
+	# Args: $1 = the raw string. Mirrors Python's str.strip() for the ASCII
+	# whitespace the manifest subset can contain.
+	local value="$1"
+	value=${value#"${value%%[![:space:]]*}"}
+	value=${value%"${value##*[![:space:]]}"}
+	printf '%s' "$value"
+}
+
+yp_split_lines() {
+	# Populate YP_LINES by splitting text on any of the three line terminators.
+	#
+	# The CRLF replacement runs first so a carriage-return/line-feed pair is
+	# consumed as one terminator rather than as a CR followed by an empty line,
+	# matching the ordered alternation in the Python module's regex.
+	#
+	# Args: $1 = raw document text.
+	local text="$1"
+	text=${text//$'\r\n'/$'\n'}
+	text=${text//$'\r'/$'\n'}
+	YP_LINES=()
+	local line
+	# A here-string appends one newline, so a text that already ends in a
+	# terminator yields the same trailing empty element Python's split does.
+	while IFS= read -r line; do
+		YP_LINES+=("$line")
+	done <<<"$text"
+}
+
+yp_extract_frontmatter_body() {
+	# Populate YP_BODY_LINES with the leading frontmatter block (invariant M1).
+	#
+	# Args: $1 = raw document text.
+	# Returns 0 on success. On failure returns 1 and sets YP_FENCE_ERROR to the
+	# single M1 error string, using the caller-supplied context prefix in $2.
+	local text="$1" context="$2"
+	yp_split_lines "$text"
+	YP_BODY_LINES=()
+	YP_FENCE_ERROR=""
+	if ((${#YP_LINES[@]} == 0)) || [[ $(yp_trim "${YP_LINES[0]}") != "$YP_FENCE" ]]; then
+		YP_FENCE_ERROR="$context must open with a '$YP_FENCE' frontmatter fence."
+		return 1
+	fi
+	local index
+	# Scan forward for the first closing fence: everything between the two
+	# fences is the body, and no second fence means the block is unterminated.
+	for ((index = 1; index < ${#YP_LINES[@]}; index++)); do
+		if [[ $(yp_trim "${YP_LINES[index]}") == "$YP_FENCE" ]]; then
+			local body_index
+			for ((body_index = 1; body_index < index; body_index++)); do
+				YP_BODY_LINES+=("${YP_LINES[body_index]}")
+			done
+			return 0
+		fi
+	done
+	YP_FENCE_ERROR="$context frontmatter block is not terminated by '$YP_FENCE'."
+	return 1
+}
+
+yp_reject() {
+	# Record an out-of-subset rejection and return 1.
+	#
+	# Args: $1 = detail describing the refused construct.
+	YP_STATUS="out_of_subset"
+	YP_DETAIL="$1"
+	return 1
+}
+
+yp_yaml_error() {
+	# Record a YAML-level parse failure and return 1.
+	#
+	# Args: $1 = detail describing the malformed input.
+	YP_STATUS="yaml_error"
+	YP_DETAIL="$1"
+	return 1
+}
+
+yp_classify_scalar() {
+	# Classify one scalar token, setting YP_SCALAR_TYPE and YP_SCALAR_VALUE.
+	#
+	# Args: $1 = the raw token with surrounding whitespace already trimmed.
+	# Returns 0 when the token is inside the subset, 1 otherwise, with
+	# YP_STATUS and YP_DETAIL set by yp_reject or yp_yaml_error.
+	local raw="$1"
+	YP_SCALAR_TYPE=""
+	YP_SCALAR_VALUE=""
+
+	# Quoted forms are decided first: a quote character makes every later
+	# lexical rule inapplicable, and an unterminated quote is a YAML error
+	# rather than an out-of-subset construct.
+	if [[ $raw == '"'* ]]; then
+		if [[ ${#raw} -lt 2 || $raw != *'"' ]]; then
+			yp_yaml_error "unterminated double-quoted scalar: $raw"
+			return 1
+		fi
+		local body=${raw:1:${#raw}-2}
+		local backslash=$'\\'
+		if [[ $body == *"$backslash"* || $body == *'"'* ]]; then
+			yp_reject "escape sequences inside double-quoted scalars are outside the subset"
+			return 1
+		fi
+		YP_SCALAR_TYPE="str"
+		YP_SCALAR_VALUE="$body"
+		return 0
+	fi
+	if [[ $raw == "'"* ]]; then
+		if [[ ${#raw} -lt 2 || $raw != *"'" ]]; then
+			yp_yaml_error "unterminated single-quoted scalar: $raw"
+			return 1
+		fi
+		local single_body=${raw:1:${#raw}-2}
+		YP_SCALAR_TYPE="str"
+		YP_SCALAR_VALUE="${single_body//\'\'/\'}"
+		return 0
+	fi
+
+	# Structural sigils that introduce constructs this parser does not model.
+	case "$raw" in
+	'&'* | '*'* | '!'* | '|'* | '>'* | '?'* | '%'* | '@'* | '\`'*)
+		yp_reject "value begins with the unsupported YAML indicator: $raw"
+		return 1
+		;;
+	'[]' | '{}') ;;
+	'['* | '{'*)
+		yp_reject "non-empty flow collections are outside the subset: $raw"
+		return 1
+		;;
+	esac
+
+	# Null, then boolean, then integer: the resolver order PyYAML applies to a
+	# plain scalar, restricted to the members the manifest subset admits.
+	case "$raw" in
+	'' | '~' | null | Null | NULL)
+		YP_SCALAR_TYPE="null"
+		YP_SCALAR_VALUE=""
+		return 0
+		;;
+	true | True | TRUE | yes | Yes | YES | on | On | ON)
+		YP_SCALAR_TYPE="bool"
+		YP_SCALAR_VALUE="true"
+		return 0
+		;;
+	false | False | FALSE | no | No | NO | off | Off | OFF)
+		YP_SCALAR_TYPE="bool"
+		YP_SCALAR_VALUE="false"
+		return 0
+		;;
+	.inf | .Inf | .INF | -.inf | -.Inf | -.INF | .nan | .NaN | .NAN)
+		yp_reject "special float values are outside the subset: $raw"
+		return 1
+		;;
+	esac
+
+	if [[ $raw =~ ^[-+]?(0|[1-9][0-9]*)$ ]]; then
+		YP_SCALAR_TYPE="int"
+		YP_SCALAR_VALUE="${raw#+}"
+		return 0
+	fi
+
+	# A token that looks numeric but is not a clean decimal integer is refused
+	# rather than silently demoted to a string, because PyYAML would resolve
+	# many of these to int, float, or datetime.
+	if [[ $raw =~ ^[-+]?[0-9][0-9_]*$ ]] ||
+		[[ $raw =~ ^[-+]?0[xXoObB] ]] ||
+		[[ $raw =~ ^[-+]?[0-9]*\.[0-9]* ]] ||
+		[[ $raw =~ ^[-+]?[0-9]+[eE][-+]?[0-9]+$ ]] ||
+		[[ $raw =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
+		yp_reject "numeric, float, or timestamp scalar outside the subset: $raw"
+		return 1
+	fi
+
+	YP_SCALAR_TYPE="str"
+	YP_SCALAR_VALUE="$raw"
+	return 0
+}
+
+yp_node_add() {
+	# Register one node in the table and append it to the document order.
+	#
+	# Args: $1 = path, $2 = type, $3 = value, $4 = owning-map path or empty,
+	# $5 = mapping key name or empty.
+	local path="$1" type="$2" value="$3" parent="$4" key="$5"
+	YP_ORDER+=("$path")
+	YP_TYPE["$path"]="$type"
+	YP_VALUE["$path"]="$value"
+	if [[ -n $key ]]; then
+		YP_KEY["$path"]="$key"
+		YP_PARENT["$path"]="$parent"
+	fi
+	if [[ $type == map || $type == seq ]]; then
+		YP_COUNT["$path"]=0
+	fi
+}
+
+yp_reset() {
+	# Clear the node table so a fresh parse starts from an empty state.
+	YP_ORDER=()
+	YP_TYPE=()
+	YP_VALUE=()
+	YP_KEY=()
+	YP_PARENT=()
+	YP_COUNT=()
+	YP_STATUS="ok"
+	YP_DETAIL=""
+}
+
+yp_has() {
+	# Return 0 when a path exists in the node table.
+	#
+	# Args: $1 = path.
+	[[ -n ${YP_TYPE["$1"]+set} ]]
+}
+
+yp_type_of() {
+	# Echo the lexical type at a path, or `absent` when the path is unknown.
+	#
+	# Args: $1 = path.
+	if yp_has "$1"; then
+		printf '%s' "${YP_TYPE["$1"]}"
+	else
+		printf 'absent'
+	fi
+}
+
+yp_value_of() {
+	# Echo the decoded scalar value at a path, or the empty string when absent.
+	#
+	# Args: $1 = path.
+	if yp_has "$1"; then
+		printf '%s' "${YP_VALUE["$1"]}"
+	fi
+}
+
+yp_count_of() {
+	# Echo the child count at a container path, or 0 when the path is absent.
+	#
+	# Args: $1 = path.
+	if [[ -n ${YP_COUNT["$1"]+set} ]]; then
+		printf '%s' "${YP_COUNT["$1"]}"
+	else
+		printf '0'
+	fi
+}