Software Requirements Specification

jsonparser

This document was auto-generated by ReqProof on 2026-08-27 05:53:37 UTC. Do not edit manually; regenerate from source requirements.

Table of Contents

1. Introduction

1.1 Purpose

This Software Requirements Specification (SRS) defines the requirements for the jsonparser project. It follows the structure recommended by NPR 7150.2D (NASA Software Engineering Requirements) and IEEE/ISO/IEC 29148.

This document is intended for engineers, reviewers, program managers, and automated verification tools that need to understand and validate the requirements for jsonparser.

1.2 Scope

This document covers all specifications defined in the project.

FieldValue
Project Namejsonparser
Versionnot specified
Default Assurance LevelE
Total Requirements123
Total Components1
Generated2026-08-27 05:53:37 UTC

1.3 Definitions, Acronyms, and Abbreviations

TermDefinition
SRSSoftware Requirements Specification
FRETishFormal Requirements Elicitation Tool language — a restricted natural language for writing unambiguous requirements
LTLLinear Temporal Logic — a formal logic for specifying properties over time
FLIPFormal LTL-based Input Partitioning — NASA algorithm for generating MC/DC test cases from temporal logic formulas
MC/DCModified Condition/Decision Coverage — a structural coverage criterion required by DO-178C for Level A software
CoCoSpecCompositional Contract Specification — a Lustre-based contract language used by Kind2
Kind2 / JKindSMT-based model checkers for Lustre contracts used for realizability and consistency checking
MCPModel Context Protocol — a standardized interface for AI agent tool integration
NPR 7150NASA Procedural Requirements for Software Engineering
DALDesign Assurance Level (A = highest criticality, E = lowest)
DO-178CSoftware Considerations in Airborne Systems and Equipment Certification

1.4 References

DocumentDescription
NPR 7150.2DNASA Procedural Requirements for Software Engineering, NASA Office of the Chief Engineer, 2020
DO-178C / ED-12CSoftware Considerations in Airborne Systems and Equipment Certification, RTCA/EUROCAE, 2011
ISO/IEC/IEEE 29148:2018Systems and software engineering — Life cycle processes — Requirements engineering
Giannakopoulou et al.Formal Requirements Elicitation with FRET, RLSS 2020 (NASA Ames)
Mavridou et al.The Ten Lockheed Martin Cyber-Physical Challenges, IEEE S&P 2020

1.5 Overview

This document is organized as follows: Section 2 provides a general description of the product, its context, capabilities, users, constraints, and interface requirements (user interfaces, software component boundaries, and communication protocols). Sections 3 through 4 contain requirements organized hierarchically by specification level, with each level grouping requirements by component and category. Section 5 presents the verification status matrix showing formalization, realizability, and review status for each requirement. Section 6 provides a traceability matrix linking requirements to parent requirements, tests, and implementation artifacts. Section 7 summarizes gap analysis findings. Section 8 contains appendices with variable definitions.

2. General Description

2.1 Product Perspective

This section describes jsonparser in the context of its requirements. The product perspective is derived from the project configuration and the requirements captured in this specification; no product-specific positioning is asserted beyond what the project defines.

Stakeholder Perspectives

The following stakeholder personas describe the key users and their needs. Each stakeholder requirement captures a user story and acceptance criteria that decompose into formal system requirements.

PersonaRequirementDescriptionStory / Need
Go developers consuming dynamic JSON payloads STK-REQ-001 Library users shall retrieve values from JSON byte payloads by specifying a key path without predeclaring Go structs. As a Go developer consuming unpredictable JSON APIs, I want to retrieve nested values by key path without predeclaring structs so that I can process payloads directly from byte slices.
Go developers reading string fields from dynamic JSON payloads STK-REQ-002 Library users shall retrieve string values with JSON escapes and Unicode decoded into Go strings. As a Go developer reading JSON string fields, I want escaped and Unicode content decoded into normal Go strings so that application code does not need to manually unescape payload bytes.
Go developers reading known scalar fields from dynamic JSON payloads STK-REQ-003 Library users shall extract known numeric and boolean JSON values through typed helpers without manual byte parsing or ad-hoc conversions. As a Go developer who knows the expected scalar type of a JSON field, I want typed helper accessors so that I can avoid manual byte parsing and get explicit errors on invalid access.
Go developers traversing dynamic JSON structures STK-REQ-004 Library users shall traverse arrays and objects and extract multiple key paths from one payload without manually walking the JSON structure. As a Go developer inspecting dynamic JSON payloads, I want traversal helpers that iterate arrays and objects and resolve multiple paths in one scan so that I can process payloads without writing custom walkers.
Go developers mutating dynamic JSON payloads in-place STK-REQ-005 Library users shall update or delete addressed JSON values in byte payloads through the experimental mutation helpers with deterministic edge-case behavior. As a Go developer mutating JSON byte payloads, I want experimental helpers that update or delete addressed values with deterministic edge-case behavior so that I can transform payloads without writing my own low-level mutator.
Go developers reading JSON tokens with minimal allocations STK-REQ-006 Library users shall retrieve addressed JSON values as zero-allocation raw strings without JSON unescaping when they intentionally choose the unsafe helper. As a Go developer reading JSON byte payloads, I want an unsafe helper that exposes addressed values as raw strings without unescaping so that I can avoid extra allocations when I explicitly accept the tradeoff.
Go developers converting raw JSON scalar tokens into typed values STK-REQ-007 Library users shall parse raw JSON scalar tokens into Go boolean, integer, float, and decoded string values with deterministic error behavior on malformed input. As a Go developer working with raw JSON scalar tokens, I want Parse helpers that convert boolean, integer, float, and string tokens into Go values with deterministic malformed-input behavior so that I can safely reuse the parser below full document traversal.

2.2 Product Functions

At a high level, jsonparser is organized into the following components, whose detailed functions are specified in Section 3:

Acceptance Criteria by Stakeholder Requirement

STK-REQ-001 (Go developers consuming dynamic JSON payloads):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can request a nested value by path from a JSON byte slice and receive the correct value, not-found result, or parsing error for the addressed input case. test SYS-REQ-001, SYS-REQ-016, SYS-REQ-017, SYS-REQ-018, SYS-REQ-019, SYS-REQ-020, SYS-REQ-021, SYS-REQ-022, SYS-REQ-023, SYS-REQ-024, SYS-REQ-025, SYS-REQ-026, SYS-REQ-027, SYS-REQ-041, SYS-REQ-042, SYS-REQ-043, SYS-REQ-044, SYS-REQ-045, SYS-REQ-046, SYS-REQ-047, SYS-REQ-086, SYS-REQ-087, SYS-REQ-088, SYS-REQ-089, SYS-REQ-114, SYS-REQ-115, SYS-REQ-116

STK-REQ-002 (Go developers reading string fields from dynamic JSON payloads):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can request a string field and receive the correctly decoded Go string, including escaped and Unicode content, or an error when string access is invalid. test SYS-REQ-002, SYS-REQ-071, SYS-REQ-072, SYS-REQ-073, SYS-REQ-074, SYS-REQ-090, SYS-REQ-091, SYS-REQ-092, SYS-REQ-093, SYS-REQ-115, SYS-REQ-116

STK-REQ-003 (Go developers reading known scalar fields from dynamic JSON payloads):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can request an integer-valued field through a typed helper and receive the expected int64 result or an error when integer access is invalid. test SYS-REQ-003, SYS-REQ-075, SYS-REQ-076, SYS-REQ-077, SYS-REQ-078
AC-2 A caller can request a floating-point field through a typed helper and receive the expected float64 result or an error when float access is invalid. test SYS-REQ-004
AC-3 A caller can request a boolean field through a typed helper and receive the expected bool result or an error when boolean access is invalid. test SYS-REQ-005, SYS-REQ-079, SYS-REQ-094, SYS-REQ-095, SYS-REQ-096

STK-REQ-004 (Go developers traversing dynamic JSON structures):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can iterate an addressed JSON array in encounter order, receive no callbacks for a well-formed empty addressed array, and receive an error for malformed or otherwise unusable array input. test SYS-REQ-006, SYS-REQ-028, SYS-REQ-029, SYS-REQ-052, SYS-REQ-053, SYS-REQ-055, SYS-REQ-083, SYS-REQ-112, SYS-REQ-113, SYS-REQ-115, SYS-REQ-116
AC-2 A caller can iterate an addressed JSON object and receive the correct key, value, and value type tuples for well-formed entries, no entries for well-formed empty objects, propagated callback errors, and an error for malformed or otherwise unusable object input. test SYS-REQ-007, SYS-REQ-030, SYS-REQ-031, SYS-REQ-032, SYS-REQ-054, SYS-REQ-084, SYS-REQ-112
AC-3 A caller can request multiple key paths from one payload scan and receive the correct found or missing-path behavior for each requested path. test SYS-REQ-008, SYS-REQ-085, SYS-REQ-097, SYS-REQ-098, SYS-REQ-099

STK-REQ-005 (Go developers mutating dynamic JSON payloads in-place):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can update an existing addressed JSON value or create a supported missing addressed value through Set and receive the expected mutated payload, or a defined error when the requested mutation path is unusable. test SYS-REQ-009, SYS-REQ-051, SYS-REQ-068, SYS-REQ-069, SYS-REQ-070, SYS-REQ-110, SYS-REQ-111, SYS-REQ-115
AC-2 A caller can delete an addressed JSON value through Delete and receive either the expected mutated payload, the unchanged original payload for a missing addressed target in otherwise usable input, or the unchanged original payload for malformed, truncated, or otherwise unusable input, without process crash or panic. test SYS-REQ-010, SYS-REQ-033, SYS-REQ-034, SYS-REQ-035, SYS-REQ-044, SYS-REQ-048, SYS-REQ-049, SYS-REQ-050, SYS-REQ-056, SYS-REQ-100, SYS-REQ-101, SYS-REQ-102

STK-REQ-006 (Go developers reading JSON tokens with minimal allocations):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can retrieve an addressed JSON value through GetUnsafeString and receive the raw bytes as a Go string without JSON unescaping, including the documented lookup-miss behavior from the underlying path lookup. test SYS-REQ-011, SYS-REQ-080, SYS-REQ-081, SYS-REQ-082, SYS-REQ-103, SYS-REQ-104, SYS-REQ-105

STK-REQ-007 (Go developers converting raw JSON scalar tokens into typed values):

CriterionDescriptionVerification MethodDerived Reqs
AC-1 A caller can parse raw boolean tokens through ParseBoolean and receive the expected bool value or the documented malformed-token error. test SYS-REQ-012, SYS-REQ-036, SYS-REQ-057, SYS-REQ-066
AC-2 A caller can parse raw floating-point tokens through ParseFloat and receive the expected float64 value or the documented malformed-token error. test SYS-REQ-013, SYS-REQ-037, SYS-REQ-065
AC-3 A caller can parse raw string tokens through ParseString and receive the expected decoded Go string value or the documented malformed-token error. test SYS-REQ-014, SYS-REQ-038, SYS-REQ-060, SYS-REQ-061, SYS-REQ-062, SYS-REQ-063, SYS-REQ-067
AC-4 A caller can parse raw integer tokens through ParseInt and receive the expected int64 value, the documented overflow error, or the documented malformed-token error. test SYS-REQ-015, SYS-REQ-039, SYS-REQ-040, SYS-REQ-058, SYS-REQ-059, SYS-REQ-064, SYS-REQ-106, SYS-REQ-107, SYS-REQ-108, SYS-REQ-109

2.3 User Characteristics

The following user classes (stakeholder personas) are derived from the stakeholder requirements captured for this project:

2.4 Constraints

The design constraints for jsonparser are the requirements classified as constraints; they are specified in full in Section 3 under each component's "Design Constraints". The assurance levels assigned to requirements in this specification determine the rigor of the verification evidence required.

2.5 Assumptions and Dependencies

The assumptions for jsonparser are the requirements classified as assumptions in this specification; they are specified in Section 3 alongside the guarantees that depend on them. Inter-component dependencies are captured by the interface definitions in Section 2.8 and the traceability links in Section 6.

2.6 Components

#ComponentRequirements
1parser123

2.7 Variable Summary

Total variables across all components: 242

2.7b Specification Hierarchy

The project organizes requirements into a multi-level specification hierarchy. Each level represents a tier of decomposition from stakeholder needs down to implementation details.

LevelSpec PathTypePrefixRequirements
L0 specs/stakeholder stakeholder STK-REQ 7
L1 specs/system system SYS-REQ 116

Specification Hierarchy Diagram

graph TD
  n_specs_stakeholder["specs/stakeholder\nL0 #124; stakeholder\n7 reqs"]
  n_specs_system["specs/system\nL1 #124; system\n116 reqs"]

  n_specs_stakeholder --> n_specs_system

2.8 Interface Requirements

2.8.1 User Interfaces

User interface requirements for jsonparser, where applicable, are captured as interface-category requirements in Section 3.

2.8.2 Software Interfaces (Component Boundaries)

No software interfaces defined.

2.8.3 Communication Interfaces

No communication interfaces are defined for this project.

3. Stakeholder Requirements (L0)

3.1 parser

Requirements: 7 total (7 guarantees, 0 assumptions, 0 constraints, 0 derived)

Functional Requirements

STK-REQ-001 approved shall Guarantee DAL-E
Description: Library users shall retrieve values from JSON byte payloads by specifying a key path without predeclaring Go structs.
Rationale: This is the core value proposition described in the project README and the primary reason to adopt jsonparser over encoding/json for dynamic payloads.
Strategy: informal
Verification Method:
Verified: No
Tags: parser, deserializer, accepts_user_data
STK-REQ-002 approved shall Guarantee DAL-E
Description: Library users shall retrieve string values with JSON escapes and Unicode decoded into Go strings.
Rationale: The README explicitly promises that GetString handles escaped and Unicode characters correctly, which is a user-visible contract distinct from raw byte lookup.
Strategy: informal
Verification Method:
Verified: No
Tags: parser, deserializer, accepts_user_data
STK-REQ-003 approved shall Guarantee DAL-E
Description: Library users shall extract known numeric and boolean JSON values through typed helpers without manual byte parsing or ad-hoc conversions.
Rationale: The README presents typed helpers as part of the public API for callers who already know the expected JSON scalar type.
Strategy: informal
Verification Method:
Verified: No
Tags: parser, accepts_user_data
STK-REQ-004 approved shall Guarantee DAL-E
Description: Library users shall traverse arrays and objects and extract multiple key paths from one payload without manually walking the JSON structure.
Rationale: The traversal helpers and EachKey are part of the library's value proposition for dynamic JSON inspection without struct predeclaration or hand-written walkers.
Strategy: informal
Verification Method:
Verified: No
Tags: traversal, decomposition, parser, deserializer, accepts_user_data
STK-REQ-005 approved shall Guarantee DAL-E
Description: Library users shall update or delete addressed JSON values in byte payloads through the experimental mutation helpers with deterministic edge-case behavior.
Rationale: Set and Delete are documented experimental APIs, so their mutation and malformed-input behavior still needs explicit contract coverage.
Strategy: informal
Verification Method:
Verified: No
Tags: mutation, decomposition, parser, accepts_user_data
STK-REQ-006 approved shall Guarantee DAL-E
Description: Library users shall retrieve addressed JSON values as zero-allocation raw strings without JSON unescaping when they intentionally choose the unsafe helper.
Rationale: GetUnsafeString is a distinct public contract from GetString because it trades escaping semantics for speed and zero-allocation string mapping.
Strategy: informal
Verification Method:
Verified: No
Tags: parser, accepts_user_data
STK-REQ-007 approved shall Guarantee DAL-E
Description: Library users shall parse raw JSON scalar tokens into Go boolean, integer, float, and decoded string values with deterministic error behavior on malformed input.
Rationale: The Parse* helpers are public token-level conversion utilities and their malformed-input behavior is part of the callable API surface.
Strategy: informal
Verification Method:
Verified: No
Tags: parse, decomposition, parser, accepts_user_data

4. System Requirements (L1)

4.1 parser

Requirements: 116 total (116 guarantees, 0 assumptions, 0 constraints, 0 derived)

Functional Requirements

SYS-REQ-001 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !json_input_is_well_formed | !key_path_is_provided | !addressed_path_exists | returns_existing_path_lookup_result
Description: When the JSON input is well formed, a key path is provided, and the addressed path exists, the parser shall return the addressed value slice, the corresponding value type classification, the end offset of that value, and no error.
Rationale: The exported Get API is the fundamental primitive that all typed accessor helpers build on, so successful addressed lookup should be specified independently from not-found, empty-input, incomplete-input, no-key-path behavior, and lower-level path interpretation rules.
Strategy: fretish
SYS-REQ-002 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_value_is_string | !raw_string_token_is_well_formed | returns_getstring_decoded_value
Description: When GetString addresses a JSON string value whose raw token is well formed, the parser shall return the corresponding decoded Go string value.
Rationale: GetString is the documented safe string helper and is expected to handle escaped and Unicode content correctly.
Strategy: fretish
SYS-REQ-003 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_value_is_number | !raw_number_token_is_integer_parseable | returns_getint_value
Description: When GetInt addresses a JSON number token that is parseable as an int64 value, the parser shall return the corresponding int64 result. GetUint64 is the uint64-typed variant of GetInt: when the addressed JSON number token is parseable as a uint64 (non-negative, magnitude within uint64 range), GetUint64 returns the corresponding uint64 result, returning OverflowIntegerError when the magnitude exceeds uint64 range and MalformedValueError when the addressed value is not a non-negative integer.
Rationale: GetInt is a public typed helper for callers who expect integer-valued JSON fields and need contract-level error behavior on invalid access.
Strategy: fretish
SYS-REQ-004 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_value_is_number | !raw_number_token_is_float_parseable | returns_getfloat_value
Description: When GetFloat addresses a JSON number token that is parseable as a float64 value, the parser shall return the corresponding float64 result. ArrayEachErr is the io.EOF-aware ArrayEach variant where the callback may stop iteration by returning an error; the returned count includes the element whose callback stopped iteration.
Rationale: GetFloat is the public floating-point accessor for callers that know the expected numeric type and still need defined failure behavior.
Strategy: fretish
SYS-REQ-005 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_value_is_boolean | !raw_boolean_token_is_well_formed | returns_getboolean_value
Description: When GetBoolean addresses a well-formed JSON boolean token, the parser shall return the corresponding Go bool value.
Rationale: GetBoolean is a public typed helper for callers that expect boolean JSON fields and need explicit error signaling otherwise.
Strategy: fretish
SYS-REQ-006 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_array_is_well_formed | addressed_array_is_empty | array_callback_receives_elements_in_order
Description: When ArrayEach addresses a well-formed non-empty JSON array, the parser shall invoke the callback for each addressed array element in encounter order.
Rationale: Ordered iteration over addressed array contents is a distinct externally visible behavior from empty-array handling and malformed-input handling.
Strategy: fretish
Tags: decomposition, arrayeach, traversal
SYS-REQ-007 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_object_is_well_formed | addressed_object_is_empty | object_callback_receives_entries
Description: When ObjectEach addresses a well-formed non-empty JSON object, the parser shall invoke the callback with the correct key, value, and value type tuple for each addressed object entry.
Rationale: Correct object entry reporting is a distinct externally visible contract from empty-object handling, malformed-input failure, and callback error propagation.
Strategy: fretish
Tags: decomposition, objecteach, traversal
SYS-REQ-008 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !multipath_requests_are_provided | eachkey_callback_receives_found_values | missing_multipath_request_does_not_emit_callback | eachkey_malformed_input_returns_error | eachkey_completes_requested_scan
Description: When EachKey is called with one or more requested key paths, the parser shall emit callback results for found paths, omit found-value callbacks for missing paths, surface malformed-input errors, and complete the requested multi-path scan. EachKeyErr is the io.EOF-aware EachKey variant where the callback may stop iteration by returning an error; io.EOF stops iteration gracefully while any other non-nil error stops iteration and is propagated to the caller.
Rationale: EachKey is the documented single-pass multi-path lookup helper and needs explicit contract coverage for both found and missing path behavior.
Strategy: fretish
SYS-REQ-009 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_path_is_provided | set_target_exists | set_creates_missing_path | set_returns_updated_document | set_returns_not_found_error
Description: When Set is called with a provided path, the parser shall either replace the existing addressed value, create a type-consistent missing path and return the updated JSON document, or return KeyPathNotFoundError when the requested mutation path is not usable for the provided input. 'Type-consistent' means each path segment's kind matches its resolved parent container: object-key segments under object parents, array-index [N] segments under array parents. A path component whose kind mismatches its parent (e.g. [N] under an object, or an object-key under an array at a depth where the parent must be inferred) is 'not usable for the provided input' and shall surface KeyPathNotFoundError. (Cross-type mismatch currently produces malformed JSON output instead — tracked as DEFECT-260726-MFPA / KI-3.) SetString is the auto-quoting Set variant: SetString(data, val, keys...) is equivalent to Set(data, Escape(val), keys...) where Escape RFC-8259-encodes val as a JSON string literal including surrounding quotes, so callers can pass a Go string directly without manually quoting it.
Rationale: Set is the documented experimental mutation helper and must preserve defined behavior for addressed path updates and invalid mutation inputs.
Strategy: fretish
SYS-REQ-010 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy delete_path_is_provided | delete_returns_empty_document_without_path
Description: When Delete is called without a path, the parser shall return an empty document. DeleteFound is the explicit-found variant of Delete: DeleteFound(data, keys...) returns (result, found) where result is the post-deletion document (or the original input when the path is missing) and found is true iff the addressed value was located and removed.
Rationale: Delete without a path is a distinct API outcome and should not be bundled with successful deletion, missing-target handling, or malformed-input robustness.
Strategy: fretish
Tags: decomposition, delete, edge-case
SYS-REQ-011 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_value_is_string | returns_unsafe_string_view
Description: When GetUnsafeString addresses a JSON string value, the parser shall return the addressed raw value bytes mapped directly as a Go string without JSON unescaping.
Rationale: GetUnsafeString is explicitly documented as the low-allocation alternative to GetString and needs its own contract coverage.
Strategy: fretish
SYS-REQ-012 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_boolean_literal_is_valid | returns_parseboolean_value
Description: When ParseBoolean receives a valid raw boolean token, the parser shall return the corresponding Go bool value.
Rationale: ParseBoolean success on valid tokens should be specified independently from the invalid-token error path.
Strategy: fretish
Tags: decomposition, parse, boolean
SYS-REQ-013 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_float_token_is_well_formed | returns_parsefloat_value
Description: When ParseFloat receives a well-formed floating-point number token, the parser shall return the corresponding float64 value.
Rationale: ParseFloat success on valid tokens should be specified independently from malformed-token rejection.
Strategy: fretish
Tags: decomposition, parse, float
SYS-REQ-014 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_string_literal_is_well_formed | returns_parsestring_value
Description: When ParseString receives a well-formed raw JSON string literal body, the parser shall return the corresponding decoded Go string value. Escape is the RFC 8259 inverse of Unescape/ParseString: Escape(in) returns in encoded as a JSON string literal including the surrounding quotation marks, escaping the mandatory characters (quotation mark, reverse solidus, control characters U+0000–U+001F) and any non-ASCII bytes as \uXXXX sequences, so the result is a valid JSON string token suitable for direct embedding in a JSON document.
Rationale: ParseString success on valid encoded strings should be specified independently from malformed-string rejection.
Strategy: fretish
Tags: decomposition, parse, string
SYS-REQ-015 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_int_token_is_well_formed | returns_parseint_value
Description: When ParseInt receives a syntactically well-formed integer token that does not overflow int64, the parser shall return the corresponding int64 value.
Rationale: ParseInt success on non-overflow integer tokens should be specified independently from overflow and malformed-token outcomes.
Strategy: fretish
Tags: decomposition, parse, int
SYS-REQ-016 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !json_input_is_well_formed | !key_path_is_provided | addressed_path_exists | returns_missing_path_result_for_well_formed_lookup
Description: When the JSON input is well formed, a key path is provided, and the addressed path does not exist, the parser shall return the defined not-found result with `NotExist`, offset `-1`, and `KeyPathNotFoundError`.
Rationale: The Get contract is not complete unless the missing-path outcome is specified independently from successful lookup and incomplete-input failure.
Strategy: fretish
Tags: decomposition, get
SYS-REQ-017 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !input_is_incomplete_during_lookup | returns_parse_error_for_incomplete_lookup
Description: When the JSON input is incomplete or truncated before addressed lookup or no-key-path extraction can complete, including incomplete addressed strings, arrays, objects, or missing value tokens, the parser shall return a parse-related error and shall not report a successful lookup result.
Rationale: Incomplete or truncated input is a distinct externally visible failure mode in Get and should be modeled independently from successful lookup, empty-input, tolerated malformed-input, or not-found behavior.
Strategy: fretish
Tags: decomposition, get, edge-case
SYS-REQ-018 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !json_input_is_well_formed | key_path_is_provided | returns_root_value_without_key_path
Description: When the JSON input is well formed and no key path is provided, the parser shall return the closest complete root JSON value according to the API contract, including complete object, array, string, number, boolean, or null values.
Rationale: Get has special root-extraction behavior when no key path is provided, so that contract should be modeled independently from addressed lookup.
Strategy: fretish
Tags: decomposition, get
SYS-REQ-019 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !json_input_is_empty | !key_path_is_provided | returns_missing_path_result_for_empty_input
Description: When the input is empty and a key path is provided, the parser shall return the defined not-found result with `NotExist`, offset `-1`, and `KeyPathNotFoundError`.
Rationale: The current Get contract treats empty input as an addressed lookup miss rather than as a parsing error, so that edge case should be modeled explicitly.
Strategy: fretish
Tags: decomposition, get, edge-case
SYS-REQ-020 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !path_segment_is_object_key | !segment_is_evaluated_at_current_scope | returns_value_from_current_scope_object_key
Description: When the current path segment is an object key and it is evaluated at the current JSON structural scope, Get shall resolve that segment only against object members in that current scope.
Rationale: Correct lookup depends on respecting JSON structural scope rather than matching a similarly named key in a sibling or deeper subtree.
Strategy: fretish
Tags: decomposition, get, scope
SYS-REQ-021 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !path_segment_is_array_index | !array_index_segment_is_valid | !array_index_is_in_bounds | returns_value_from_in_bounds_array_index
Description: When the current path segment is a valid in-bounds array index, Get shall resolve the addressed array element and return it through the normal successful lookup contract.
Rationale: Array index path segments are part of the documented public lookup contract and are behaviorally distinct from object-key segments.
Strategy: fretish
Tags: decomposition, get, array-index
SYS-REQ-022 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !path_segment_is_array_index | array_index_segment_is_valid | returns_invalid_array_index_not_found
Description: When the current path segment is intended as an array index but its syntax is malformed, Get shall return the defined not-found result rather than a successful lookup.
Rationale: Malformed array-index syntax is an externally visible path-interpretation case and should not be hidden inside a generic lookup-miss predicate.
Strategy: fretish
Tags: decomposition, get, array-index, edge-case
SYS-REQ-023 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !path_segment_is_array_index | !array_index_segment_is_valid | !array_index_is_out_of_bounds | returns_oob_array_index_not_found
Description: When the current path segment is a valid array index but the index is out of bounds for the addressed array, Get shall return the defined not-found result.
Rationale: Out-of-bounds array access is behaviorally distinct from malformed index syntax and from successful element resolution.
Strategy: fretish
Tags: decomposition, get, array-index, edge-case
SYS-REQ-024 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !escaped_json_object_key_is_present | !decoded_path_segment_matches_escaped_key | returns_value_from_decoded_escaped_key
Description: When a JSON object member key is escaped in the payload and the decoded path segment matches that logical key value, Get shall resolve the member through the normal successful lookup contract.
Rationale: Escaped-key matching is caller-visible compatibility behavior and should be specified directly rather than left implicit in helper implementation.
Strategy: fretish
Tags: decomposition, get, escaped-key
SYS-REQ-025 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !addressed_value_is_string | returns_unquoted_raw_string_contents
Description: When the addressed value is a JSON string, Get shall return the string token contents without surrounding quotes and without JSON unescaping.
Rationale: Get has a distinct string-return contract from both GetString and GetUnsafeString, so the returned string shape should be modeled explicitly.
Strategy: fretish
Tags: decomposition, get, string
SYS-REQ-026 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !malformed_input_outside_addressed_token | !addressed_token_can_be_isolated | returns_best_effort_lookup_result
Description: When the input is malformed outside the addressed token path but the parser can still isolate a complete addressed token or determine that the path is absent, Get shall preserve the corresponding best-effort success or not-found result instead of requiring full-document rejection.
Rationale: The current implementation intentionally tolerates some malformed-document cases for performance, and that externally visible behavior should be either specified or explicitly retired from the contract.
Strategy: fretish
Tags: decomposition, get, malformed-tolerance
SYS-REQ-027 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !addressed_token_shape_is_invalid | returns_value_type_error
Description: When the addressed token cannot be classified as string, object, array, number, boolean, or null, Get shall return a value-type error instead of a successful classification.
Rationale: Unknown token classification is an externally visible error path in Get and should not be hidden inside a generic parse-failure bucket.
Strategy: fretish
Tags: decomposition, get, type
SYS-REQ-028 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_array_is_well_formed | !addressed_array_is_empty | empty_array_produces_no_callbacks
Description: When ArrayEach addresses a well-formed empty JSON array, the parser shall emit no callbacks.
Rationale: Empty-array behavior is externally visible and should be reviewed independently from non-empty iteration and malformed-input failure.
Strategy: fretish
Tags: decomposition, arrayeach, edge-case
SYS-REQ-029 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy addressed_array_is_well_formed | malformed_array_input_returns_error
Description: When ArrayEach receives malformed or otherwise unusable addressed array input, the parser shall return an error. When the addressed root value is not an array (object, number, string, boolean, null) and no key path is provided, the parser shall return MalformedArrayError WITHOUT invoking the callback — the previous implementation emitted one spurious callback with a misparsed token before erroring (DEFECT-260727-ARR1).
Rationale: Malformed-array failure is a distinct observable behavior class and should not be hidden inside the ordered-iteration or empty-array contracts.
Strategy: fretish
Tags: decomposition, arrayeach, edge-case
SYS-REQ-030 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_object_is_well_formed | !addressed_object_is_empty | empty_object_produces_no_entries
Description: When ObjectEach addresses a well-formed empty JSON object, the parser shall emit no entry callbacks.
Rationale: Empty-object behavior is externally visible and should be reviewed independently from non-empty entry reporting, malformed-input failure, and callback error propagation.
Strategy: fretish
Tags: decomposition, objecteach, edge-case
SYS-REQ-031 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy addressed_object_is_well_formed | malformed_object_input_returns_error
Description: When ObjectEach receives malformed or otherwise unusable addressed object input, the parser shall return an error.
Rationale: Malformed-object failure is a distinct observable behavior class and should not be hidden inside entry-reporting or callback-propagation semantics.
Strategy: fretish
Tags: decomposition, objecteach, edge-case
SYS-REQ-032 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !addressed_object_is_well_formed | !object_callback_returns_error | object_callback_error_is_returned
Description: When ObjectEach addresses a well-formed object and the callback returns an error, the parser shall return that callback error.
Rationale: Callback error propagation is a distinct externally visible contract and should not be buried inside generic object-iteration success behavior.
Strategy: fretish
Tags: decomposition, objecteach, callback
SYS-REQ-033 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_path_is_provided | !delete_target_exists | delete_returns_document_without_target
Description: When Delete is called with a provided path and the addressed target exists in usable input, the parser shall return the JSON document with that target removed.
Rationale: Successful deletion of an existing target is a distinct API behavior from no-path handling, missing-target preservation, and unusable-input robustness.
Strategy: fretish
Tags: decomposition, delete, mutation
SYS-REQ-034 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_path_is_provided | delete_target_exists | delete_input_is_unusable_for_requested_path | delete_preserves_input_when_target_missing
Description: When Delete is called with a provided path, the addressed target is absent, and the input is otherwise usable for deletion, the parser shall return the original byte payload unchanged.
Rationale: Missing-target preservation is a distinct API outcome from successful deletion and from malformed-input robustness.
Strategy: fretish
Tags: decomposition, delete, edge-case
SYS-REQ-035 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_path_is_provided | !delete_input_is_unusable_for_requested_path | (delete_returns_original_input_on_unusable_input & delete_completes_without_panic)
Description: When Delete is called with a provided path but the input is malformed, truncated, or otherwise unusable for the requested deletion, the parser shall return the original byte payload unchanged and shall not panic.
Rationale: Delete robustness on unusable input is a security-relevant behavior class and should be specified independently from successful deletion and missing-target behavior.
Strategy: fretish
Tags: decomposition, delete, robustness
SYS-REQ-036 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy raw_boolean_literal_is_valid | returns_parseboolean_error
Description: When ParseBoolean receives an invalid boolean token, the parser shall return the documented malformed-value error.
Rationale: Invalid-token failure is externally visible and should be specified independently from valid ParseBoolean success behavior.
Strategy: fretish
Tags: decomposition, parse, boolean, edge-case
SYS-REQ-037 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy raw_float_token_is_well_formed | returns_parsefloat_error
Description: When ParseFloat receives a malformed numeric token, the parser shall return the documented malformed-value error.
Rationale: Malformed-token failure is externally visible and should be specified independently from valid ParseFloat success behavior.
Strategy: fretish
Tags: decomposition, parse, float, edge-case
SYS-REQ-038 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy raw_string_literal_is_well_formed | returns_parsestring_error
Description: When ParseString receives a malformed encoded string literal, the parser shall return the documented malformed-value error.
Rationale: Malformed-string failure is externally visible and should be specified independently from valid ParseString decoding behavior.
Strategy: fretish
Tags: decomposition, parse, string, edge-case
SYS-REQ-039 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_int_token_overflows_int64 | returns_parseint_overflow_error
Description: When ParseInt receives an integer token whose magnitude exceeds the supported int64 range, the parser shall return the documented overflow error.
Rationale: Overflow is an externally visible ParseInt outcome and should be specified independently from valid integer parsing and malformed-token rejection.
Strategy: fretish
Tags: decomposition, parse, int, overflow
SYS-REQ-040 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy raw_int_token_is_well_formed | raw_int_token_overflows_int64 | returns_parseint_malformed_error
Description: When ParseInt receives a non-integer or otherwise malformed token that is not an overflow case, the parser shall return the documented malformed-value error.
Rationale: Malformed-token rejection is an externally visible ParseInt outcome and should be specified independently from valid integer parsing and overflow detection.
Strategy: fretish
Tags: decomposition, parse, int, edge-case
SYS-REQ-041 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !input_is_truncated_at_value_boundary | returns_error_for_truncated_value_boundary
Description: When the JSON input is truncated at a value boundary (e.g., the value token ends at EOF with no closing delimiter such as '{"a":1' with no closing brace), Get shall return a parse-related error or not-found result and shall not panic or use an out-of-bounds index.
Rationale: PR #280 demonstrated that tokenEnd returns len(data) as a sentinel when no delimiter is found, and callers that use this sentinel as an array index without bounds checking will panic. This obligation class must be modeled explicitly.
Strategy: fretish
Tags: truncation, sentinel, pr280
SYS-REQ-042 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !input_is_truncated_mid_structure | returns_error_for_truncated_mid_structure
Description: When the JSON input is truncated in the middle of a structural element (e.g., an object or array that is opened but never closed, such as '{"a":[1,2'), Get shall return a parse-related error and shall not panic.
Rationale: Truncated mid-structure input exercises blockEnd returning -1, which is behaviorally distinct from truncated-at-value-boundary where tokenEnd returns len(data).
Strategy: fretish
Tags: truncation, structure
SYS-REQ-043 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !input_is_truncated_mid_key | returns_error_for_truncated_mid_key
Description: When the JSON input is truncated in the middle of a key string (e.g., '{"a' where the key string is not terminated), Get shall return a parse-related error and shall not panic.
Rationale: Truncated mid-key input exercises stringEnd returning -1, which is a distinct truncation pattern from mid-structure and at-value-boundary cases.
Strategy: fretish
Tags: truncation, key
SYS-REQ-044 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !tokenEnd_returns_len_data | caller_bounds_checks_tokenEnd_sentinel
Description: When internal helper tokenEnd returns len(data) as a sentinel value indicating no delimiter was found, all callers of tokenEnd shall treat this sentinel as an end-of-input condition and shall not use it as an unchecked array index that could exceed the valid data range.
Rationale: The root cause of PR #280 was that tokenEnd returns len(data) as a sentinel, and Delete used data[endOffset+tokEnd] without checking whether endOffset+tokEnd >= len(data). This data constraint must be formalized.
Strategy: fretish
Tags: sentinel, data-constraint, pr280
SYS-REQ-045 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !stringEnd_returns_negative_one | caller_handles_stringEnd_sentinel
Description: When internal helper stringEnd returns -1 indicating no closing quote was found, all callers of stringEnd shall treat this as a malformed-string condition and shall not proceed with normal value extraction.
Rationale: stringEnd returning -1 is a sentinel value that indicates truncated or malformed string input. All callers must check for this before using the return value as an offset.
Strategy: fretish
Tags: sentinel, data-constraint
SYS-REQ-046 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !blockEnd_returns_negative_one | caller_handles_blockEnd_sentinel
Description: When internal helper blockEnd returns -1 indicating no matching closing bracket or brace was found, all callers of blockEnd shall treat this as a malformed-structure condition and shall not proceed with normal value extraction.
Rationale: blockEnd returning -1 is a sentinel value that indicates truncated or malformed structural input. All callers must check for this before using the return value as an offset.
Strategy: fretish
Tags: sentinel, data-constraint
SYS-REQ-047 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !path_segment_is_negative_array_index | returns_not_found_for_negative_array_index
Description: When the current path segment is a negative array index (e.g., "[-1]"), Get shall return the defined not-found result because negative indexing is not supported by the JSON path syntax.
Rationale: Negative array indices are not part of the documented path syntax. The parser should deterministically handle them rather than producing undefined behavior.
Strategy: fretish
Tags: array-index, edge-case
SYS-REQ-048 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_input_is_truncated_at_value_boundary | (delete_returns_original_input_on_truncated_value & delete_completes_without_panic_on_truncated_value)
Description: When Delete is called on input that is truncated at a value boundary (the exact PR
Rationale: This is the exact bug class from PR #280. Delete calls tokenEnd on truncated input, gets len(data) back, then uses data[endOffset+tokEnd] which panics with index out of range. This specific truncation pattern for Delete must have its own requirement.
Strategy: fretish
Tags: pr280, delete, truncation, sentinel
SYS-REQ-049 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_discards_internalGet_error | delete_propagates_internalGet_error
Description: When Delete calls internalGet and internalGet returns an error, Delete shall use that error to short-circuit to the safe fallback path (return original input unchanged) rather than discarding the error and proceeding with potentially invalid offsets.
Rationale: Error propagation from internalGet is the defense-in-depth mechanism against sentinel-value panics. If Delete discards the error (assigns to _), it loses the signal that offsets are invalid. This was a contributing factor in the PR #280 class.
Strategy: fretish
Tags: error-propagation, delete, pr280
SYS-REQ-050 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_array_input_is_truncated | (delete_returns_original_input_on_truncated_array & delete_completes_without_panic_on_truncated_array)
Description: When Delete is called with an array-element path on input where the array is truncated (e.g., Delete([]byte(`{"a":[1,2`), "a", "[1]")), the parser shall return the original byte payload unchanged and shall not panic.
Rationale: Array deletion on truncated input exercises the same tokenEnd sentinel pattern as object deletion but through a different code path in Delete (the array branch).
Strategy: fretish
Tags: delete, array, truncation
SYS-REQ-051 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_input_is_truncated | set_returns_error_for_truncated_input
Description: When Set is called on truncated JSON input where the path resolution encounters incomplete structural elements, the parser shall return an error rather than producing corrupt output or panicking.
Rationale: Set shares the same internalGet code path as Delete. If truncated input can cause Delete to panic, Set is equally vulnerable through the same sentinel-value patterns.
Strategy: fretish
Tags: set, truncation
SYS-REQ-052 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !array_callback_returns_error | array_callback_error_is_propagated
Description: When ArrayEach iterates a well-formed array and the Get call for an element returns an error (e.g., due to a truncated element within the array), ArrayEach shall propagate that error to the caller rather than silently continuing iteration.
Rationale: ArrayEach error propagation from element-level Get failures is a distinct contract from ObjectEach callback error propagation (SYS-REQ-032) and from malformed-array input (SYS-REQ-029).
Strategy: fretish
Tags: arrayeach, callback, error-propagation
SYS-REQ-053 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !array_is_truncated_mid_element | returns_error_for_truncated_array_element
Description: When ArrayEach encounters an array element that is truncated (e.g., '[1, {"a":' where the second element is incomplete), the parser shall return a parse-related error and shall not panic.
Rationale: Truncated mid-element iteration exercises different sentinel paths than completely missing closing brackets. The Get call inside the loop may return sentinel values.
Strategy: fretish
Tags: arrayeach, truncation
SYS-REQ-054 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !object_is_truncated_mid_entry | returns_error_for_truncated_object_entry
Description: When ObjectEach encounters an object entry that is truncated (e.g., '{"a":1, "b":' where the second value is incomplete), the parser shall return a parse-related error and shall not panic.
Rationale: Truncated mid-entry iteration in ObjectEach exercises Get on incomplete value tokens, which may trigger sentinel-value boundary conditions.
Strategy: fretish
Tags: objecteach, truncation
SYS-REQ-055 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !array_has_malformed_delimiter | returns_error_for_malformed_array_delimiter
Description: When ArrayEach encounters a malformed delimiter between array elements (e.g., '[1; 2]' or '[1 2]' where a comma is expected but a different character or no delimiter is found), the parser shall return a MalformedArrayError.
Rationale: Malformed delimiters between elements are a distinct malformed-input subclass from missing closing brackets and from truncated elements.
Strategy: fretish
Tags: arrayeach, malformed, delimiter
SYS-REQ-056 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !delete_input_is_truncated_mid_structure | (delete_returns_original_input_on_truncated_structure & delete_completes_without_panic_on_truncated_structure)
Description: When Delete is called on input that is truncated mid-structure (e.g., an object with an unclosed nested object like '{"a":{"b":1'), the parser shall return the original byte payload unchanged and shall not panic.
Rationale: Mid-structure truncation in Delete exercises both internalGet and findKeyStart with incomplete structural input, which is a distinct truncation pattern from at-value-boundary.
Strategy: fretish
Tags: delete, truncation, structure
SYS-REQ-057 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_boolean_literal_is_partial | returns_error_for_partial_boolean_literal
Description: When ParseBoolean receives a partial boolean literal (e.g., "tru", "fals", "t", "f"), the parser shall return MalformedValueError because the token does not match either "true" or "false" exactly.
Rationale: Partial boolean literals are a distinct malformed-input subclass that exercises the bytes.Equal comparison boundary. Truncated network payloads commonly produce these.
Strategy: fretish
Tags: parse, boolean, partial-literal
SYS-REQ-058 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_int_token_is_at_int64_max_boundary | returns_correct_value_at_int64_boundary
Description: When ParseInt receives integer tokens at the exact int64 boundary values (9223372036854775807 for max, -9223372036854775808 for min), the parser shall return the correct int64 value without overflow error.
Rationale: The int64 boundary is a critical boundary value where off-by-one errors in overflow detection would produce incorrect results. Both max positive and min negative must be tested.
Strategy: fretish
Tags: parse, int, boundary
SYS-REQ-059 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_int_token_is_at_int64_max_plus_one | returns_overflow_at_int64_max_plus_one
Description: When ParseInt receives an integer token that is exactly one beyond the int64 range (9223372036854775808 for max+1, -9223372036854775809 for min-1), the parser shall return OverflowIntegerError.
Rationale: The boundary between valid and overflow is where off-by-one errors hide. The max+1 and min-1 cases must be specified explicitly.
Strategy: fretish
Tags: parse, int, boundary, overflow
SYS-REQ-060 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_string_has_truncated_escape_sequence | returns_error_for_truncated_escape_sequence
Description: When ParseString receives a string literal containing a truncated escape sequence (e.g., a backslash at end of string, or a unicode escape like '\u00' with insufficient hex digits), the parser shall return MalformedValueError.
Rationale: Truncated escape sequences exercise the unescapeToUTF8 and decodeUnicodeEscape boundary conditions where insufficient input length is checked.
Strategy: fretish
Tags: parse, string, escape, truncation
SYS-REQ-061 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_string_has_missing_low_surrogate | substitutes_replacement_for_missing_low_surrogate
Description: When ParseString encounters a UTF-16 high surrogate escape (e.g., '\uD800') that is not followed by a valid low surrogate escape, the parser shall substitute U+FFFD (replacement character) for the lone surrogate and continue parsing, matching encoding/json behavior, rather than producing corrupted output or synthesizing a bogus code point.
Rationale: Surrogate pair handling in decodeUnicodeEscape requires both high and low surrogates. A missing or invalid low surrogate exercises a distinct failure path.
Strategy: fretish
Tags: parse, string, unicode, surrogate
SYS-REQ-062 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_string_has_invalid_low_surrogate | substitutes_replacement_for_invalid_low_surrogate
Description: When ParseString encounters a UTF-16 high surrogate escape followed by a second unicode escape whose value is below the low surrogate range (e.g., '\uD800\u0041'), the parser shall substitute U+FFFD (replacement character) for the malformed surrogate sequence and continue parsing, matching encoding/json behavior, rather than producing corrupted output or returning an error.
Rationale: An invalid low surrogate (valid unicode escape but wrong range) exercises a different branch in decodeUnicodeEscape than a completely missing second escape.
Strategy: fretish
Tags: parse, string, unicode, surrogate
SYS-REQ-063 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !raw_string_has_backslash_at_end | returns_error_for_backslash_at_end
Description: When ParseString encounters a string literal ending with a lone backslash (the escape sequence is incomplete because there is no character after the backslash), the parser shall return MalformedValueError.
Rationale: A backslash at the end of a string is the simplest truncated-escape case and exercises the len(in) < 2 guard in unescapeToUTF8.
Strategy: fretish
Tags: parse, string, escape, edge-case
SYS-REQ-064 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parseint_input_is_empty | returns_parseint_malformed_for_empty
Description: When ParseInt receives an empty byte slice, the parser shall return MalformedValueError because an empty token is not a valid integer representation.
Rationale: Empty input to ParseInt is a distinct boundary case from malformed non-empty tokens and overflow tokens.
Strategy: fretish
Tags: parse, int, empty, boundary
SYS-REQ-065 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parsefloat_input_is_empty | returns_parsefloat_malformed_for_empty
Description: When ParseFloat receives an empty byte slice, the parser shall return MalformedValueError because an empty token is not a valid floating-point representation.
Rationale: Empty input to ParseFloat is a distinct boundary case from malformed non-empty tokens.
Strategy: fretish
Tags: parse, float, empty, boundary
SYS-REQ-066 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parseboolean_input_is_empty | returns_parseboolean_malformed_for_empty
Description: When ParseBoolean receives an empty byte slice, the parser shall return MalformedValueError because an empty token is not a valid boolean representation.
Rationale: Empty input to ParseBoolean is a distinct boundary case from partial literals like "tru" and from valid tokens.
Strategy: fretish
Tags: parse, boolean, empty, boundary
SYS-REQ-067 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parsestring_input_is_empty | returns_parsestring_identity_for_empty
Description: When ParseString receives an empty byte slice, the parser shall return an empty Go string without error because an empty string body (content between quotes) is a valid string representation.
Rationale: Empty string input to ParseString (representing the body of '""') is a valid edge case that should produce an empty Go string, not an error.
Strategy: fretish
Tags: parse, string, empty, boundary
SYS-REQ-068 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_path_points_beyond_eof | set_returns_error_for_path_beyond_eof
Description: When Set is called with a path that resolves to a location beyond the end of the available data (e.g., setting a deep nested key in a truncated document), the parser shall return an error rather than panicking or producing corrupt output.
Rationale: Set uses internalGet for path resolution. If the path points beyond available data, the offsets returned may be sentinel values that cause out-of-bounds access in the mutation logic.
Strategy: fretish
Tags: set, truncation, sentinel
SYS-REQ-069 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_target_is_nested_in_existing_structure | set_performs_nested_mutation_correctly
Description: When Set is called with a multi-level path where intermediate levels exist but the leaf does not, the parser shall correctly create the missing nested structure and insert the value at the correct location.
Rationale: Nested mutation through createInsertComponent exercises depth-tracking logic that determines whether to append inside an existing structure or overwrite. This is a distinct behavior from flat key insertion.
Strategy: fretish
Tags: set, nested, mutation
SYS-REQ-070 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_called_without_path | set_returns_error_without_path
Description: When Set is called without any key path, the parser shall return KeyPathNotFoundError because Set requires at least one path segment to identify the mutation target.
Rationale: Set without a path is a distinct edge case from Delete without a path (which returns empty). Set returns an error, Delete returns empty document. Both no-path behaviors must be explicitly specified.
Strategy: fretish
Tags: set, edge-case, no-path
SYS-REQ-071 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_input_is_malformed | returns_getstring_error_for_malformed
Description: When GetString is called on malformed input where the underlying Get call returns an error, GetString shall propagate that error to the caller.
Rationale: GetString delegates to Get for path resolution. Malformed input errors from Get must be propagated rather than masked.
Strategy: fretish
Tags: getstring, malformed, error-propagation
SYS-REQ-072 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_value_has_truncated_escape | returns_getstring_error_for_truncated_escape
Description: When GetString addresses a JSON string value containing a truncated escape sequence, the parser shall return an error from the ParseString unescape step rather than returning corrupted output.
Rationale: GetString calls ParseString for unescaping. Truncated escape sequences must surface as errors through GetString.
Strategy: fretish
Tags: getstring, escape, truncation
SYS-REQ-073 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_addressed_value_is_not_string | returns_getstring_type_mismatch_error
Description: When GetString addresses a value that is not a JSON string (e.g., a number, boolean, object, array, or null), the parser shall return a type-mismatch error.
Rationale: GetString has explicit type-checking logic that rejects non-string values. This type-mismatch behavior is distinct from successful string decoding and from malformed-input error propagation.
Strategy: fretish
Tags: getstring, type-mismatch
SYS-REQ-074 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_input_is_empty | returns_getstring_error_for_empty_input
Description: When GetString is called on empty input, the parser shall return the same not-found or error behavior as Get on empty input.
Rationale: Empty input to GetString delegates to Get. The empty-input behavior must be explicitly covered.
Strategy: fretish
Tags: getstring, empty
SYS-REQ-075 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getint_input_is_malformed | returns_getint_error_for_malformed
Description: When GetInt is called on malformed input where the underlying Get call returns an error, GetInt shall propagate that error to the caller.
Rationale: GetInt delegates to Get for path resolution. Malformed input errors from Get must be propagated.
Strategy: fretish
Tags: getint, malformed
SYS-REQ-076 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getint_value_overflows_int64 | returns_getint_overflow_error
Description: When GetInt addresses a JSON number token whose magnitude exceeds the int64 range, the parser shall return the documented overflow error.
Rationale: GetInt delegates to ParseInt for conversion. Overflow at int64 boundary must be propagated through GetInt.
Strategy: fretish
Tags: getint, boundary, overflow
SYS-REQ-077 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getint_addressed_value_is_not_number | returns_getint_type_mismatch_error
Description: When GetInt addresses a value that is not a JSON number (e.g., a string, boolean, object, array, or null), the parser shall return a type-mismatch error.
Rationale: GetInt has explicit type-checking logic that rejects non-number values. This is behaviorally distinct from successful integer parsing and from malformed-input errors.
Strategy: fretish
Tags: getint, type-mismatch
SYS-REQ-078 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getint_input_is_empty | returns_getint_error_for_empty_input
Description: When GetInt is called on empty input, the parser shall return the same not-found or error behavior as Get on empty input.
Rationale: Empty input to GetInt delegates to Get. The empty-input behavior must be explicitly covered.
Strategy: fretish
Tags: getint, empty
SYS-REQ-079 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getboolean_addressed_value_is_partial_literal | returns_getboolean_error_for_partial
Description: When GetBoolean addresses a value that appears to be a partial boolean literal (e.g., the addressed token is "tru" or "fals" due to truncation), the parser shall return an error from the type-classification or ParseBoolean step.
Rationale: Partial boolean literals can occur when input is truncated at a token boundary. The getType function uses tokenEnd to find the token end, and if the token is partial, it may be classified as Unknown rather than Boolean.
Strategy: fretish
Tags: getboolean, partial-literal
SYS-REQ-080 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_input_is_malformed | returns_getunsafestring_error_for_malformed
Description: When GetUnsafeString is called on malformed input where the underlying Get call returns an error, GetUnsafeString shall propagate that error to the caller.
Rationale: GetUnsafeString delegates to Get for path resolution. Malformed input errors from Get must be propagated.
Strategy: fretish
Tags: getunsafestring, malformed
SYS-REQ-081 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_input_is_empty | returns_getunsafestring_error_for_empty
Description: When GetUnsafeString is called on empty input, the parser shall return the same not-found or error behavior as Get on empty input.
Rationale: Empty input to GetUnsafeString delegates to Get. The empty-input behavior must be explicitly covered.
Strategy: fretish
Tags: getunsafestring, empty
SYS-REQ-082 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_input_is_truncated_at_value_boundary | returns_getunsafestring_error_for_truncated_value
Description: When GetUnsafeString is called on input truncated at a value boundary, the parser shall propagate the error from Get without panicking.
Rationale: GetUnsafeString delegates to Get. Truncated-at-value-boundary input must surface an error through GetUnsafeString.
Strategy: fretish
Tags: getunsafestring, truncation
SYS-REQ-083 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !arrayeach_input_is_truncated_at_value_boundary | returns_error_for_arrayeach_truncated_value
Description: When ArrayEach is called on input truncated at a value boundary where the array-containing structure ends at EOF with no delimiter, the parser shall return an error without panicking.
Rationale: ArrayEach uses Get internally for element extraction. Truncated-at-value-boundary input can trigger the same tokenEnd sentinel issues in element processing.
Strategy: fretish
Tags: arrayeach, truncation, sentinel
SYS-REQ-084 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !objecteach_input_is_truncated_mid_structure | returns_error_for_objecteach_truncated_structure
Description: When ObjectEach is called on input truncated mid-structure where the object or a nested structure is not closed, the parser shall return an error without panicking.
Rationale: ObjectEach iterates entries by calling Get for each value. Truncated mid-structure input can produce sentinel values from blockEnd that affect iteration.
Strategy: fretish
Tags: objecteach, truncation, structure
SYS-REQ-085 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !eachkey_tokenEnd_sentinel_reached | eachkey_handles_sentinel_safely
Description: When EachKey encounters a tokenEnd sentinel value (len(data)) during multi-path scanning, the parser shall treat it as an end-of-input condition and return -1 or error rather than using it as an unchecked array index.
Rationale: EachKey uses searchKeys and Get internally. The same tokenEnd sentinel patterns that caused PR
Strategy: fretish
Tags: eachkey, sentinel
SYS-REQ-086 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !get_called_twice_with_same_input | get_returns_identical_results
Description: When Get is called twice with identical JSON input and identical key paths, the parser shall return identical value slices, value types, offsets, and error values on both calls.
Rationale: Deterministic output is a fundamental property of a parser -- callers must be able to rely on repeated calls producing the same result without hidden state mutation.
Strategy: fretish
Tags: get, determinism
SYS-REQ-087 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !get_called_on_valid_input | get_does_not_mutate_input
Description: When Get is called on a JSON byte slice, the parser shall not mutate the input slice -- the input bytes before and after the call shall be identical. Get is a pure read operation.
Rationale: Idempotency of read operations means Get must not modify the caller's input buffer. Callers rely on being able to re-read the same input for other keys.
Strategy: fretish
Tags: get, idempotency
SYS-REQ-088 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !get_input_is_nil | get_returns_safe_result_for_nil
Description: When Get is called with a nil byte slice as input, the parser shall return a not-found or error result without panicking.
Rationale: Nil input is distinct from empty input and must not cause a nil-pointer dereference panic. Callers may pass nil when an upstream read fails.
Strategy: fretish
Tags: get, nil_safety
SYS-REQ-089 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !get_input_is_deeply_nested | get_handles_deep_nesting_safely
Description: When Get is called on JSON input with deeply nested structures (e.g., 64+ levels of nesting), the parser shall either return the correct result or a parse error, without panicking or stack-overflowing.
Rationale: Deeply nested JSON payloads are a known edge case that can cause stack overflows in recursive parsers. The parser must handle them safely.
Strategy: fretish
Tags: get, edge_case, deep_nesting
SYS-REQ-090 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_called_twice_with_same_input | getstring_returns_identical_results
Description: When GetString is called twice with identical JSON input and identical key paths, the parser shall return identical decoded string values and identical error values on both calls.
Rationale: Deterministic string decoding ensures callers can cache or compare GetString results reliably.
Strategy: fretish
Tags: getstring, determinism
SYS-REQ-091 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_input_is_nil | getstring_returns_safe_result_for_nil
Description: When GetString is called with a nil byte slice as input, the parser shall return an empty string and an error or not-found result without panicking.
Rationale: Nil input must not cause a nil-pointer dereference. GetString delegates to Get, so nil safety must be preserved through the delegation chain.
Strategy: fretish
Tags: getstring, nil_safety
SYS-REQ-092 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_input_has_escaped_unicode | getstring_decodes_and_preserves_semantics
Description: When GetString is called on a JSON string containing escaped Unicode sequences (e.g., \u00e9, \uD83D\uDE00), the parser shall decode them to the correct Go string runes, preserving round-trip semantic equivalence with the original Unicode codepoints.
Rationale: Encoding safety ensures that escaped Unicode in JSON is faithfully decoded to Go strings. This is critical for internationalized payloads.
Strategy: fretish
Tags: getstring, encoding_safety, unicode
SYS-REQ-093 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getstring_input_has_unicode_edge_cases | getstring_handles_unicode_edges_safely
Description: When GetString is called on JSON containing Unicode edge cases such as BOM characters, zero-width joiners, or multi-byte sequences at string boundaries, the parser shall decode correctly or return a well-defined error without panicking.
Rationale: Unicode edge cases (BOM, ZWJ, emoji sequences) are common in real-world JSON from international APIs and must not cause undefined behavior.
Strategy: fretish
Tags: getstring, edge_case, unicode
SYS-REQ-094 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !typed_getter_called_twice_with_same_input | typed_getter_returns_identical_results
Description: When GetInt, GetFloat, or GetBoolean is called twice with identical JSON input and identical key paths, the parser shall return identical typed values and identical error values on both calls.
Rationale: Typed accessor helpers compose Get with Parse* and must preserve determinism through the composition chain.
Strategy: fretish
Tags: getint, getfloat, getboolean, determinism
SYS-REQ-095 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !typed_getter_input_is_nil | typed_getter_returns_safe_result_for_nil
Description: When GetInt, GetFloat, or GetBoolean is called with a nil byte slice as input, the parser shall return a zero value and an error or not-found result without panicking.
Rationale: Nil input must be handled safely throughout all typed accessor paths without nil-pointer panics.
Strategy: fretish
Tags: getint, getfloat, getboolean, nil_safety
SYS-REQ-096 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getint_input_has_large_number_edge_case | getint_handles_large_numbers_safely
Description: When GetInt is called on JSON containing numeric edge cases such as numbers with many leading zeros, maximum-length digit strings, or values at float64 precision boundaries, the parser shall return a correct int64 result or a well-defined error without panicking.
Rationale: Large and edge-case numbers in JSON are common in financial and scientific APIs. The parser must not silently truncate or corrupt these values.
Strategy: fretish
Tags: getint, edge_case, large_numbers
SYS-REQ-097 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !traversal_called_twice_with_same_input | traversal_returns_identical_results
Description: When ArrayEach, ObjectEach, or EachKey is called twice with identical JSON input and identical parameters, the parser shall invoke callbacks in the same order with the same values on both calls.
Rationale: Traversal determinism ensures callers can rely on stable iteration order and consistent callback invocations across repeated calls.
Strategy: fretish
Tags: arrayeach, objecteach, eachkey, determinism
SYS-REQ-098 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !traversal_input_is_nil | traversal_returns_safe_result_for_nil
Description: When ArrayEach, ObjectEach, or EachKey is called with a nil byte slice as input, the parser shall return an error without invoking any callbacks and without panicking.
Rationale: Nil input to traversal helpers must not cause nil-pointer dereference panics. The callback must never be invoked on nil input.
Strategy: fretish
Tags: arrayeach, objecteach, eachkey, nil_safety
SYS-REQ-099 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !traversal_input_is_deeply_nested | traversal_handles_deep_nesting_safely
Description: When ArrayEach or ObjectEach is called on JSON with deeply nested structures (64+ levels), the parser shall traverse correctly or return a parse error without panicking or stack-overflowing.
Rationale: Deeply nested JSON in traversal is an edge case that can cause stack overflows. The parser must handle it safely.
Strategy: fretish
Tags: arrayeach, objecteach, edge_case, deep_nesting
SYS-REQ-100 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !set_applied_twice_with_same_args | set_second_call_produces_same_result
Description: When Set is called twice on the same input with the same value and key path, the second call shall produce the same output as applying Set once -- the operation is idempotent for existing keys.
Rationale: Set idempotency for existing keys means callers can safely retry mutations without checking whether the first call succeeded. This is important for at-least-once delivery patterns.
Strategy: fretish
Tags: set, idempotency
SYS-REQ-101 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !mutation_input_is_nil | mutation_returns_safe_result_for_nil
Description: When Set or Delete is called with a nil byte slice as input, the parser shall return an error (Set) or the nil/empty slice unchanged (Delete) without panicking.
Rationale: Nil input to mutation helpers must not cause nil-pointer dereference panics. Callers may pass nil when constructing JSON from scratch or when upstream reads fail.
Strategy: fretish
Tags: set, delete, nil_safety
SYS-REQ-102 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !mutation_input_has_unicode_keys | mutation_handles_unicode_keys_safely
Description: When Set or Delete is called with key paths containing Unicode characters, the parser shall correctly resolve the path and perform the mutation or return a well-defined error without panicking.
Rationale: JSON object keys can be arbitrary Unicode strings. Mutation helpers must handle non-ASCII key paths without corrupting the document.
Strategy: fretish
Tags: set, delete, edge_case, unicode
SYS-REQ-103 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_called_twice_with_same_input | getunsafestring_returns_identical_results
Description: When GetUnsafeString is called twice with identical JSON input and identical key paths, the parser shall return identical raw string values and identical error values on both calls.
Rationale: GetUnsafeString must be deterministic even though it skips unescaping. The same input must always produce the same raw string view.
Strategy: fretish
Tags: getunsafestring, determinism
SYS-REQ-104 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_input_is_nil | getunsafestring_returns_safe_result_for_nil
Description: When GetUnsafeString is called with a nil byte slice as input, the parser shall return an empty string and an error or not-found result without panicking.
Rationale: Nil input must be handled safely through the GetUnsafeString delegation chain to Get.
Strategy: fretish
Tags: getunsafestring, nil_safety
SYS-REQ-105 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !getunsafestring_input_has_unicode_edge_cases | getunsafestring_handles_unicode_edges_safely
Description: When GetUnsafeString is called on JSON containing values with Unicode edge cases (BOM, ZWJ, multi-byte sequences), the parser shall return the raw bytes as a Go string without corruption or panic, even though unescaping is skipped.
Rationale: GetUnsafeString returns raw bytes as a Go string. Multi-byte sequences at value boundaries must not cause slice-out-of-bounds panics.
Strategy: fretish
Tags: getunsafestring, edge_case, unicode
SYS-REQ-106 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parse_helper_called_twice_with_same_input | parse_helper_returns_identical_results
Description: When ParseBoolean, ParseInt, ParseFloat, or ParseString is called twice with identical byte input, the parser shall return identical typed values and identical error values on both calls.
Rationale: Parse helpers are pure functions converting byte tokens to Go values. They must be deterministic to support caching and comparison.
Strategy: fretish
Tags: parseboolean, parseint, parsefloat, parsestring, determinism
SYS-REQ-107 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parse_helper_input_is_nil | parse_helper_returns_safe_result_for_nil
Description: When ParseBoolean, ParseInt, ParseFloat, or ParseString is called with a nil byte slice, the parser shall return a zero value and an error (or empty string for ParseString) without panicking.
Rationale: Nil input to parse helpers must not cause nil-pointer panics. The helpers must gracefully handle nil as an empty-input variant.
Strategy: fretish
Tags: parseboolean, parseint, parsefloat, parsestring, nil_safety
SYS-REQ-108 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parsestring_input_has_standard_escapes | parsestring_roundtrip_preserves_semantics
Description: When ParseString is called on a byte slice containing standard JSON escape sequences (backslash-n, backslash-t, double backslash, backslash-solidus, backslash-doublequote, backslash-uXXXX), the decoded Go string shall contain the correct Unicode codepoints such that re-encoding to JSON would produce semantically equivalent escape sequences.
Rationale: Encoding safety for ParseString ensures that the decode path does not lose information. The decoded string must represent the same semantic content as the original JSON encoding.
Strategy: fretish
Tags: parsestring, encoding_safety
SYS-REQ-109 approved shall Guarantee DAL-E
FRETish: the parser shall always satisfy !parseint_input_has_edge_case_number | parseint_handles_edge_numbers_safely
Description: When ParseInt is called on edge-case numeric tokens such as negative zero, very long digit strings (100+ digits), or numbers with unusual but valid formatting, the parser shall return a correct int64 value or a well-defined overflow/malformed error without panicking.
Rationale: Edge-case numeric tokens stress the integer parsing logic and must produce correct results or well-defined errors rather than undefined behavior.
Strategy: fretish
Tags: parseint, edge_case, large_numbers
SYS-REQ-110 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !set_targets_array_index_beyond_length | set_appends_value_at_array_end
Description: When Set targets an array-index path component [N] where N >= the current length of the addressed array, the parser shall append the value at the end of the array (index becomes len(array)) and return the mutated document, rather than overwriting existing elements or panicking. This contract applies regardless of the existing array's element types (scalars, objects, nested arrays, mixed); the previous implementation only honored it when the first element was an object, silently replacing scalar arrays — fixed (DEFECT-260727-WWWY).
Rationale: Set on an array-index beyond current length was underspecified; PR #286 found it silently overwrites element 0, destroying data the caller did not address. The append-at-end contract must be explicit so the overwrite path can never regress.
Strategy: fretish
Tags: set, array_index, boundary, beyond_length
References:
SYS-REQ-111 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !path_component_is_empty_string | (returns_not_found_for_empty_key_component & completes_without_panic_on_empty_key_component)
Description: When any key path component is the empty string, the parser shall treat the path as unresolvable and return KeyPathNotFoundError (Get family / Delete) or a defined error (Set), and shall never panic. An empty-string component is neither a valid object key nor the [ array-index marker.
Rationale: Empty-string key components previously reached unguarded keys[i][0] / p[level][0] dereferences and panicked (OSS-Fuzz 4649128545288192 / hazard-sweep class, DEFECT-260726-QS2V, KI-1). The contract that an empty-string component is an invalid path returning KeyPathNotFoundError must be explicit so no future code reintroduces a panic site.
Strategy: fretish
Tags: path, empty_key, missing_path, nil_safety
References:
SYS-REQ-112 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy !addressed_container_is_array_or_object | returns_container_element_count
Description: GetArrayLen returns the number of elements in the addressed JSON array (0 for an empty array), and GetObjectLen returns the number of key-value pairs in the addressed JSON object (0 for an empty object). Both helpers address the container by key path without invoking a caller callback, returning KeyPathNotFoundError when the path is missing and MalformedArrayError / MalformedObjectError when the addressed value is not the expected container type.
Rationale: Existing ArrayEach/ObjectEach iteration APIs force the caller to provide a callback that runs per element; callers who only need the count pay callback overhead and must carry mutation hazards in the callback closure. A direct length accessor closes the gap as a v1.4.0 exported helper.
Strategy: fretish
Tags: container_length, array, object, boundary, malformed_input
SYS-REQ-113 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy wildcard_path_resolves_to_every_matched_element
Description: EachKeyWildcard, ArrayEachWildcard, and SetWildcard accept [*] as a wildcard array-index component that fans out over every element of the addressed array. EachKeyWildcard invokes the callback once per matched combination in document order; ArrayEachWildcard iterates an array addressed by a path that may end in [*]; SetWildcard applies Set to every concrete path produced by expanding all [*] components. Multiple wildcards compose by cartesian fan-out. If a wildcard addresses a non-array container the parser returns MalformedArrayError; an empty matched array is a no-op (SetWildcard returns data unchanged, EachKeyWildcard invokes no callback).
Rationale: v1.4.0 introduces [*] wildcard path components so library users can fan out over array elements without pre-walking the JSON; the contract must be explicit so future refactors preserve document order, multi-wildcard composition, and the no-panic-on-non-array guarantee.
Strategy: fretish
Tags: wildcard, path, array, each_key, set, nominal, boundary, malformed_input
SYS-REQ-114 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path
Description: ParsePath converts a JSONPath-style string (root $. optionally followed by dot-delimited keys, [N] numeric array-index bracket components, [*] wildcard, and "quoted" keys containing dots or brackets) into the path-component slice accepted by Get/Set/Delete/ArrayEach/EachKey. CompilePath parses the path once and returns a CompiledPath value whose Get/GetString/GetInt/Set/Delete/ArrayEach/EachKey methods behave identically to invoking the equivalent top-level function with the parsed components. ParsePath returns errEmptyPath for an empty input and errMalformedPath for any non-conforming syntax (unbalanced bracket, missing key between dots, control character in quoted key, non-numeric bracket index other than *).
Rationale: v1.4.0 exposes a JSONPath compiler so callers can amortize the cost of parsing a path string across many Get/Set/Delete operations and so external callers can express bracket-index paths without hand-assembling [N] tokens. The contract that CompiledPath methods are observationally equivalent to the equivalent top-level function must be explicit so future refactors do not diverge the compiled and uncompiled code paths.
Strategy: fretish
Tags: jsonpath, compiler, path, parse, nominal, boundary, malformed_input
SYS-REQ-115 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy config_lenient_modes_are_opt_in_and_default_remains_strict
Description: When a Config with AllowSingleQuotes=true is provided, the parser shall accept single-quoted strings (delimited by ' instead of ") using the same escape rules as double-quoted strings. When AllowUnknownEscapes=true, unknown escape sequences shall be passed through literally instead of returning an error. The default Config shall remain strict (RFC 8259 only).
Rationale: v1.5.0 introduces explicit opt-in compatibility modes for common non-RFC JSON emitted by external systems while preserving the strict behavior and API contracts of every existing package-level function.
Strategy: fretish
Tags: config, lenient, single_quotes, escapes, nominal, malformed_input, encoding_safety
SYS-REQ-116 approved shall Guarantee DAL-B
FRETish: the parser shall always satisfy reader_parser_provides_incremental_stream_access
Description: A ReaderParser shall provide path-based access to JSON data from an io.Reader stream, supporting Get, GetString, and ArrayEach without requiring the entire document to be loaded into memory. The parser shall buffer data incrementally and yield values as they are found.
Rationale: Large JSON documents can exceed available memory even when callers need only one path or need to process array elements sequentially. ReaderParser preserves jsonparser's path-based access model while bounding retained stream data to the current window or value.
Strategy: fretish
Tags: streaming, io_reader, incremental, nominal, boundary, empty_input, malformed_input

5. Verification Status Matrix

Req ID Assurance Formalization Realizability Consistency Vacuity Code Coverage Documented Review
STK-REQ-001 E none Unchecked Unchecked — — approved
STK-REQ-002 E none Unchecked Unchecked — — approved
STK-REQ-003 E none Unchecked Unchecked — — approved
STK-REQ-004 E none Unchecked Unchecked — — approved
STK-REQ-005 E none Unchecked Unchecked — — approved
STK-REQ-006 E none Unchecked Unchecked — — approved
STK-REQ-007 E none Unchecked Unchecked — — approved
SYS-REQ-001 B valid Unchecked Unchecked — — approved
SYS-REQ-002 E valid Unchecked Unchecked — — approved
SYS-REQ-003 E valid Unchecked Unchecked — — approved
SYS-REQ-004 E valid Unchecked Unchecked — — approved
SYS-REQ-005 E valid Unchecked Unchecked — — approved
SYS-REQ-006 E valid Unchecked Unchecked — — approved
SYS-REQ-007 E valid Unchecked Unchecked — — approved
SYS-REQ-008 E valid Unchecked Unchecked — — approved
SYS-REQ-009 E valid Unchecked Unchecked — — approved
SYS-REQ-010 E valid Unchecked Unchecked — — approved
SYS-REQ-011 E valid Unchecked Unchecked — — approved
SYS-REQ-012 E valid Unchecked Unchecked — — approved
SYS-REQ-013 E valid Unchecked Unchecked — — approved
SYS-REQ-014 E valid Unchecked Unchecked — — approved
SYS-REQ-015 E valid Unchecked Unchecked — — approved
SYS-REQ-016 B valid Unchecked Unchecked — — approved
SYS-REQ-017 B valid Unchecked Unchecked — — approved
SYS-REQ-018 B valid Unchecked Unchecked — — approved
SYS-REQ-019 B valid Unchecked Unchecked — — approved
SYS-REQ-020 B valid Unchecked Unchecked — — approved
SYS-REQ-021 B valid Unchecked Unchecked — — approved
SYS-REQ-022 B valid Unchecked Unchecked — — approved
SYS-REQ-023 B valid Unchecked Unchecked — — approved
SYS-REQ-024 B valid Unchecked Unchecked — — approved
SYS-REQ-025 B valid Unchecked Unchecked — — approved
SYS-REQ-026 B valid Unchecked Unchecked — — approved
SYS-REQ-027 B valid Unchecked Unchecked — — approved
SYS-REQ-028 E valid Unchecked Unchecked — — approved
SYS-REQ-029 E valid Unchecked Unchecked — — approved
SYS-REQ-030 E valid Unchecked Unchecked — — approved
SYS-REQ-031 E valid Unchecked Unchecked — — approved
SYS-REQ-032 E valid Unchecked Unchecked — — approved
SYS-REQ-033 E valid Unchecked Unchecked — — approved
SYS-REQ-034 E valid Unchecked Unchecked — — approved
SYS-REQ-035 E valid Unchecked Unchecked — — approved
SYS-REQ-036 E valid Unchecked Unchecked — — approved
SYS-REQ-037 E valid Unchecked Unchecked — — approved
SYS-REQ-038 E valid Unchecked Unchecked — — approved
SYS-REQ-039 E valid Unchecked Unchecked — — approved
SYS-REQ-040 E valid Unchecked Unchecked — — approved
SYS-REQ-041 E valid Unchecked Unchecked — — approved
SYS-REQ-042 E valid Unchecked Unchecked — — approved
SYS-REQ-043 E valid Unchecked Unchecked — — approved
SYS-REQ-044 E valid Unchecked Unchecked — — approved
SYS-REQ-045 E valid Unchecked Unchecked — — approved
SYS-REQ-046 E valid Unchecked Unchecked — — approved
SYS-REQ-047 E valid Unchecked Unchecked — — approved
SYS-REQ-048 E valid Unchecked Unchecked — — approved
SYS-REQ-049 E valid Unchecked Unchecked — — approved
SYS-REQ-050 E valid Unchecked Unchecked — — approved
SYS-REQ-051 E valid Unchecked Unchecked — — approved
SYS-REQ-052 E valid Unchecked Unchecked — — approved
SYS-REQ-053 E valid Unchecked Unchecked — — approved
SYS-REQ-054 E valid Unchecked Unchecked — — approved
SYS-REQ-055 E valid Unchecked Unchecked — — approved
SYS-REQ-056 E valid Unchecked Unchecked — — approved
SYS-REQ-057 E valid Unchecked Unchecked — — approved
SYS-REQ-058 E valid Unchecked Unchecked — — approved
SYS-REQ-059 E valid Unchecked Unchecked — — approved
SYS-REQ-060 E valid Unchecked Unchecked — — approved
SYS-REQ-061 E valid Unchecked Unchecked — — approved
SYS-REQ-062 E valid Unchecked Unchecked — — approved
SYS-REQ-063 E valid Unchecked Unchecked — — approved
SYS-REQ-064 E valid Unchecked Unchecked — — approved
SYS-REQ-065 E valid Unchecked Unchecked — — approved
SYS-REQ-066 E valid Unchecked Unchecked — — approved
SYS-REQ-067 E valid Unchecked Unchecked — — approved
SYS-REQ-068 E valid Unchecked Unchecked — — approved
SYS-REQ-069 E valid Unchecked Unchecked — — approved
SYS-REQ-070 E valid Unchecked Unchecked — — approved
SYS-REQ-071 E valid Unchecked Unchecked — — approved
SYS-REQ-072 E valid Unchecked Unchecked — — approved
SYS-REQ-073 E valid Unchecked Unchecked — — approved
SYS-REQ-074 E valid Unchecked Unchecked — — approved
SYS-REQ-075 E valid Unchecked Unchecked — — approved
SYS-REQ-076 E valid Unchecked Unchecked — — approved
SYS-REQ-077 E valid Unchecked Unchecked — — approved
SYS-REQ-078 E valid Unchecked Unchecked — — approved
SYS-REQ-079 E valid Unchecked Unchecked — — approved
SYS-REQ-080 E valid Unchecked Unchecked — — approved
SYS-REQ-081 E valid Unchecked Unchecked — — approved
SYS-REQ-082 E valid Unchecked Unchecked — — approved
SYS-REQ-083 E valid Unchecked Unchecked — — approved
SYS-REQ-084 E valid Unchecked Unchecked — — approved
SYS-REQ-085 E valid Unchecked Unchecked — — approved
SYS-REQ-086 E valid Unchecked Unchecked — — approved
SYS-REQ-087 E valid Unchecked Unchecked — — approved
SYS-REQ-088 E valid Unchecked Unchecked — — approved
SYS-REQ-089 E valid Unchecked Unchecked — — approved
SYS-REQ-090 E valid Unchecked Unchecked — — approved
SYS-REQ-091 E valid Unchecked Unchecked — — approved
SYS-REQ-092 E valid Unchecked Unchecked — — approved
SYS-REQ-093 E valid Unchecked Unchecked — — approved
SYS-REQ-094 E valid Unchecked Unchecked — — approved
SYS-REQ-095 E valid Unchecked Unchecked — — approved
SYS-REQ-096 E valid Unchecked Unchecked — — approved
SYS-REQ-097 E valid Unchecked Unchecked — — approved
SYS-REQ-098 E valid Unchecked Unchecked — — approved
SYS-REQ-099 E valid Unchecked Unchecked — — approved
SYS-REQ-100 E valid Unchecked Unchecked — — approved
SYS-REQ-101 E valid Unchecked Unchecked — — approved
SYS-REQ-102 E valid Unchecked Unchecked — — approved
SYS-REQ-103 E valid Unchecked Unchecked — — approved
SYS-REQ-104 E valid Unchecked Unchecked — — approved
SYS-REQ-105 E valid Unchecked Unchecked — — approved
SYS-REQ-106 E valid Unchecked Unchecked — — approved
SYS-REQ-107 E valid Unchecked Unchecked — — approved
SYS-REQ-108 E valid Unchecked Unchecked — — approved
SYS-REQ-109 E valid Unchecked Unchecked — — approved
SYS-REQ-110 B valid Unchecked Unchecked — — approved
SYS-REQ-111 B valid Unchecked Unchecked — — approved
SYS-REQ-112 B valid Unchecked Unchecked — — approved
SYS-REQ-113 B valid Unchecked Unchecked — — approved
SYS-REQ-114 B valid Unchecked Unchecked — — approved
SYS-REQ-115 B valid Unchecked Unchecked — — approved
SYS-REQ-116 B valid Unchecked Unchecked — — approved

6. Traceability

6.1 Coverage Summary (Per-Component Heat Map)

This table shows test coverage for each component's guarantee requirements. Color-coded: green = 80%+, amber = 40-79%, red = <40%.

Component Total Reqs Guarantees Tested Test Coverage Code Coverage Documented Gaps Suspect
parser 123 123 0 0% — 0% 20 0

Note: Test coverage reflects FLIP/MC-DC verified_by links. Assumptions and constraints are verified through consistency checking and integration analysis, not through FLIP test fixtures. Parent (satisfies) links apply only to cross-component integration requirements. Implementation (implemented_by) links to source code are optional traceability.

6.1b Cross-Level Traceability

Per-level coverage showing upward and downward traceability across the specification hierarchy.

Level Spec Prefix Total Reqs Upward Traces Downward Traces Coverage
L0 specs/stakeholder STK-REQ 7 0 7 100%
L1 specs/system SYS-REQ 116 116 0 100%

Cross-Level Link Summary

From LevelFrom SpecTo LevelTo SpecLinks
L1 specs/system L0 specs/stakeholder 122

6.2 Traceability Gaps

This section highlights requirements with missing traceability links. Requirements that are fully traced are omitted — only gaps are shown. If this section is empty, all requirements are fully traced.

SYS-REQ-001 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-016 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-017 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-018 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-019 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-020 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-021 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-022 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-023 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-024 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-025 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-026 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-027 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-110 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-111 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-112 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-113 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-114 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-115 required guarantee — missing test link
guarantee requirement missing verified_by trace
SYS-REQ-116 required guarantee — missing test link
guarantee requirement missing verified_by trace

7. Gap Analysis Summary

123
Total Requirements
94%
Parent Traceability
0%
Test Traceability
0%
Implementation Traceability

Identified Gaps (Missing Links Only)

Only requirements missing expected links are shown below. This gap-focused view highlights what needs action rather than listing all links.

Req IDTypeMissingSeverityMessage
SYS-REQ-001 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-016 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-017 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-018 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-019 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-020 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-021 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-022 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-023 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-024 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-025 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-026 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-027 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-110 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-111 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-112 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-113 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-114 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-115 guarantee test required guarantee requirement missing verified_by trace
SYS-REQ-116 guarantee test required guarantee requirement missing verified_by trace

8. Appendices

8.1 Variable Definitions

parser

NameTypeDirectionDescriptionUnits
json_input_is_well_formed bool input True when the provided JSON byte slice is well formed for the lookup case under evaluation.
addressed_path_exists bool input True when the requested key path resolves to a value in the JSON input under evaluation.
key_path_is_provided bool input True when the caller supplies at least one key-path segment for the lookup case under evaluation.
json_input_is_empty bool input True when the provided lookup input is empty.
input_is_incomplete_during_lookup bool input True when the input is truncated or incomplete before Get can complete the addressed lookup.
returns_existing_path_lookup_result bool output True when Get returns the addressed value, value type, end offset, and no error for a well-formed existing path lookup.
returns_missing_path_result_for_well_formed_lookup bool output True when Get reports the defined not-found outcome for a well-formed lookup whose addressed path does not exist.
returns_parse_error_for_incomplete_lookup bool output True when Get reports a parse-related error for an incomplete or truncated lookup input.
returns_root_value_without_key_path bool output True when Get returns the closest complete root JSON value for a well-formed input when no key path is provided.
returns_missing_path_result_for_empty_input bool output True when Get reports the defined not-found outcome for an empty input with a provided key path.
path_segment_is_object_key bool input True when the current lookup path segment is interpreted as an object-member key rather than as an array index.
segment_is_evaluated_at_current_scope bool input True when the current lookup segment is being matched against the current JSON structural scope rather than against a sibling or deeper subtree.
path_segment_is_array_index bool input True when the current lookup path segment is interpreted as an array index.
array_index_segment_is_valid bool input True when the current array-index path segment has valid index syntax.
array_index_is_in_bounds bool input True when the addressed array index is within the bounds of the addressed array.
array_index_is_out_of_bounds bool input True when the addressed array index exceeds the bounds of the addressed array.
escaped_json_object_key_is_present bool input True when the addressed object member key is encoded with JSON escape sequences in the payload.
decoded_path_segment_matches_escaped_key bool input True when the decoded lookup path segment matches the logical value of an escaped JSON object key.
addressed_value_is_string bool input True when the addressed successful lookup value is a JSON string token.
addressed_value_is_number bool input True when the addressed value is a JSON number token.
addressed_value_is_boolean bool input True when the addressed value is a JSON boolean token.
returns_value_from_current_scope_object_key bool output True when Get resolves the requested object-member path segment only against the current structural scope and returns that value.
returns_value_from_in_bounds_array_index bool output True when Get resolves a valid in-bounds array-index path segment and returns the addressed element.
returns_invalid_array_index_not_found bool output True when Get reports the defined not-found outcome for a malformed array-index path segment.
returns_oob_array_index_not_found bool output True when Get reports the defined not-found outcome for a valid but out-of-bounds array index.
returns_value_from_decoded_escaped_key bool output True when Get resolves an escaped JSON object key by comparing the decoded path segment to the logical key value.
returns_unquoted_raw_string_contents bool output True when Get returns JSON string contents without surrounding quotes and without JSON unescaping.
malformed_input_outside_addressed_token bool input True when malformed JSON appears outside the addressed token path rather than inside the token that lookup is trying to return.
addressed_token_can_be_isolated bool input True when Get can still isolate a complete addressed token or determine lookup absence despite malformed input elsewhere in the document.
returns_best_effort_lookup_result bool output True when Get preserves the corresponding success or not-found lookup result despite malformed input outside the addressed token path.
addressed_token_shape_is_invalid bool input True when the addressed token cannot be classified as string, object, array, number, boolean, or null.
returns_value_type_error bool output True when Get returns a value-type classification error for an invalid addressed token shape.
raw_string_token_is_well_formed bool input True when the addressed raw JSON string token is well formed and can be decoded.
returns_getstring_decoded_value bool output True when GetString returns the addressed value as a decoded Go string.
raw_number_token_is_integer_parseable bool input True when the addressed JSON number token can be parsed as an int64 value.
returns_getint_value bool output True when GetInt returns the addressed value as an int64.
raw_number_token_is_float_parseable bool input True when the addressed JSON number token can be parsed as a float64 value.
returns_getfloat_value bool output True when GetFloat returns the addressed value as a float64.
raw_boolean_token_is_well_formed bool input True when the addressed JSON boolean token is a valid `true` or `false` literal.
returns_getboolean_value bool output True when GetBoolean returns the addressed value as a Go bool.
addressed_array_is_well_formed bool input True when ArrayEach is operating on a well-formed addressed JSON array.
addressed_array_is_empty bool input True when ArrayEach is operating on an addressed array that contains no elements.
array_callback_receives_elements_in_order bool output True when ArrayEach invokes the callback for each addressed array element in encounter order.
empty_array_produces_no_callbacks bool output True when ArrayEach emits no callbacks for a well-formed empty addressed array.
malformed_array_input_returns_error bool output True when ArrayEach returns an error for malformed or unusable array input.
addressed_object_is_well_formed bool input True when ObjectEach is operating on a well-formed addressed JSON object.
addressed_object_is_empty bool input True when ObjectEach is operating on an addressed object that contains no entries.
object_callback_receives_entries bool output True when ObjectEach invokes the callback with the correct key, value, and value-type tuple for each addressed object entry.
object_callback_error_is_returned bool output True when ObjectEach returns an error produced by the callback instead of swallowing it.
empty_object_produces_no_entries bool output True when ObjectEach emits no entry callbacks for a well-formed empty addressed object.
malformed_object_input_returns_error bool output True when ObjectEach returns an error for malformed or unusable addressed object input.
object_callback_returns_error bool input True when the callback supplied to ObjectEach returns an error during iteration.
multipath_requests_are_provided bool input True when EachKey is called with one or more requested key paths.
eachkey_callback_receives_found_values bool output True when EachKey invokes the callback with the value and type for each requested path that is found during the scan.
missing_multipath_request_does_not_emit_callback bool output True when EachKey does not emit a found-value callback for a requested path that is absent.
eachkey_malformed_input_returns_error bool output True when EachKey surfaces an error for malformed or unusable input during the scan.
eachkey_completes_requested_scan bool output True when EachKey completes the requested multi-path scan and stops once the requested results have been determined.
set_path_is_provided bool input True when Set is called with at least one mutation path segment.
set_target_exists bool input True when the full addressed Set path already exists in the input JSON.
set_creates_missing_path bool output True when Set creates the missing addressed path inside a valid target container.
set_returns_updated_document bool output True when Set returns the updated JSON document for the addressed mutation case.
set_returns_not_found_error bool output True when Set returns `KeyPathNotFoundError` because the requested mutation path is not usable for the provided input.
delete_path_is_provided bool input True when Delete is called with at least one path segment.
delete_returns_empty_document_without_path bool output True when Delete returns an empty byte slice because no path segment was provided.
delete_target_exists bool input True when the addressed Delete target exists and can be isolated in the input JSON.
delete_input_is_unusable_for_requested_path bool input True when Delete cannot safely resolve the requested path because the input is malformed, truncated, or otherwise unusable for that deletion request.
delete_returns_document_without_target bool output True when Delete returns the JSON document with the addressed value removed.
delete_preserves_input_when_target_missing bool output True when Delete leaves the input unchanged because the addressed target is missing in otherwise usable input.
delete_returns_original_input_on_unusable_input bool output True when Delete returns the original byte payload unchanged because the input is unusable for the requested deletion.
delete_completes_without_panic bool output True when Delete completes the requested call path without panicking.
returns_unsafe_string_view bool output True when GetUnsafeString returns the addressed raw value bytes mapped directly as a Go string without JSON unescaping.
raw_boolean_literal_is_valid bool input True when ParseBoolean receives a valid boolean literal token.
returns_parseboolean_value bool output True when ParseBoolean returns the corresponding Go bool value.
returns_parseboolean_error bool output True when ParseBoolean returns the documented malformed-value error for an invalid boolean token.
raw_float_token_is_well_formed bool input True when ParseFloat receives a well-formed floating-point number token.
returns_parsefloat_value bool output True when ParseFloat returns the corresponding float64 value.
returns_parsefloat_error bool output True when ParseFloat returns the documented malformed-value error for a malformed numeric token.
raw_string_literal_is_well_formed bool input True when ParseString receives a well-formed raw JSON string literal body.
returns_parsestring_value bool output True when ParseString returns the corresponding decoded Go string value.
returns_parsestring_error bool output True when ParseString returns the documented malformed-value error for a malformed encoded string literal.
raw_int_token_is_well_formed bool input True when ParseInt receives a syntactically well-formed integer token that does not overflow int64.
raw_int_token_overflows_int64 bool input True when ParseInt receives an integer token whose magnitude exceeds the supported int64 range.
returns_parseint_value bool output True when ParseInt returns the corresponding int64 value.
returns_parseint_overflow_error bool output True when ParseInt returns the documented overflow error for an integer token outside the supported int64 range.
returns_parseint_malformed_error bool output True when ParseInt returns the documented malformed-value error for a non-integer or otherwise malformed token.
input_is_truncated_at_value_boundary bool input True when the JSON input is truncated at a value boundary where the value token ends at EOF with no closing delimiter (e.g., '{"a":1' with no closing brace).
returns_error_for_truncated_value_boundary bool output True when Get returns a parse-related error or not-found result for input truncated at a value boundary, without panicking.
input_is_truncated_mid_structure bool input True when the JSON input is truncated in the middle of a structural element where an object or array is opened but never closed.
returns_error_for_truncated_mid_structure bool output True when Get returns a parse-related error for input truncated mid-structure, without panicking.
input_is_truncated_mid_key bool input True when the JSON input is truncated in the middle of a key string where the key is not terminated by a closing quote.
returns_error_for_truncated_mid_key bool output True when Get returns a parse-related error for input truncated mid-key, without panicking.
tokenEnd_returns_len_data bool input True when the internal helper tokenEnd returns len(data) as a sentinel value indicating no delimiter was found in the remaining input.
caller_bounds_checks_tokenEnd_sentinel bool output True when all callers of tokenEnd treat the len(data) sentinel as an end-of-input condition and do not use it as an unchecked array index.
stringEnd_returns_negative_one bool input True when the internal helper stringEnd returns -1 indicating no closing quote was found.
caller_handles_stringEnd_sentinel bool output True when all callers of stringEnd treat -1 as a malformed-string condition and do not proceed with normal value extraction.
blockEnd_returns_negative_one bool input True when the internal helper blockEnd returns -1 indicating no matching closing bracket or brace was found.
caller_handles_blockEnd_sentinel bool output True when all callers of blockEnd treat -1 as a malformed-structure condition and do not proceed with normal value extraction.
path_segment_is_negative_array_index bool input True when the current path segment is a negative array index such as "[-1]".
returns_not_found_for_negative_array_index bool output True when Get returns the defined not-found result for a negative array index because negative indexing is not supported.
delete_input_is_truncated_at_value_boundary bool input True when Delete is called on input truncated at a value boundary where tokenEnd would return len(data) as a sentinel.
delete_returns_original_input_on_truncated_value bool output True when Delete returns the original byte payload unchanged for input truncated at a value boundary.
delete_completes_without_panic_on_truncated_value bool output True when Delete completes without panicking on input truncated at a value boundary.
delete_discards_internalGet_error bool input True when Delete discards an error returned by internalGet (assigns to underscore) instead of using it to short-circuit.
delete_propagates_internalGet_error bool output True when Delete uses an error returned by internalGet to short-circuit to the safe fallback path.
delete_array_input_is_truncated bool input True when Delete is called with an array-element path on input where the array is truncated.
delete_returns_original_input_on_truncated_array bool output True when Delete returns the original byte payload unchanged for truncated array input.
delete_completes_without_panic_on_truncated_array bool output True when Delete completes without panicking on truncated array input.
set_input_is_truncated bool input True when Set is called on truncated JSON input where path resolution encounters incomplete structural elements.
set_returns_error_for_truncated_input bool output True when Set returns an error for truncated input rather than producing corrupt output or panicking.
array_callback_returns_error bool input True when the Get call for an array element within ArrayEach returns an error.
array_callback_error_is_propagated bool output True when ArrayEach propagates the element-level Get error to the caller.
array_is_truncated_mid_element bool input True when ArrayEach encounters an array element that is truncated or incomplete.
returns_error_for_truncated_array_element bool output True when ArrayEach returns a parse-related error for a truncated array element, without panicking.
object_is_truncated_mid_entry bool input True when ObjectEach encounters an object entry whose value is truncated or incomplete.
returns_error_for_truncated_object_entry bool output True when ObjectEach returns a parse-related error for a truncated object entry, without panicking.
array_has_malformed_delimiter bool input True when ArrayEach encounters a malformed delimiter between array elements where a comma is expected but absent or wrong.
returns_error_for_malformed_array_delimiter bool output True when ArrayEach returns MalformedArrayError for a malformed delimiter between array elements.
delete_input_is_truncated_mid_structure bool input True when Delete is called on input truncated mid-structure with unclosed nested objects or arrays.
delete_returns_original_input_on_truncated_structure bool output True when Delete returns the original byte payload unchanged for mid-structure truncated input.
delete_completes_without_panic_on_truncated_structure bool output True when Delete completes without panicking on mid-structure truncated input.
raw_boolean_literal_is_partial bool input True when ParseBoolean receives a partial boolean literal such as "tru" or "fals".
returns_error_for_partial_boolean_literal bool output True when ParseBoolean returns MalformedValueError for a partial boolean literal.
raw_int_token_is_at_int64_max_boundary bool input True when ParseInt receives an integer token at the exact int64 boundary values (max 9223372036854775807 or min -9223372036854775808).
returns_correct_value_at_int64_boundary bool output True when ParseInt returns the correct int64 value at the exact boundary without overflow error.
raw_int_token_is_at_int64_max_plus_one bool input True when ParseInt receives an integer token exactly one beyond the int64 range (9223372036854775808 or -9223372036854775809).
returns_overflow_at_int64_max_plus_one bool output True when ParseInt returns OverflowIntegerError for an integer token exactly one beyond the int64 range.
raw_string_has_truncated_escape_sequence bool input True when ParseString receives a string containing a truncated escape sequence such as a lone backslash or incomplete unicode escape like '\u00'.
returns_error_for_truncated_escape_sequence bool output True when ParseString returns MalformedValueError for a truncated escape sequence.
raw_string_has_missing_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate escape not followed by a valid low surrogate escape.
substitutes_replacement_for_missing_low_surrogate bool output True when ParseString substitutes U+FFFD for a lone high surrogate, matching encoding/json behavior.
raw_string_has_invalid_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate followed by a unicode escape whose value is below the low surrogate range.
substitutes_replacement_for_invalid_low_surrogate bool output True when ParseString substitutes U+FFFD for a high surrogate followed by an invalid low surrogate, matching encoding/json behavior.
raw_string_has_backslash_at_end bool input True when ParseString encounters a string ending with a lone backslash with no character after it.
returns_error_for_backslash_at_end bool output True when ParseString returns MalformedValueError for a string ending with a lone backslash.
parseint_input_is_empty bool input True when ParseInt receives an empty byte slice.
returns_parseint_malformed_for_empty bool output True when ParseInt returns MalformedValueError for an empty byte slice.
parsefloat_input_is_empty bool input True when ParseFloat receives an empty byte slice.
returns_parsefloat_malformed_for_empty bool output True when ParseFloat returns MalformedValueError for an empty byte slice.
parseboolean_input_is_empty bool input True when ParseBoolean receives an empty byte slice.
returns_parseboolean_malformed_for_empty bool output True when ParseBoolean returns MalformedValueError for an empty byte slice.
parsestring_input_is_empty bool input True when ParseString receives an empty byte slice.
returns_parsestring_identity_for_empty bool output True when ParseString returns an empty Go string without error for an empty byte slice.
set_path_points_beyond_eof bool input True when Set is called with a path that resolves to a location beyond the end of available data.
set_returns_error_for_path_beyond_eof bool output True when Set returns an error for a path that resolves beyond the end of available data.
set_target_is_nested_in_existing_structure bool input True when Set is called with a multi-level path where intermediate levels exist but the leaf does not.
set_performs_nested_mutation_correctly bool output True when Set correctly creates missing nested structure and inserts the value at the correct location.
set_called_without_path bool input True when Set is called without any key path segments.
set_returns_error_without_path bool output True when Set returns KeyPathNotFoundError because no path segment was provided.
getstring_input_is_malformed bool input True when GetString is called on malformed input where the underlying Get call returns an error.
returns_getstring_error_for_malformed bool output True when GetString propagates the error from Get for malformed input.
getstring_value_has_truncated_escape bool input True when GetString addresses a JSON string value containing a truncated escape sequence.
returns_getstring_error_for_truncated_escape bool output True when GetString returns an error from ParseString for a truncated escape sequence.
getstring_addressed_value_is_not_string bool input True when GetString addresses a value that is not a JSON string.
returns_getstring_type_mismatch_error bool output True when GetString returns a type-mismatch error for a non-string addressed value.
getstring_input_is_empty bool input True when GetString is called on empty input.
returns_getstring_error_for_empty_input bool output True when GetString returns not-found or error for empty input.
getint_input_is_malformed bool input True when GetInt is called on malformed input where the underlying Get call returns an error.
returns_getint_error_for_malformed bool output True when GetInt propagates the error from Get for malformed input.
getint_value_overflows_int64 bool input True when GetInt addresses a JSON number token whose magnitude exceeds the int64 range.
returns_getint_overflow_error bool output True when GetInt returns the documented overflow error for a value exceeding int64 range.
getint_addressed_value_is_not_number bool input True when GetInt addresses a value that is not a JSON number.
returns_getint_type_mismatch_error bool output True when GetInt returns a type-mismatch error for a non-number addressed value.
getint_input_is_empty bool input True when GetInt is called on empty input.
returns_getint_error_for_empty_input bool output True when GetInt returns not-found or error for empty input.
getboolean_addressed_value_is_partial_literal bool input True when GetBoolean addresses a value that is a partial boolean literal due to truncation.
returns_getboolean_error_for_partial bool output True when GetBoolean returns an error from type classification or ParseBoolean for a partial boolean literal.
getunsafestring_input_is_malformed bool input True when GetUnsafeString is called on malformed input where the underlying Get call returns an error.
returns_getunsafestring_error_for_malformed bool output True when GetUnsafeString propagates the error from Get for malformed input.
getunsafestring_input_is_empty bool input True when GetUnsafeString is called on empty input.
returns_getunsafestring_error_for_empty bool output True when GetUnsafeString returns not-found or error for empty input.
getunsafestring_input_is_truncated_at_value_boundary bool input True when GetUnsafeString is called on input truncated at a value boundary.
returns_getunsafestring_error_for_truncated_value bool output True when GetUnsafeString propagates the error from Get for input truncated at a value boundary.
arrayeach_input_is_truncated_at_value_boundary bool input True when ArrayEach is called on input truncated at a value boundary.
returns_error_for_arrayeach_truncated_value bool output True when ArrayEach returns an error for input truncated at a value boundary, without panicking.
objecteach_input_is_truncated_mid_structure bool input True when ObjectEach is called on input truncated mid-structure where the object or a nested structure is not closed.
returns_error_for_objecteach_truncated_structure bool output True when ObjectEach returns an error for truncated mid-structure input, without panicking.
eachkey_tokenEnd_sentinel_reached bool input True when EachKey encounters a tokenEnd sentinel value during multi-path scanning.
eachkey_handles_sentinel_safely bool output True when EachKey treats the tokenEnd sentinel as an end-of-input condition and returns safely.
get_called_twice_with_same_input bool input True when Get is called twice with identical JSON input and identical key paths.
get_returns_identical_results bool output True when Get returns identical value slices, value types, offsets, and error values on both calls.
get_called_on_valid_input bool input True when Get is called on a non-nil JSON byte slice.
get_does_not_mutate_input bool output True when Get does not mutate the input byte slice during the call.
get_input_is_nil bool input True when Get is called with a nil byte slice as input.
get_returns_safe_result_for_nil bool output True when Get returns a not-found or error result without panicking for nil input.
get_input_is_deeply_nested bool input True when Get is called on JSON with deeply nested structures (64+ levels).
get_handles_deep_nesting_safely bool output True when Get returns a correct result or error for deeply nested input without panicking.
getstring_called_twice_with_same_input bool input True when GetString is called twice with identical JSON input and identical key paths.
getstring_returns_identical_results bool output True when GetString returns identical decoded string values and error values on both calls.
getstring_input_is_nil bool input True when GetString is called with a nil byte slice as input.
getstring_returns_safe_result_for_nil bool output True when GetString returns an empty string and error without panicking for nil input.
getstring_input_has_escaped_unicode bool input True when GetString addresses a JSON string containing escaped Unicode sequences.
getstring_decodes_and_preserves_semantics bool output True when GetString decodes escaped Unicode to correct Go string runes preserving semantic equivalence.
getstring_input_has_unicode_edge_cases bool input True when GetString addresses a JSON string containing Unicode edge cases like BOM or ZWJ.
getstring_handles_unicode_edges_safely bool output True when GetString handles Unicode edge cases correctly or returns a well-defined error.
typed_getter_called_twice_with_same_input bool input True when GetInt, GetFloat, or GetBoolean is called twice with identical input.
typed_getter_returns_identical_results bool output True when typed getters return identical typed values and error values on both calls.
typed_getter_input_is_nil bool input True when GetInt, GetFloat, or GetBoolean is called with a nil byte slice.
typed_getter_returns_safe_result_for_nil bool output True when typed getters return zero value and error without panicking for nil input.
getint_input_has_large_number_edge_case bool input True when GetInt addresses a JSON number with edge-case formatting like leading zeros or max-length digit strings.
getint_handles_large_numbers_safely bool output True when GetInt returns correct int64 or well-defined error for large-number edge cases.
traversal_called_twice_with_same_input bool input True when ArrayEach, ObjectEach, or EachKey is called twice with identical input.
traversal_returns_identical_results bool output True when traversal callbacks are invoked in the same order with same values on both calls.
traversal_input_is_nil bool input True when ArrayEach, ObjectEach, or EachKey is called with a nil byte slice.
traversal_returns_safe_result_for_nil bool output True when traversal returns error without invoking callbacks and without panicking for nil input.
traversal_input_is_deeply_nested bool input True when ArrayEach or ObjectEach is called on JSON with deeply nested structures.
traversal_handles_deep_nesting_safely bool output True when traversal handles deeply nested input safely without panicking or stack overflowing.
set_applied_twice_with_same_args bool input True when Set is called twice on the same input with the same value and key path.
set_second_call_produces_same_result bool output True when the second Set call produces the same output as the first application.
mutation_input_is_nil bool input True when Set or Delete is called with a nil byte slice.
mutation_returns_safe_result_for_nil bool output True when Set returns error and Delete returns nil/empty without panicking for nil input.
mutation_input_has_unicode_keys bool input True when Set or Delete is called with key paths containing Unicode characters.
mutation_handles_unicode_keys_safely bool output True when Set or Delete correctly resolves Unicode key paths or returns well-defined error.
getunsafestring_called_twice_with_same_input bool input True when GetUnsafeString is called twice with identical input.
getunsafestring_returns_identical_results bool output True when GetUnsafeString returns identical raw string values on both calls.
getunsafestring_input_is_nil bool input True when GetUnsafeString is called with a nil byte slice.
getunsafestring_returns_safe_result_for_nil bool output True when GetUnsafeString returns empty string and error without panicking for nil input.
getunsafestring_input_has_unicode_edge_cases bool input True when GetUnsafeString addresses a value with Unicode edge cases.
getunsafestring_handles_unicode_edges_safely bool output True when GetUnsafeString returns raw bytes as Go string without corruption for Unicode edge cases.
parse_helper_called_twice_with_same_input bool input True when a Parse helper is called twice with identical byte input.
parse_helper_returns_identical_results bool output True when Parse helpers return identical typed values and error values on both calls.
parse_helper_input_is_nil bool input True when a Parse helper is called with a nil byte slice.
parse_helper_returns_safe_result_for_nil bool output True when Parse helpers return zero value and error (or empty string) without panicking for nil input.
parsestring_input_has_standard_escapes bool input True when ParseString input contains standard JSON escape sequences.
parsestring_roundtrip_preserves_semantics bool output True when ParseString decoded string preserves semantic equivalence with original JSON encoding.
parseint_input_has_edge_case_number bool input True when ParseInt receives an edge-case numeric token like negative zero or very long digit strings.
parseint_handles_edge_numbers_safely bool output True when ParseInt returns correct int64 or well-defined error for edge-case numbers.
array_index int input The array index N addressed by an array-index path component [N]. Unbounded above; the boundary of interest is N versus the current length of the addressed array.
addressed_array_length int input The current element count of the array addressed by an array-index path component during Set mutation.
set_targets_array_index_beyond_length bool input True when Set addresses an array-index path component [N] where N >= the current length of the addressed array (the beyond-length partition of array_index).
set_targets_array_index_within_length bool input True when Set addresses an array-index path component [N] where N < the current length of the addressed array (the in-bounds partition of array_index, complement of set_targets_array_index_beyond_length).
set_appends_value_at_array_end bool output True when Set appends the value at the end of the addressed array (the new element's index becomes len(array)) and returns the mutated document, rather than overwriting an existing element or panicking.
path_component_length int input The byte length of a single caller-supplied key path component string. The boundary of interest is the empty-component case (length 0).
path_component_is_empty_string bool input True when any caller-supplied key path component is the empty string (the empty partition of path_component_length, length == 0). An empty-string component is neither a valid object key nor the [ array-index marker.
path_component_is_nonempty_string bool input True when every caller-supplied key path component is non-empty (the nonempty partition of path_component_length, complement of path_component_is_empty_string).
returns_not_found_for_empty_key_component bool output True when the parser treats an empty-string key path component as an unresolvable path, returning KeyPathNotFoundError for the Get family and Delete (and EachKey omitting the callback) or a defined error/document for Set.
completes_without_panic_on_empty_key_component bool output True when the parser completes the call without panicking for an empty-string key path component, never reaching an unguarded keys[i][0] / p[level][0] dereference (the OSS-Fuzz 4649128545288192 / hazard-sweep class).
addressed_container_is_array_or_object bool input True when the value addressed by the GetArrayLen/GetObjectLen key path is a JSON array (GetArrayLen) or object (GetObjectLen) container rather than a scalar or missing path.
returns_container_element_count bool output True when GetArrayLen returns the number of elements in the addressed array (0 for an empty array) or GetObjectLen returns the number of key-value pairs in the addressed object (0 for an empty object), with no caller callback invoked.
wildcard_path_resolves_to_every_matched_element bool output True when EachKeyWildcard/ArrayEachWildcard/SetWildcard fan out over every element matched by [*] components in document order (EachKeyWildcard one callback per matched combination, SetWildcard applies to every expanded concrete path), returning MalformedArrayError for a non-array container and treating an empty matched array as a no-op.
compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path bool output True when ParsePath converts a JSONPath-style string ($.dot, [N], [*], "quoted") into the path-component slice accepted by Get/Set/Delete/ArrayEach/EachKey and CompiledPath methods are observationally equivalent to invoking the matching top-level function with the parsed components, with errEmptyPath for empty input and errMalformedPath for non-conforming syntax.
config_lenient_modes_are_opt_in_and_default_remains_strict bool output True when Config accepts single-quoted strings only with AllowSingleQuotes, passes unknown escape bytes through literally only with AllowUnknownEscapes, and the zero/default Config plus package-level functions retain strict RFC 8259 behavior.
reader_parser_provides_incremental_stream_access bool output True when ReaderParser resolves paths and iterates root arrays from an io.Reader while retaining only the active sliding window or value and reporting empty or malformed streams without panicking or looping.
Data Properties
VariableStrategySemantics
returns_existing_path_lookup_result last_wins Last_wins, commutative, idempotent
returns_missing_path_result_for_well_formed_lookup last_wins Last_wins, commutative, idempotent
returns_parse_error_for_incomplete_lookup last_wins Last_wins, commutative, idempotent
returns_root_value_without_key_path last_wins Last_wins, commutative, idempotent
returns_missing_path_result_for_empty_input last_wins Last_wins, commutative, idempotent
returns_value_from_in_bounds_array_index last_wins Last_wins, commutative, idempotent
returns_invalid_array_index_not_found last_wins Last_wins, commutative, idempotent
returns_oob_array_index_not_found last_wins Last_wins, commutative, idempotent
returns_value_from_decoded_escaped_key last_wins Last_wins, commutative, idempotent
returns_unquoted_raw_string_contents last_wins Last_wins, commutative, idempotent
returns_best_effort_lookup_result last_wins Last_wins, commutative, idempotent
returns_value_type_error last_wins Last_wins, commutative, idempotent
set_appends_value_at_array_end last_wins Last_wins, commutative, idempotent
returns_not_found_for_empty_key_component last_wins Last_wins, commutative, idempotent
completes_without_panic_on_empty_key_component last_wins Last_wins, commutative, idempotent
returns_container_element_count last_wins Last_wins, commutative, idempotent
wildcard_path_resolves_to_every_matched_element last_wins Last_wins, commutative, idempotent
compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path last_wins Last_wins, commutative, idempotent
config_lenient_modes_are_opt_in_and_default_remains_strict last_wins Last_wins, commutative, idempotent
reader_parser_provides_incremental_stream_access last_wins Last_wins, commutative, idempotent