morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #7079] [MERGED] fix(apple): keep the documented terminating process, parent pid and metadata members of IPS reports #7626

New issue

Closed

opened 2026-11-03 13:39:12 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:39:12 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7079
Author: @rodricksz4h5
Created: 10/25/2026
Status: ✅ Merged
Merged: 10/25/2026
Merged by: @morluto

Base: main ← Head: fix/ips-documented-termination-members

📝 Commits (1)

9decc5e fix(apple): keep the documented terminating process, parent pid and metadata members of IPS reports

📊 Changes

7 files changed (+81 additions, -13 deletions)

View changed files

📝 docs/apple-ips.md (+4 -1)
📝 src/application/binaryDiagnostics/AppleIpsService.test.ts (+10 -3)
📝 src/domain/native/appleIps.test.ts (+3 -0)
📝 src/domain/native/appleIps.ts (+11 -1)
📝 src/native/apple/AppleIpsJsonShape.ts (+11 -1)
📝 src/native/apple/AppleIpsParser.test.ts (+36 -7)
📝 src/native/apple/AppleIpsParser.ts (+6 -0)

📄 Description

Summary

inspect_apple_ips / inspect-apple-ips now keeps six members that Apple documents but REA reported only by name in unlisted_keys:

termination.byPid, termination.byProc and termination.flags;
the body's parentPid;
the metadata line's build_version and platform.

Fixes #7078

Problem and expected behavior

Apple's key tables list these members. #4297 asks for termination members beyond namespace, code and indicator to be retained as recorded, and docs/apple-ips.md says documented fields are reproduced, with only undocumented keys going to unlisted_keys. The parser shapes did not list them, so their values were dropped and coverage stayed complete. For a watchdog kill, the result no longer said which process (runningboardd) ended the app.

Change and scope

src/native/apple/AppleIpsJsonShape.ts lists the six members in the termination, body and metadata shapes.
src/native/apple/AppleIpsParser.ts reads by_proc and build_version as text, and by_pid, flags, parent_pid and platform as recorded integers. Like pid and code, the integers keep their decimal and hexadecimal forms, are charged to max_integer_text_bytes, and a wrong JSON type goes to coverage.type_mismatches.
src/domain/native/appleIps.ts adds the fields to the strict output schema, and appleIpsReportIntegerTextBytes counts the new integers.
docs/apple-ips.md names the new fields.

This is the same cause as #7059 (usedImages[].name, frames[].symbolLocation). Not included: body members outside the facts this tool reports (procRole, uptime, bundleInfo, storeInfo, lastExceptionBacktrace, vmSummary and others). They stay in unlisted_body_keys as before.

Contribution scope: not applicable (a fix within the existing static-inspection boundary).

Contract and boundary impact

Semantic owner and earliest changed stage: the IPS JSON projection (AppleIpsJsonShape.ts) and its parser (AppleIpsParser.ts), the single producer for AppleIpsService, the CLI and the MCP tool.
Contribution scope fit and linked maintainer decision: within the existing tool; #4297 describes the termination contract.
CLI and MCP/tool-catalog contract: additive output fields metadata.build_version, metadata.platform, process.parent_pid, termination.flags, termination.by_pid and termination.by_proc. These names no longer appear in the corresponding unlisted_keys. The MCP output schema comes from appleIpsSchema.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: recorded values only; nothing is derived.
Target selection, authority, upstream behavior, and cleanup details: not applicable.
Generated metadata, package, or installation impact: none beyond the generated tool output schema.
Read existing files or captured data.

Evidence and regression coverage

Tests added or updated:
- AppleIpsParser.test.ts: a new test keeps the six members from the ReportCrash-shaped fixture and records a string byPid as a type mismatch. The fixture test now expects termination.unlisted_keys to be [] instead of ["flags","byProc","byPid"]. "bounds rejected index text" uses a bare metadata line, so the fixture's recorded platform stays out of its 19/20-byte allowance.
- AppleIpsService.test.ts: the repeated-integer-text check now includes platform, parent_pid, flags and by_pid (threshold 131/132 bytes).
- appleIps.test.ts: schema fixture updated.
Base reproduction: on main 8e6a95788 with the new tests, the two parser tests and the 132-byte service case fail. The other six hand-built-fixture tests fail only because main's strict schema rejects the new fields.
User-visible CLI output, rea inspect-apple-ips watchdog.ips --json (a report with byProc runningboardd, byPid 33, flags 6, parentPid 1, build_version "42", platform 2):

	main `8e6a95788`	this branch
`termination`	`unlisted_keys: ["flags","byProc","byPid"]`	`by_proc: "runningboardd"`, `by_pid: {"decimal":"33","hex":"0x21"}`, `flags: {"decimal":"6","hex":"0x6"}`, `unlisted_keys: []`
`process`	`parent: "launchd"` (`parentPid` in `unlisted_body_keys`)	`parent: "launchd"`, `parent_pid: {"decimal":"1","hex":"0x1"}`
`metadata`	`build_version`, `platform` in `unlisted_keys`	`build_version: "42"`, `platform: {"decimal":"2","hex":"0x2"}`
coverage, classification	`complete`, `watchdog`	unchanged

Remaining proof gaps: the report above is synthetic. Field names and types come from Apple's key tables and the repository's macOS ReportCrash-shaped fixture, which records all six. No new device-generated report was captured.

Boundary regressions: parser format evidence (documented member kept, wrong type recorded as a mismatch) and the integer-text resource bound.

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

Linux (Debian bookworm), Node 24.22.1, on the commit before its rebase onto fead4fdaa (which touches no IPS files):

npm run test:local -- src/native/apple/AppleIpsParser.test.ts src/application/binaryDiagnostics/AppleIpsService.test.ts src/domain/native/appleIps.test.ts: 82 passed.
npm run test:focused -- tests/boundary/mcp/appleIpsMcp.test.ts: 1 passed.
npm run check:fast: passed.
npm run docs:check: passed.
rea inspect-apple-ips on main and on this branch: output above.

Compatibility, safety, and release

Breaking changes or migration steps: none. The output fields are additive; the six keys move from unlisted_keys into named fields.
Real Hopper/Ghidra, browser, or OS coverage: not applicable (static JSON parsing).
Package or release metadata impact: none.
Security, privacy, process, or containment review: reads the selected file only. by_proc is a recorded process name, like parent.

Author readiness

Human owner: @rodricksz4h5

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/7079 **Author:** [@rodricksz4h5](https://github.com/rodricksz4h5) **Created:** 10/25/2026 **Status:** ✅ Merged **Merged:** 10/25/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/ips-documented-termination-members` --- ### 📝 Commits (1) - [`9decc5e`](https://github.com/morluto/rea/commit/9decc5efffbcca328ce548d235e973a725c35d81) fix(apple): keep the documented terminating process, parent pid and metadata members of IPS reports ### 📊 Changes **7 files changed** (+81 additions, -13 deletions) <details> <summary>View changed files</summary> 📝 `docs/apple-ips.md` (+4 -1) 📝 `src/application/binaryDiagnostics/AppleIpsService.test.ts` (+10 -3) 📝 `src/domain/native/appleIps.test.ts` (+3 -0) 📝 `src/domain/native/appleIps.ts` (+11 -1) 📝 `src/native/apple/AppleIpsJsonShape.ts` (+11 -1) 📝 `src/native/apple/AppleIpsParser.test.ts` (+36 -7) 📝 `src/native/apple/AppleIpsParser.ts` (+6 -0) </details> ### 📄 Description ## Summary `inspect_apple_ips` / `inspect-apple-ips` now keeps six members that Apple documents but REA reported only by name in `unlisted_keys`: - `termination.byPid`, `termination.byProc` and `termination.flags`; - the body's `parentPid`; - the metadata line's `build_version` and `platform`. Fixes #7078 ## Problem and expected behavior Apple's key tables list these members. #4297 asks for termination members beyond `namespace`, `code` and `indicator` to be retained as recorded, and `docs/apple-ips.md` says documented fields are reproduced, with only undocumented keys going to `unlisted_keys`. The parser shapes did not list them, so their values were dropped and coverage stayed `complete`. For a watchdog kill, the result no longer said which process (`runningboardd`) ended the app. ## Change and scope - `src/native/apple/AppleIpsJsonShape.ts` lists the six members in the termination, body and metadata shapes. - `src/native/apple/AppleIpsParser.ts` reads `by_proc` and `build_version` as text, and `by_pid`, `flags`, `parent_pid` and `platform` as recorded integers. Like `pid` and `code`, the integers keep their decimal and hexadecimal forms, are charged to `max_integer_text_bytes`, and a wrong JSON type goes to `coverage.type_mismatches`. - `src/domain/native/appleIps.ts` adds the fields to the strict output schema, and `appleIpsReportIntegerTextBytes` counts the new integers. - `docs/apple-ips.md` names the new fields. This is the same cause as #7059 (`usedImages[].name`, `frames[].symbolLocation`). Not included: body members outside the facts this tool reports (`procRole`, `uptime`, `bundleInfo`, `storeInfo`, `lastExceptionBacktrace`, `vmSummary` and others). They stay in `unlisted_body_keys` as before. Contribution scope: not applicable (a fix within the existing static-inspection boundary). ## Contract and boundary impact - Semantic owner and earliest changed stage: the IPS JSON projection (`AppleIpsJsonShape.ts`) and its parser (`AppleIpsParser.ts`), the single producer for `AppleIpsService`, the CLI and the MCP tool. - Contribution scope fit and linked maintainer decision: within the existing tool; #4297 describes the termination contract. - CLI and MCP/tool-catalog contract: additive output fields `metadata.build_version`, `metadata.platform`, `process.parent_pid`, `termination.flags`, `termination.by_pid` and `termination.by_proc`. These names no longer appear in the corresponding `unlisted_keys`. The MCP output schema comes from `appleIpsSchema`. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: recorded values only; nothing is derived. - Target selection, authority, upstream behavior, and cleanup details: not applicable. - Generated metadata, package, or installation impact: none beyond the generated tool output schema. - [x] Read existing files or captured data. ## Evidence and regression coverage - Tests added or updated: - `AppleIpsParser.test.ts`: a new test keeps the six members from the ReportCrash-shaped fixture and records a string `byPid` as a type mismatch. The fixture test now expects `termination.unlisted_keys` to be `[]` instead of `["flags","byProc","byPid"]`. "bounds rejected index text" uses a bare metadata line, so the fixture's recorded `platform` stays out of its 19/20-byte allowance. - `AppleIpsService.test.ts`: the repeated-integer-text check now includes `platform`, `parent_pid`, `flags` and `by_pid` (threshold 131/132 bytes). - `appleIps.test.ts`: schema fixture updated. - Base reproduction: on main 8e6a95788 with the new tests, the two parser tests and the 132-byte service case fail. The other six hand-built-fixture tests fail only because main's strict schema rejects the new fields. - User-visible CLI output, `rea inspect-apple-ips watchdog.ips --json` (a report with `byProc` `runningboardd`, `byPid` 33, `flags` 6, `parentPid` 1, `build_version` "42", `platform` 2): | | main 8e6a95788 | this branch | |---|---|---| | `termination` | `unlisted_keys: ["flags","byProc","byPid"]` | `by_proc: "runningboardd"`, `by_pid: {"decimal":"33","hex":"0x21"}`, `flags: {"decimal":"6","hex":"0x6"}`, `unlisted_keys: []` | | `process` | `parent: "launchd"` (`parentPid` in `unlisted_body_keys`) | `parent: "launchd"`, `parent_pid: {"decimal":"1","hex":"0x1"}` | | `metadata` | `build_version`, `platform` in `unlisted_keys` | `build_version: "42"`, `platform: {"decimal":"2","hex":"0x2"}` | | coverage, classification | `complete`, `watchdog` | unchanged | - Remaining proof gaps: the report above is synthetic. Field names and types come from Apple's key tables and the repository's macOS ReportCrash-shaped fixture, which records all six. No new device-generated report was captured. Boundary regressions: parser format evidence (documented member kept, wrong type recorded as a mismatch) and the integer-text resource bound. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed Linux (Debian bookworm), Node 24.22.1, on the commit before its rebase onto fead4fdaa (which touches no IPS files): - `npm run test:local -- src/native/apple/AppleIpsParser.test.ts src/application/binaryDiagnostics/AppleIpsService.test.ts src/domain/native/appleIps.test.ts`: 82 passed. - `npm run test:focused -- tests/boundary/mcp/appleIpsMcp.test.ts`: 1 passed. - `npm run check:fast`: passed. - `npm run docs:check`: passed. - `rea inspect-apple-ips` on main and on this branch: output above. ## Compatibility, safety, and release - Breaking changes or migration steps: none. The output fields are additive; the six keys move from `unlisted_keys` into named fields. - Real Hopper/Ghidra, browser, or OS coverage: not applicable (static JSON parsing). - Package or release metadata impact: none. - Security, privacy, process, or containment review: reads the selected file only. `by_proc` is a recorded process name, like `parent`. ## Author readiness Human owner: @rodricksz4h5 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:39:12 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7626

No description provided.

Rows
Columns