From acb10754c1007688d07759d41e24916eec540bbf Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:01:36 +0800 Subject: [PATCH] refactor(native)!: report kernel build config coverage as partial or unknown instead of incomplete (#11486) inspect_kernel_build_config coverage.status was `incomplete` for a config cut by the searched bytes or a budget-stopped search (known gaps), for a malformed framed config, and for a payload that was never searched (examined_bytes 0). Coverage now uses the shared status: `partial` for the known gaps, `unknown` when a config's existence or contents cannot be determined; `unsupported` is unchanged. config.status keeps its own values, and the service's consistency check pairs each config state with its coverage. BREAKING CHANGE: inspect_kernel_build_config `coverage.status` reports `partial` (config_gzip_truncated, config_search_exhausted) or `unknown` (malformed config, payload not searched) instead of `incomplete`. --- docs/guides/native/kernel-build-config.md | 11 +++++++--- docs/specs/native/kernel-build-config/spec.md | 4 +++- .../baselines/local-completeness-enum.json | 1 - .../KernelBuildConfigService.test.ts | 20 +++++++++++++++++++ .../KernelBuildConfigService.ts | 12 ++++++----- src/domain/native/kernelBuildConfig.ts | 10 +++++++++- src/native/elf/KernelBuildConfig.test.ts | 17 ++++++++-------- src/native/elf/KernelBuildConfig.ts | 17 +++++++++++++--- .../boundary/mcp/kernelBuildConfigMcp.test.ts | 2 +- 9 files changed, 71 insertions(+), 23 deletions(-) diff --git a/docs/guides/native/kernel-build-config.md b/docs/guides/native/kernel-build-config.md index c010dc65c5..d7b4a48098 100644 --- a/docs/guides/native/kernel-build-config.md +++ b/docs/guides/native/kernel-build-config.md @@ -59,7 +59,7 @@ reported as a config. When `IKCFG_ST`, gzip magic, and a later `IKCFG_ED` frame a member that does not decode, a deflate stream cut off by that marker, a member that fails its CRC-32 or ISIZE check, or text that fails the grammar, the config is `malformed` with coverage -`incomplete`, and `marker`, `gzip`, and `end_marker` locate the blob. A +`unknown`, and `marker`, `gzip`, and `end_marker` locate the blob. A malformed blob is never reported as an absent config. A valid config later in the searched bytes still wins. `marker`, `gzip`, and `end_marker` give the three ranges. `sha256` hashes the inflated text. `option_count` counts @@ -115,7 +115,8 @@ times `max_config_bytes` of output across them. A candidate whose stream fails partway through is charged its full per-candidate allowance, since its partial output is not measured. When that search budget runs out before a config is accepted, the config is `incomplete` with reason -`config_search_exhausted` instead of failing or reporting an absent config. +`config_search_exhausted` and coverage `partial` instead of failing or +reporting an absent config. Inflation runs off the event loop. Every scan, including marker searches that find nothing, config text checks, validation of one long value, and hashing, yields to it at least once @@ -124,7 +125,11 @@ at the next check. One inflate call runs to its output bound once started. Results that could not search or read the kernel bytes stay `incomplete`, `malformed`, or `unsupported` and are never -reported as an absent config: +reported as an absent config. `coverage.status` is `partial` when the config +is known to extend past what was examined (`config_gzip_truncated`, +`config_search_exhausted`), `unknown` when a framed config is malformed or the +payload could not be searched (`examined_bytes` is 0), and `unsupported` for a +payload codec REA does not inflate: | `config.reason` | Meaning | | ---------------------------------- | ---------------------------------------------------------------------------- | diff --git a/docs/specs/native/kernel-build-config/spec.md b/docs/specs/native/kernel-build-config/spec.md index 5043a06933..7527bd4e25 100644 --- a/docs/specs/native/kernel-build-config/spec.md +++ b/docs/specs/native/kernel-build-config/spec.md @@ -50,7 +50,9 @@ these files. page size. The config search inflates at most 16 candidates and at most four times `max_config_bytes` in total, charging a stream that fails partway through its full per-candidate allowance. Exhausting the search budget is - `incomplete` with `config_search_exhausted`. A member past + `incomplete` with `config_search_exhausted` and coverage `partial`; a + member cut by the searched bytes is also `partial`. A malformed framed + config, or a payload that could not be searched, has coverage `unknown`. A member past `max_config_bytes` fails the budget only when no later candidate is accepted. 8. Cancellation is checked between candidates, between banner hits, while diff --git a/scripts/verify/baselines/local-completeness-enum.json b/scripts/verify/baselines/local-completeness-enum.json index eea85cabdb..e9905e371e 100644 --- a/scripts/verify/baselines/local-completeness-enum.json +++ b/scripts/verify/baselines/local-completeness-enum.json @@ -14,7 +14,6 @@ "src/domain/javascript/javascriptRouteInventory.ts": 1, "src/domain/javascript/javascriptStaticCoverage.ts": 1, "src/domain/model/modelArtifact.ts": 1, - "src/domain/native/kernelBuildConfig.ts": 1, "src/domain/native/nativeInitializers.ts": 1, "src/domain/sqlite/sqliteDatabase.ts": 1, "src/domain/wasm/wasmArtifact.ts": 1, diff --git a/src/application/binaryDiagnostics/KernelBuildConfigService.test.ts b/src/application/binaryDiagnostics/KernelBuildConfigService.test.ts index 5dec5fa3a6..f555174972 100644 --- a/src/application/binaryDiagnostics/KernelBuildConfigService.test.ts +++ b/src/application/binaryDiagnostics/KernelBuildConfigService.test.ts @@ -144,6 +144,26 @@ it.each([ }; }, ], + [ + "a malformed config reported as a partial gap", + async (): Promise => { + const malformed = await reportOf(nonConfigGzipFixture()); + return { + ...malformed, + coverage: { ...malformed.coverage, status: "partial" }, + }; + }, + ], + [ + "a truncated config reported with unknown coverage", + async (): Promise => { + const truncated = await reportOf(truncatedKernelConfigFixture()); + return { + ...truncated, + coverage: { ...truncated.coverage, status: "unknown" }, + }; + }, + ], [ "an incomplete config carrying a malformed reason", async (): Promise => { diff --git a/src/application/binaryDiagnostics/KernelBuildConfigService.ts b/src/application/binaryDiagnostics/KernelBuildConfigService.ts index e2de30a59f..b394e3d08e 100644 --- a/src/application/binaryDiagnostics/KernelBuildConfigService.ts +++ b/src/application/binaryDiagnostics/KernelBuildConfigService.ts @@ -260,11 +260,13 @@ const searchedAgrees = (report: KernelBuildConfig): boolean => { if (report.banner.status === "unknown") return false; if (report.config.status === "present" || report.config.status === "absent") return report.coverage.status === "complete"; + // A cut or budget-stopped config is a known gap; a malformed one is unreadable. + if (report.coverage.examined_entries !== 0) return false; + if (report.config.status === "incomplete") + return report.coverage.status === "partial"; return ( - (report.config.status === "incomplete" || - report.config.status === "malformed") && - report.coverage.status === "incomplete" && - report.coverage.examined_entries === 0 + report.config.status === "malformed" && + report.coverage.status === "unknown" ); } if ( @@ -279,7 +281,7 @@ const searchedAgrees = (report: KernelBuildConfig): boolean => { report.config.status === "unsupported" ); return ( - report.coverage.status === "incomplete" && + report.coverage.status === "unknown" && report.config.status === "incomplete" ); }; diff --git a/src/domain/native/kernelBuildConfig.ts b/src/domain/native/kernelBuildConfig.ts index bc878365f1..d2603965f9 100644 --- a/src/domain/native/kernelBuildConfig.ts +++ b/src/domain/native/kernelBuildConfig.ts @@ -1,5 +1,6 @@ import { z } from "zod"; +import { coverageStatusSchema } from "../coverage.js"; import { digestSchema } from "../digests.js"; import { absoluteLocalPathStringSchema } from "../localPath.js"; @@ -214,7 +215,14 @@ export const kernelBuildConfigSchema = z.strictObject({ entries: z.array(entrySchema), }), coverage: z.strictObject({ - status: z.enum(["complete", "incomplete", "unsupported"]), + /** + * `partial` when the config is known to extend past what was examined (a + * gzip member cut by the searched bytes, or the candidate budget stopping + * the search); `unknown` when whether a config exists or what it holds + * cannot be determined (an unreadable payload that was not searched, or a + * malformed config); `unsupported` for a payload codec REA does not inflate. + */ + status: z.enum([...coverageStatusSchema.options, "unsupported"]), examined_bytes: uint, examined_entries: uint, }), diff --git a/src/native/elf/KernelBuildConfig.test.ts b/src/native/elf/KernelBuildConfig.test.ts index 8829319c58..6dab182bf1 100644 --- a/src/native/elf/KernelBuildConfig.test.ts +++ b/src/native/elf/KernelBuildConfig.test.ts @@ -204,7 +204,7 @@ it("reports a framed member whose text fails the grammar as malformed, not absen option_count: 0, entries: [], }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect( report.limitations.some((line) => line.includes("not a .config")), ).toBe(true); @@ -219,7 +219,7 @@ it("reports a framed member with a bad CRC-32 as malformed, not absent", async ( sha256: null, option_count: 0, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect(report.limitations.some((line) => line.includes("CRC-32"))).toBe(true); }); @@ -274,7 +274,7 @@ it("reports a framed member that does not decode as malformed, not absent", asyn gzip: { space: "file", offset: 8, bytes: body.length }, end_marker: { space: "file", offset: bytes.length - 8, bytes: 8 }, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect( (await parse(Buffer.concat([bytes, embeddedKernelConfig()]))).config .status, @@ -296,7 +296,7 @@ it("reports a truncated IKCFG member as incomplete, not absent", async () => { status: "incomplete", reason: "config_gzip_truncated", }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("partial"); }); it("inflates a bzImage gzip payload and reports payload-relative offsets", async () => { @@ -332,15 +332,16 @@ it("names an xz bzImage payload as unsupported without searching it", async () = }); }); -it("keeps truncated and unusable bzImage payloads incomplete", async () => { +it("keeps coverage unknown for truncated and unusable bzImage payloads", async () => { const truncated = await parse(bzImageTruncatedGzipFixture()); expect(truncated.payload.status).toBe("truncated"); expect(truncated.config.reason).toBe("payload_truncated"); - expect(truncated.coverage.status).toBe("incomplete"); + expect(truncated.coverage.status).toBe("unknown"); const old = await parse(bzImageFixture(gzipSync("x"), { version: 0x0206 })); expect(old.payload.status).toBe("unavailable"); expect(old.config.reason).toBe("setup_header_payload_unavailable"); + expect(old.coverage).toMatchObject({ status: "unknown", examined_bytes: 0 }); const short = bzImageFixture(gzipSync("x")); short.writeUInt32LE(0xffff, 0x24c); @@ -414,7 +415,7 @@ it("stops inflating decoy candidates after the candidate cap and reports incompl reason: "config_search_exhausted", marker: null, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("partial"); expect( report.limitations.some((line) => line.includes("16 IKCFG_ST gzip")), ).toBe(true); @@ -737,7 +738,7 @@ it("retains incomplete coverage for a partial config end marker", async () => { reason: "config_gzip_truncated", entries: [], }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("partial"); }); it("ignores marker bytes inside a gzip member", async () => { diff --git a/src/native/elf/KernelBuildConfig.ts b/src/native/elf/KernelBuildConfig.ts index 7d4e320c30..891486e4df 100644 --- a/src/native/elf/KernelBuildConfig.ts +++ b/src/native/elf/KernelBuildConfig.ts @@ -769,7 +769,6 @@ const reportFromSearch = async ( ...blobRanges(found, search.space), } : acceptedConfig(found, input, search.space); - const complete = found === "absent" || config.status === "present"; const banner = await findBanner(search.bytes, search.space, signal); return { artifact, @@ -779,7 +778,14 @@ const reportFromSearch = async ( banner, config, coverage: { - status: complete ? "complete" : "incomplete", + status: + found === "absent" || config.status === "present" + ? "complete" + : // A member cut by the searched bytes, or candidates the budget + // left uninflated, is a known gap; a malformed config is unreadable. + found === "truncated" || found === "exhausted" + ? "partial" + : "unknown", examined_bytes: search.bytes.length, examined_entries: config.option_count, }, @@ -857,7 +863,12 @@ const closedReport = ( : null, banner: absentBanner("unknown"), config: emptyConfig(input, status, reason), - coverage: { status, examined_bytes: 0, examined_entries: 0 }, + // Nothing was searched, so whether a config exists cannot be determined. + coverage: { + status: status === "incomplete" ? "unknown" : status, + examined_bytes: 0, + examined_entries: 0, + }, limitations: [...baseLimitations(), limitation], }); diff --git a/tests/boundary/mcp/kernelBuildConfigMcp.test.ts b/tests/boundary/mcp/kernelBuildConfigMcp.test.ts index 05144c982b..1eba75d657 100644 --- a/tests/boundary/mcp/kernelBuildConfigMcp.test.ts +++ b/tests/boundary/mcp/kernelBuildConfigMcp.test.ts @@ -94,7 +94,7 @@ mcpTest("reports a truncated IKCFG member as incomplete", async ({ mcp }) => { const evidence = contract.outputSchema.parse(response.structuredContent); expect(evidence.normalized_result).toMatchObject({ config: { status: "incomplete", reason: "config_gzip_truncated" }, - coverage: { status: "incomplete" }, + coverage: { status: "partial" }, }); } finally { await session.close();