docs: record player-start edge evidence and propose signed coordinates

README.md

@@ -150,7 +150,6 @@ for update and uninstall details.
 
 The CLI currently exposes experimental candidate discovery, project inventory,
 bounded raw snapshot loading, typed map-catalog inspection, selected-map
-summaries, tileset identity/name catalogs, selected system-setting summaries,
 summaries, tileset identity/name catalogs, selected-map event catalogs,
 selected system-setting summaries, bounded player-start and map-to-tileset
 validation, and strict lossless JSON syntax inspection. The tileset command

docs/capability-roadmap.md

@@ -183,8 +183,12 @@ The bounded `System.json` orientation summary is accepted in
 [ADR 0009](decisions/0009-experimental-system-summary.md) and implemented
 experimentally. It projects only the seven accepted string and nonnegative
 integer fields, retains raw bytes and unknown settings in the snapshot, and
-does not validate map references or coordinate bounds. Neither acceptance nor
-implementation makes the capability Supported.
+does not validate map references or coordinate bounds. A controlled MZ 1.10.0
+save preserved negative player-start coordinates, exposing a known gap in that
+unsigned contract. Proposed
+[ADR 0014](decisions/0014-signed-player-start-coordinates.md) defines the
+correction. Neither acceptance nor implementation makes the capability
+Supported.
 
 A bounded tileset identity/name catalog is implemented experimentally under
 accepted [ADR 0012](decisions/0012-experimental-tileset-catalog.md). It leaves
@@ -218,8 +222,9 @@ decision.
 **Current status: Experimental first slice.** The player-start contract accepted
 in [ADR 0010](decisions/0010-experimental-player-start-validation.md) composes
 the system summary, coherent map catalog, and selected-map dimensions. It
-reports only the evidenced zero triplet, an unevidenced mixed-zero state, a
-missing positive catalog record, and coordinates outside the map rectangle.
+reports only the evidenced zero triplet, a distinct zero-map/mixed-coordinate
+state, a missing positive catalog record, and coordinates outside the map
+rectangle.
 Structural projection failures remain errors. A finding-free result is not a
 general project-validity or compatibility claim, and the general severity and
 diagnostic model remains open.
@@ -332,10 +337,13 @@ Differential verification matched all 196 catalog records and all 196
 selected-map summaries in the local four-project MZ 1.10.0 evidence corpus. It
 also matched all 28 field comparisons and all four output envelopes for the
 system summary. Controlled MZ 1.10.0 experiments also establish same-map start
-relocation and editor recognition/preservation of the exact zero triplet as
-`None`. Independent differential verification also matched the bounded tileset
-and event projections and the map-to-tileset validation relationship against
-the four-project corpus. The next evidence steps are controlled tileset name,
-mode, and map-assignment experiments plus event creation, movement, renaming,
-page lifecycle, and deletion. Tile behavior, event page bodies, and commands
-remain later separate slices.
+relocation, Delete-generated zero-triplet serialization, and preservation of
+mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper
+out-of-bounds states. The negative case returns the system and player-start
+contracts to the contract stage under proposed ADR 0014. Independent
+differential verification also matched the bounded tileset and event
+projections and the map-to-tileset validation relationship against the
+four-project corpus. A controlled tileset rename changed only the name field;
+the next editor evidence steps are tileset mode and map assignment plus event
+creation, movement, renaming, page lifecycle, and deletion. Tile behavior,
+event page bodies, and commands remain later separate slices.

docs/compatibility.md

@@ -42,8 +42,8 @@ not use “supported” to mean only that one file happened to parse.
 | RPG Maker MZ typed tileset catalog | Experimental | Projects exact `data/Tilesets.json` into positive catalog-scoped IDs and decoded editor-facing names in ID order while retaining exact bytes and every unprojected field. It accepts null holes and refuses ambiguous required structure or ID/index mismatches. Aggregate evidence covers 24 records and 196 resolving map references across four MZ 1.10.0 projects, and an independent differential audit matched all 72 bounded comparisons. Modes, image slots, flags, notes, map-reference validation, assets, tile behavior, lifecycle operations, malformed-input editor behavior, mutation, persistence, and later versions remain unknown or unimplemented, so the capability remains Experimental. |
 | RPG Maker MZ selected-map summary | Experimental | Requires a coherent typed map catalog and matching catalog-scoped ID, then projects one evidenced three-digit map document into its exact path, catalog and display names, positive dimensions, positive tileset ID scalar, and count of opaque event objects. Unknown fields and exact bytes remain in the raw snapshot. The operation refuses ambiguous required structure and does not interpret tile data or event bodies, validate tileset references or editor compatibility, support IDs above 999, mutate, serialize, or persist data. Direct shape evidence covers 196 map documents from four MZ 1.10.0 projects, and an independent differential audit matched every bounded summary field across the corpus. Later versions and malformed-input editor behavior remain unknown, so the capability remains Experimental. |
 | RPG Maker MZ selected-map event catalog | Experimental | Requires a coherent map catalog, matching catalog-scoped ID, and evidenced three-digit map document, then projects map-scoped positive event IDs, decoded names, nonnegative coordinates, and opaque page counts in ID order. Coordinates outside the map dimensions are contextual findings, not editor-rejection claims. Exact bytes, notes, page bodies, commands, and unknown fields remain in the raw snapshot. Aggregate evidence covers 1,555 events and 1,576 pages across 196 MZ 1.10.0 map documents, and an independent differential audit matched all 10,323 bounded comparisons. Page semantics, commands, mutation, persistence, malformed-input editor behavior, and later versions remain unknown or unimplemented, so the capability remains Experimental. |
-| RPG Maker MZ system summary | Experimental | Projects exact `data/System.json` from an existing snapshot into its exact path, decoded game title, currency unit, and locale, plus nonnegative editor-map and player-start map/X/Y scalars. Unknown settings and exact bytes remain in the raw snapshot. The operation refuses ambiguous required structure and does not interpret other system settings, validate map references or coordinate bounds, compare titles across files, mutate, serialize, or persist data. Aggregate shape evidence covers four MZ 1.10.0 projects, and an independent differential audit matched all 28 field comparisons and all four output envelopes across that corpus. Later versions and malformed-input editor behavior remain unknown, so the capability remains Experimental. |
-| RPG Maker MZ player-start validation | Experimental | Composes the system summary, coherent map catalog, and selected-map dimensions over one existing snapshot. It reports the observed exact zero triplet as an unset player start, treats a zero map ID with nonzero coordinates as unevidenced, reports a missing positive catalog record, and checks `x < width` and `y < height`. Structural projection failures remain operation errors. Findings do not imply general project validity or editor rejection, and a finding-free report does not establish compatibility, passability, runtime success, mutation safety, or write support. Direct editor evidence covers one controlled MZ 1.10.0 relocation and recognition/preservation of the prepared zero triplet. An independent differential audit matched all 36 bounded comparisons across four MZ 1.10.0 projects, whose observed states were all finding-free. Delete-generated serialization, mixed-zero behavior, malformed-reference editor behavior, negative-category corpus coverage, and later versions remain unknown. |
+| RPG Maker MZ system summary | Experimental | Projects exact `data/System.json` from an existing snapshot into its exact path, decoded game title, currency unit, and locale, plus nonnegative editor-map and player-start map/X/Y scalars. Unknown settings and exact bytes remain in the raw snapshot. The current unsigned-coordinate contract rejects an MZ 1.10.0 saved negative-coordinate state; proposed ADR 0014 defines a correction but is not implemented. Aggregate shape evidence covers four projects, an independent differential audit matched all 28 field comparisons and four output envelopes, and controlled saves cover deletion, mixed zero, exact bounds, dangling map IDs, negative coordinates, and upper out-of-bounds coordinates. The operation remains Experimental and does not establish general editor validity, runtime behavior, mutation, persistence, or later-version compatibility. |
+| RPG Maker MZ player-start validation | Experimental | Composes the system summary, coherent map catalog, and selected-map dimensions over one existing snapshot. It reports the exact zero triplet as an unset player start, a zero map ID with nonzero coordinates as a distinct ambiguous state, a missing positive catalog record, and coordinates outside the map rectangle. Structural projection failures remain operation errors. MZ 1.10.0 generated the zero triplet through Delete and saved prepared mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper-out-of-bounds states. The current unsigned system projection prevents validation of the observed negative case; proposed ADR 0014 defines a correction. Findings do not imply general project validity, editor rejection, passability, runtime success, mutation safety, write support, or later-version behavior. |
 | RPG Maker MZ map-to-tileset reference validation | Experimental | Composes coherent map and tileset catalogs with every selected-map summary and deterministically reports positive map tileset IDs that have no catalog record. Structural prerequisite failures remain operation errors. A finding-free report does not establish project validity, editor acceptance, asset existence, tile behavior, runtime success, compatibility, mutation safety, or write support. Aggregate evidence covers 196 resolving references across four MZ 1.10.0 projects, and an independent differential audit matched all 220 bounded comparisons. Malformed-reference editor behavior and later versions remain unknown. |
 | General project validation | Not implemented | Only bounded experimental player-start and map-to-tileset relationships are implemented; no general validity, severity, compatibility, repair, or write-time validation contract exists. |
 | Lossless project round trips | Not implemented | The immutable syntax representation has an exact accepted-input no-op contract, but no project round-trip, typed edit, or supported mutation exists. |

docs/decisions/0014-signed-player-start-coordinates.md

@@ -0,0 +1,112 @@
+# ADR 0014: Signed Player-Start Coordinates
+
+- **Status:** Proposed
+- **Date:** 2026-08-09
+- **Supersedes in part:**
+  [ADR 0009](0009-experimental-system-summary.md) and
+  [ADR 0010](0010-experimental-player-start-validation.md)
+
+## Context
+
+ADR 0009 selected `u32` for all four projected map-position scalars because the
+initial four-project corpus contained only nonnegative values. The resulting
+system summary therefore rejects a negative `startX` or `startY` before the
+player-start validator can report its relationship to the selected map.
+
+A controlled RPG Maker MZ 1.10.0 tolerance matrix has now contradicted that
+assumption. In an owned disposable project, the editor saved prepared
+`startX = -1` and `startY = -1` values without normalizing them. The same matrix
+also preserved exact upper in-bounds coordinates, upper out-of-bounds
+coordinates, a dangling positive start-map ID, and a zero map ID with nonzero
+coordinates. These observations establish persistence tolerance in that
+version, not editor validity or runtime success.
+
+The stored coordinate domain must therefore be representable independently
+from coordinate validation. Map IDs remain nonnegative in all available
+evidence and retain their existing zero and positive-reference behavior.
+
+## Decision
+
+If accepted, the experimental system-summary and player-start contracts will
+change as follows:
+
+1. `editMapId` and `startMapId` remain stored `u32` scalars. Their zero,
+   dangling, and catalog-reference semantics remain separate validation
+   questions.
+2. `startX` and `startY` become stored `i64` scalars in `SystemSummary`,
+   `PlayerStartValidation`, and their associated findings. The `i64` boundary
+   is an explicit Tilewright representation limit, not a claimed MZ limit.
+3. Coordinate projection accepts strict base-ten JSON integer lexemes in the
+   inclusive `i64` range. It continues to refuse fractional, exponent-form,
+   or out-of-range coordinates through the existing typed unsupported-integer
+   error. Map ID projection retains its unsigned-decimal `u32` policy.
+4. The exact `startMapId = 0`, `startX = 0`, `startY = 0` triplet continues to
+   produce `MissingPlayerStart`.
+5. A zero map ID with either nonzero signed coordinate continues to produce
+   `ZeroMapIdWithCoordinates`, but documentation and human output describe it
+   as an editor-preserved ambiguous state rather than an unobserved state.
+6. For a positive catalog-selected map, a negative coordinate or a coordinate
+   greater than or equal to the corresponding positive dimension produces the
+   existing `OutOfBounds` finding. This remains a contextual geometric finding,
+   not an editor-rejection claim.
+7. The core operations remain pure and read-only. Exact source bytes, unknown
+   properties, and every unprojected setting remain untouched in the snapshot.
+8. Because successful `system --format json` and `validate --format json`
+   reports can newly contain negative coordinate values, the CLI output schema
+   version advances from 1 to 2. The other command shapes remain unchanged,
+   but the current executable-wide schema number advances consistently.
+
+## Rationale
+
+Signed storage reflects observed project data without conflating tolerance with
+validity. Keeping map IDs unsigned avoids expanding an unrelated domain. An
+`i64` bound is wide, directly serializable by the Rust and JSON adapters, and
+keeps recoverable range failure explicit without exposing the provisional CST.
+
+Reusing `OutOfBounds` preserves the caller's real question: whether the stored
+coordinate lies in the selected map's zero-origin rectangle. A separate
+negative-coordinate category would encode a representation detail without
+changing the relationship or available remediation.
+
+Advancing the JSON schema version makes the successful value-domain change
+visible to script consumers. Tilewright is pre-1.0 and these APIs are
+Experimental, but versioned output should still avoid silent contract changes.
+
+## Consequences
+
+- Tilewright can summarize and validate the newly observed negative-coordinate
+  state instead of failing structural projection.
+- Public Rust coordinate accessors and finding fields change from `u32` to
+  `i64`; downstream experimental callers must update explicit types.
+- Existing nonnegative reports retain the same values and finding categories.
+- CLI consumers must accept schema version 2 before processing new reports.
+- Values outside `i64`, exponent notation, and fractional forms remain refused
+  without implying that MZ rejects them.
+- General project validity, runtime behavior, mutation, and persistence remain
+  outside the capability.
+
+## Alternatives Considered
+
+- **Keep `u32` and classify negative values as malformed:** Rejected because it
+  contradicts a directly observed MZ 1.10.0 saved state and prevents contextual
+  validation from running.
+- **Use `i32`:** Rejected because no editor evidence establishes a 32-bit
+  coordinate limit; the narrower bound would add an unsupported assumption.
+- **Expose the raw numeric lexeme:** Rejected because callers need a small
+  domain value and the raw document already preserves exact syntax.
+- **Add a distinct negative-coordinate finding:** Rejected because negative and
+  upper-bound values violate the same evidenced rectangular relationship.
+- **Keep CLI schema version 1:** Rejected because successful coordinate fields
+  change from a nonnegative to a signed value domain.
+- **Interpret editor preservation as validity:** Rejected because Save tolerance
+  does not establish runtime behavior, passability, or editor intent.
+
+## Validation
+
+Implementation requires generated synthetic tests for `-1`, `i64::MIN`,
+`i64::MAX`, both overflow directions, nonnegative regression cases, zero-map
+mixed coordinates, negative and upper out-of-bounds findings, raw-byte
+preservation, schema-version-2 human/JSON adapters, and typed structural errors.
+The retained local controlled cases must be checked differentially without
+copying project data into the repository. The complete Rust quality gate must
+pass before merge.

docs/decisions/README.md

@@ -5,7 +5,9 @@ implementation context has changed.
 
 ## Proposed decisions
 
-No decisions are currently proposed.
+| ADR | Status | Summary |
+| --- | --- | --- |
+| [0014: Signed player-start coordinates](0014-signed-player-start-coordinates.md) | Proposed | Correct the experimental system and player-start projections to retain observed signed coordinates and report their map relationship contextually. |
 
 ## Accepted decisions