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`.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 05:01:36 +08:00
1 parent 0a9e736aea
commit acb10754c1
9 files changed
+71 -23

No files matched your search

+8 -3
View File
@@ -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 |
| ---------------------------------- | ---------------------------------------------------------------------------- |
@@ -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
@@ -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,
@@ -144,6 +144,26 @@ it.each([
};
},
],
[
"a malformed config reported as a partial gap",
async (): Promise<KernelBuildConfig> => {
const malformed = await reportOf(nonConfigGzipFixture());
return {
...malformed,
coverage: { ...malformed.coverage, status: "partial" },
};
},
],
[
"a truncated config reported with unknown coverage",
async (): Promise<KernelBuildConfig> => {
const truncated = await reportOf(truncatedKernelConfigFixture());
return {
...truncated,
coverage: { ...truncated.coverage, status: "unknown" },
};
},
],
[
"an incomplete config carrying a malformed reason",
async (): Promise<KernelBuildConfig> => {
@@ -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"
);
};
+9 -1
View File
@@ -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,
}),
+9 -8
View File
@@ -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 () => {
+14 -3
View File
@@ -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],
});
@@ -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();