Source: https://guthlabs.ai/docs/instruments/url-query-string-parser/mechanism/

instrument mechanism / verified-clean

# URL / Query String Parser mechanism

The inspectable method record for URL / Query String Parser, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

The core component grammar reference is appropriate, but the instrument is not fully specified enough for a PASS. Define the query decoding convention, character encoding, invalid-input behavior, duplicate and valueless parameter representation, host normalization, and whether validation means syntax-only or network/application validity. Populate honest_label.

- RFC 3986 grammar is the correct standard for URI component syntax, but it does not by itself define application-level query-parameter parsing into key/value pairs.

- The claim to validate well-formedness is underspecified: RFC 3986 syntax validation differs from URL usability, DNS validity, supported schemes, and transport port-range validation.

- Decoded query parameters require an explicit policy for duplicate keys, parameters without '=', empty values, separators, malformed percent escapes, character encoding, and whether '+' means a literal plus or a space. RFC 3986 treats '+' as a literal plus; application/x-www-form-urlencoded does not.

- The specification does not state whether parsing is strict and all-or-nothing on invalid input or whether partially parsed components are returned.

## Units and conventions

- There are no physical measurement units.

- The port is interpreted as a decimal URI port token. In the valid examples, port values are assumed to be in the conventional TCP/UDP range 0 through 65535; RFC 3986 grammar itself only requires port characters to be digits and does not impose that range.

- Percent-encoded octets are decoded as UTF-8 for the query examples; this is an implementation policy rather than a complete requirement of RFC 3986.

- The test vectors use RFC 3986 query splitting on '&', decode percent escapes, preserve '+' as '+', and represent a parameter as a key/value pair only when the syntax is unambiguous.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "url": "https://example.com:8443/a/b?x=1&name=Alice#section"
  },
  "expected_outputs": {
    "valid": true,
    "scheme": "https",
    "host": "example.com",
    "port": 8443,
    "path": "/a/b",
    "query": "x=1&name=Alice",
    "query_parameters": [
      {
        "key": "x",
        "value": "1"
      },
      {
        "key": "name",
        "value": "Alice"
      }
    ],
    "fragment": "section"
  },
  "working": "1. Identify scheme before ':': 'https'. 2. After '//', authority is 'example.com:8443'; host is 'example.com' and port is 8443. Decimal check: 8×1000 + 4×100 + 4×10 + 3 = 8443. 3. The text before '?' is path '/a/b'. 4. The query is 'x=1&name=Alice'; split at '&' into 'x=1' and 'name=Alice', then split each at '=' to obtain (x, 1) and (name, Alice). 5. The text after '#' is fragment 'section'."
}
````

## Failure boundary

- No arithmetic or division-by-zero hazard exists because this instrument performs parsing rather than numerical calculation.

- Malformed percent escapes such as '%ZZ' or a trailing '%' must be rejected or reported explicitly; silently decoding them can corrupt data.

- Query parsing can cause security and interoperability problems if '+' handling, duplicate-key handling, empty values, or parameter ordering are inconsistent.

- Host parsing must define IPv6 bracket handling, internationalized domain names, userinfo, case normalization, and percent-encoding rules.

- A syntactically valid port may still be outside the implementation's supported numeric range or unusable by the network stack.

- The empty honest_label is a concern: the catalog entry should explicitly state that this is an RFC 3986 URI parser with an application-defined query-decoding policy, not imply universal URL validation.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/url-query-string-parser/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/url-query-string-parser/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/url-query-string-parser/qualification/>)

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json`

- `evidence-tranche5/tranche5-results.json`