[PR #770] [CLOSED] fix(reference): preserve observed entry failure reasons #2230

New issue

Closed

opened 2026-10-16 21:16:00 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:16:00 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/770
Author: @rudycelekli
Created: 10/6/2026
Status: ❌ Closed

Base: main ← Head: fix/rea-reference-entry-failure-reasons-20261006

📝 Commits (1)

ab49eca fix(reference): preserve observed entry failure reasons

📊 Changes

3 files changed (+93 additions, -7 deletions)

View changed files

📝 src/application/ReferenceSourceImportEntries.ts (+6 -2)
➕ tests/boundary/filesystem/referenceSourceFailureDetails.test.ts (+81 -0)
📝 tests/boundary/filesystem/referenceSourceImport.test.ts (+6 -5)

📄 Description

Summary

Preserve observed per-entry filesystem/type failure reasons in reference-source imports. Self-contained bug fix; no separate issue linked.

Problem and expected behavior

An owned unreadable source file produces an EACCES diagnostic with the affected path in the filesystem reader. Import projection discarded it and returned generic permission advice. A FIFO's actual Entry is not a regular file reason was also discarded and replaced with advice to use a supported system. Callers need the observed constraint to decide how to repair or exclude an entry.

Change and scope

Retain the reader's message alongside recovery guidance. Unsupported entry guidance now says to exclude it or replace it with a regular file. Caller-selected local diagnostic paths are intentionally preserved under REA's local evidence rule. Top-level parser/policy error projection and transport credential handling are unchanged.

Contract and boundary impact

Semantic owner and earliest changed stage: reader failure to graph-entry limitation projection.
CLI and MCP/tool-catalog contract: schemas unchanged; per-entry limitation text preserves the observed reason.
Provider, bridge, target-format, or platform compatibility: local source filesystem only.
Evidence, artifact, provenance, or reconstruction contract: retains OS code/path and unsupported type constraint; readable entries unchanged.
Process execution, authorization, cleanup, or containment impact: none; no-follow reading and caller exclusions unchanged.
Generated metadata (docs/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

Tests added or updated: actual chmod000 file and mkfifo entry; readable control; projection expectation follows the current local diagnostic preservation rule.
Base reproduction or other evidence: two native failures and one passing readable control on base8238232. Executed reader→public import→built CLI before/after. Before, CLI limitations omit EACCES/type details; after, they contain the actual reader diagnostic and affected owned path. Unsupported FIFO guidance no longer suggests another OS.
User-visible CLI/MCP output: e.g. File could not be read: EACCES ... open '<selected path>' remains in the graph entry's limitations alongside guidance.
Remaining proof gaps: actual POSIX proof on macOS arm64; permission cases skip Windows/root UID. No claim of broader error sanitization changes or unrelated binary providers.

For evidence-bearing changes:

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

Native built CLI import-reference-source before/after — discarded reasons on base, preserves them after; readable control unchanged.
npm run test:focused -- tests/boundary/filesystem/referenceSourceFailureDetails.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts tests/boundary/filesystem/referenceSourceReader.test.ts — 23 passed.
npm run check — 5 tasks successful; 125 existing warnings, zero errors.
npm run check:fast — 2 tasks successful.
git diff --check — passed; SSH signature and DCO verified. Reused exact Node24.18.0/Vitest5.0.3/TypeScript7.0.2; no dependency edits.

Hosted full coverage tracked separately. External provider verification is not applicable to this filesystem projection.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: macOS native filesystem only.
Package or release metadata impact: none.
Security, privacy, process, or containment review: preserves caller-selected local paths and meaningful diagnostics, without changing transport credentials or explicit secret exclusions. Only owned temporary fixtures; permissions restored before cleanup.

AI assistance: implemented and source reviewed with Codex on behalf of @rudycelekli before publication.

Review checklist

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/770 **Author:** [@rudycelekli](https://github.com/rudycelekli) **Created:** 10/6/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/rea-reference-entry-failure-reasons-20261006` --- ### 📝 Commits (1) - [`ab49eca`](https://github.com/morluto/rea/commit/ab49eca4e0d0c25e5006a5150e52fba427db6e0f) fix(reference): preserve observed entry failure reasons ### 📊 Changes **3 files changed** (+93 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `src/application/ReferenceSourceImportEntries.ts` (+6 -2) ➕ `tests/boundary/filesystem/referenceSourceFailureDetails.test.ts` (+81 -0) 📝 `tests/boundary/filesystem/referenceSourceImport.test.ts` (+6 -5) </details> ### 📄 Description ## Summary Preserve observed per-entry filesystem/type failure reasons in reference-source imports. Self-contained bug fix; no separate issue linked. ## Problem and expected behavior An owned unreadable source file produces an EACCES diagnostic with the affected path in the filesystem reader. Import projection discarded it and returned generic permission advice. A FIFO's actual `Entry is not a regular file` reason was also discarded and replaced with advice to use a supported system. Callers need the observed constraint to decide how to repair or exclude an entry. ## Change and scope Retain the reader's message alongside recovery guidance. Unsupported entry guidance now says to exclude it or replace it with a regular file. Caller-selected local diagnostic paths are intentionally preserved under REA's local evidence rule. Top-level parser/policy error projection and transport credential handling are unchanged. ## Contract and boundary impact - Semantic owner and earliest changed stage: reader failure to graph-entry limitation projection. - CLI and MCP/tool-catalog contract: schemas unchanged; per-entry limitation text preserves the observed reason. - Provider, bridge, target-format, or platform compatibility: local source filesystem only. - Evidence, artifact, provenance, or reconstruction contract: retains OS code/path and unsupported type constraint; readable entries unchanged. - Process execution, authorization, cleanup, or containment impact: none; no-follow reading and caller exclusions unchanged. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none. ## Evidence and regression coverage - Tests added or updated: actual chmod000 file and mkfifo entry; readable control; projection expectation follows the current local diagnostic preservation rule. - Base reproduction or other evidence: two native failures and one passing readable control on base8238232. Executed reader→public import→built CLI before/after. Before, CLI limitations omit EACCES/type details; after, they contain the actual reader diagnostic and affected owned path. Unsupported FIFO guidance no longer suggests another OS. - User-visible CLI/MCP output: e.g. `File could not be read: EACCES ... open '<selected path>'` remains in the graph entry's limitations alongside guidance. - Remaining proof gaps: actual POSIX proof on macOS arm64; permission cases skip Windows/root UID. No claim of broader error sanitization changes or unrelated binary providers. For evidence-bearing changes: - [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 - Native built CLI `import-reference-source` before/after — discarded reasons on base, preserves them after; readable control unchanged. - `npm run test:focused -- tests/boundary/filesystem/referenceSourceFailureDetails.test.ts tests/boundary/filesystem/referenceSourceImport.test.ts tests/boundary/filesystem/referenceSourceReader.test.ts` — 23 passed. - `npm run check` — 5 tasks successful; 125 existing warnings, zero errors. - `npm run check:fast` — 2 tasks successful. - `git diff --check` — passed; SSH signature and DCO verified. Reused exact Node24.18.0/Vitest5.0.3/TypeScript7.0.2; no dependency edits. Hosted full coverage tracked separately. External provider verification is not applicable to this filesystem projection. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: macOS native filesystem only. - Package or release metadata impact: none. - Security, privacy, process, or containment review: preserves caller-selected local paths and meaningful diagnostics, without changing transport credentials or explicit secret exclusions. Only owned temporary fixtures; permissions restored before cleanup. AI assistance: implemented and source reviewed with Codex on behalf of @rudycelekli before publication. ## Review checklist - [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-10-16 21:16:00 +00:00