refactor(artifact): simplify extraction and inventory results

This commit is contained in:
morluto
2026-09-29 08:07:04 +08:00
parent 81996df7a5
commit 07ff8b30ee
24 changed files with 200 additions and 416 deletions
+4 -9
View File
@@ -26,20 +26,15 @@ import type { BinaryTarget } from "../domain/binaryTarget.js";
import { scanArtifactInventory } from "./ArtifactInventory.js";
import {
digestCanonical,
pageOf,
toOutputLimits,
} from "./ArtifactGraphConstruction.js";
const PAGE_SIZE = 500;
/** Already-approved extraction request from a caller-owned policy boundary. */
export interface ArtifactExtractionInput {
readonly inputPath: string;
readonly inputFormat: BinaryTarget["format"];
readonly outputRoot: string;
readonly occurrenceIds: readonly string[];
readonly offset: number;
readonly limit: number;
readonly limits: ArtifactLimits;
}
@@ -201,8 +196,8 @@ const createExtractionResult = (
...extractionSemantic,
extraction_id: `aex_${digestCanonical(extractionSemantic)}`,
},
output_root: "$OUTPUT_ROOT",
artifacts: pageOf(extracted, input.offset, input.limit),
output_root: input.outputRoot,
artifacts: extracted,
containment_verified: true,
cleanup: { attempted: false, verified: true, residual_paths: [] },
limits: toOutputLimits(input.limits),
@@ -284,10 +279,10 @@ const createReader = async (
};
const validateSelection = (ids: readonly string[]): void => {
if (ids.length === 0 || ids.length > PAGE_SIZE)
if (ids.length === 0)
throw new ArtifactReaderFailure(
"limit",
"Extraction requires 1 to 500 explicitly selected occurrences",
"Extraction requires at least one explicitly selected occurrence",
);
if (new Set(ids).size !== ids.length)
throw new ArtifactReaderFailure(
@@ -0,0 +1,7 @@
import { randomUUID } from "node:crypto";
import { tmpdir } from "node:os";
import { join } from "node:path";
/** Choose a fresh temporary destination for an artifact extraction. */
export const createArtifactExtractionDestination = (): string =>
join(tmpdir(), `rea-extracted-${randomUUID()}`);
@@ -318,18 +318,6 @@ export const classifyArtifactContent = (
return byPath;
};
export const pageOf = <Value>(
items: readonly Value[],
offset: number,
limit: number,
) => ({
items: items.slice(offset, offset + limit),
offset,
limit,
total: items.length,
next_offset: offset + limit < items.length ? offset + limit : null,
});
export const toOutputLimits = (limits: ArtifactLimits) => ({
max_entries: limits.maxEntries,
max_total_bytes: limits.maxTotalBytes,
+2 -29
View File
@@ -5,7 +5,6 @@ import {
artifactInventoryResultSchema,
type ArtifactInventoryResult,
} from "../domain/artifactGraph.js";
import { pageOf } from "./ArtifactGraphConstruction.js";
import { abortIfNeeded } from "./ArtifactInventory/hash.js";
import { scanCanonicalArtifactInventory } from "./ArtifactInventory/scanCanonical.js";
import type {
@@ -13,7 +12,6 @@ import type {
ArtifactInventoryOptions,
ArtifactInventorySnapshot,
ArtifactNativeMountPolicy,
InventoryPageInput,
} from "./ArtifactInventory/types.js";
export { scanCanonicalArtifactInventory } from "./ArtifactInventory/scanCanonical.js";
@@ -23,14 +21,12 @@ export type {
ArtifactInventoryOptions,
ArtifactInventorySnapshot,
ArtifactNativeMountPolicy,
InventoryPageInput,
} from "./ArtifactInventory/types.js";
/** Inventory one local artifact without extracting or mounting it. */
export const inventoryArtifact = async (
inputPath: string,
limits: ArtifactLimits,
page: InventoryPageInput,
options: {
readonly signal?: AbortSignal;
readonly nativeMount?: ArtifactNativeMountPolicy;
@@ -38,7 +34,7 @@ export const inventoryArtifact = async (
} = {},
): Promise<ArtifactInventoryResult> => {
const snapshot = await scanArtifactInventory(inputPath, limits, options);
return paginateArtifactInventory(snapshot, page);
return artifactInventoryResultSchema.parse(snapshot);
};
/** Inventory one artifact and return every graph collection in one response. */
@@ -52,14 +48,7 @@ export const inventoryArtifactFully = async (
} = {},
): Promise<ArtifactInventoryResult> => {
const snapshot = await scanArtifactInventory(inputPath, limits, options);
return paginateArtifactInventory(snapshot, {
nodeOffset: 0,
nodeLimit: Math.max(1, snapshot.nodes.length),
occurrenceOffset: 0,
occurrenceLimit: Math.max(1, snapshot.occurrences.length),
edgeOffset: 0,
edgeLimit: Math.max(1, snapshot.edges.length),
});
return artifactInventoryResultSchema.parse(snapshot);
};
/** Scan an artifact once and retain the complete immutable graph for projection. */
@@ -72,19 +61,3 @@ export const scanArtifactInventory = async (
const path = await realpath(inputPath);
return scanCanonicalArtifactInventory(path, limits, options);
};
/** Project independently paged graph collections from one inventory snapshot. */
export const paginateArtifactInventory = (
snapshot: ArtifactInventorySnapshot,
page: InventoryPageInput,
): ArtifactInventoryResult =>
artifactInventoryResultSchema.parse({
...snapshot,
nodes: pageOf(snapshot.nodes, page.nodeOffset, page.nodeLimit),
occurrences: pageOf(
snapshot.occurrences,
page.occurrenceOffset,
page.occurrenceLimit,
),
edges: pageOf(snapshot.edges, page.edgeOffset, page.edgeLimit),
});
+1 -4
View File
@@ -7,10 +7,7 @@ import type {
/** Parsed caller intent for integrity mismatch handling. */
export type ArtifactIntegrityIntent =
| { readonly mode: "fail" }
| {
readonly mode: "record-and-continue";
readonly maxMismatches: number;
};
| { readonly mode: "record-and-continue" };
/** Resolve caller approval and operator policy before native reader selection. */
export const resolveNativeMountPolicy = (
@@ -179,11 +179,6 @@ const digestArtifactEntry = async (
unpacked: entry.unpacked,
},
);
if (context.pendingContradictions.length >= context.integrity.maxMismatches)
throw new ArtifactReaderFailure(
"limit",
"Artifact integrity mismatch limit exceeded",
);
context.pendingContradictions.push({
logicalPath,
declaredSha256: entry.declaredSha256,
+3 -15
View File
@@ -4,15 +4,6 @@ import type {
IntegrityContradiction,
} from "../../domain/artifactGraph.js";
export interface InventoryPageInput {
readonly nodeOffset: number;
readonly nodeLimit: number;
readonly occurrenceOffset: number;
readonly occurrenceLimit: number;
readonly edgeOffset: number;
readonly edgeLimit: number;
}
/** Resolved native mount authority admitted to the artifact reader. */
export type ArtifactNativeMountPolicy =
| { readonly status: "disabled" }
@@ -25,10 +16,7 @@ export const NATIVE_MOUNT_DISABLED: ArtifactNativeMountPolicy = {
/** Resolved integrity behavior admitted to the artifact scanner. */
export type ArtifactIntegrityPolicy =
| { readonly mode: "fail" }
| {
readonly mode: "record-and-continue";
readonly maxMismatches: number;
};
| { readonly mode: "record-and-continue" };
export const STRICT_INTEGRITY_POLICY: ArtifactIntegrityPolicy = {
mode: "fail",
@@ -45,8 +33,8 @@ export interface ArtifactInventoryOptions {
export interface ArtifactInventorySnapshot {
readonly manifest: ArtifactInventoryResult["manifest"];
readonly nodes: readonly ArtifactNode[];
readonly occurrences: ArtifactInventoryResult["occurrences"]["items"];
readonly edges: ArtifactInventoryResult["edges"]["items"];
readonly occurrences: ArtifactInventoryResult["occurrences"];
readonly edges: ArtifactInventoryResult["edges"];
readonly limits: ArtifactInventoryResult["limits"];
readonly provenance: ReadonlyArray<
ArtifactInventoryResult["provenance"][number]
@@ -26,16 +26,10 @@ describe("artifact inventory policy resolution", () => {
it("admits parsed continuation intent only under operator policy", () => {
expect(() =>
resolveArtifactIntegrityPolicy(
{ mode: "record-and-continue", maxMismatches: 10 },
false,
),
resolveArtifactIntegrityPolicy({ mode: "record-and-continue" }, false),
).toThrow("requires explicit approval and operator policy");
expect(
resolveArtifactIntegrityPolicy(
{ mode: "record-and-continue", maxMismatches: 10 },
true,
),
).toEqual({ mode: "record-and-continue", maxMismatches: 10 });
resolveArtifactIntegrityPolicy({ mode: "record-and-continue" }, true),
).toEqual({ mode: "record-and-continue" });
});
});