refactor(test): colocate pure-domain tests and reduce test debt (#471)
* refactor(test): colocate pure-domain tests and reduce test debt Move focused immutable domain/contracts/adapter tests from tests/composition/** beside their production owners under src/** as colocated *.test.ts/*.fixture.ts, and relocate persistence-shaped composition tests under tests/boundary/filesystem/**. Update import paths, the Vitest project topology (shared worker context for pure domain/contracts and recording-port service projects), the test migration ledger, testing docs, and AGENTS.md to match. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> * docs: remove test migration ledger The cutover is complete and the ledger is no longer referenced anywhere in source, scripts, or the docs gate. Drop the standalone artifact. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> * docs: clean up stale migration artifacts Remove empty directories left by the test migration and replace the "final cutover" language in docs/testing.md with standing PR guidance that no longer references the completed migration. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix: repair CI failures from schema, knip, and stale generated artifacts Three root causes fixed: 1. catalog-schemas.mjs: valuesAt only traversed anyOf from Zod's toJSONSchema, not oneOf. The webScreenshotDiffSchema change to a discriminated union produces oneOf, so the product catalog generator could not derive the web_screenshot_diff schema version. Add oneOf traversal. 2. conformancePackage.ts: the test rewrite removed the only imports of ScenarioManifest, ReplayPlan, ShimPlan, and ExpectedEvidence, making them unused exports that knip flags. Remove the dead type aliases. 3. Regenerate stale artifacts (product catalog, MCP tool catalog, skill metadata, conformance manifest) that drifted from the source changes. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
co-authored by
Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
parent
344b9b6dff
commit
e91c8c39c2
@@ -0,0 +1,213 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
getNavigationContext,
|
||||
inspectAddressContext,
|
||||
} from "./AnalysisContextQueries.js";
|
||||
import {
|
||||
createAnalysisExecution,
|
||||
type AnalysisOperationPort,
|
||||
} from "./AnalysisProvider.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisProtocolError,
|
||||
} from "../domain/errors.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
|
||||
describe("analysis context queries: navigation", () => {
|
||||
it("aggregates volatile navigation and treats a missing procedure as null", async () => {
|
||||
const calls: {
|
||||
operation: string;
|
||||
parameters: Readonly<Record<string, unknown>>;
|
||||
}[] = [];
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: (operation, parameters) => {
|
||||
calls.push({ operation, parameters });
|
||||
if (operation === "current_document")
|
||||
return Promise.resolve(
|
||||
ok(createAnalysisExecution("fixture", provider)),
|
||||
);
|
||||
if (operation === "current_address")
|
||||
return Promise.resolve(
|
||||
ok(createAnalysisExecution("0x401000", provider)),
|
||||
);
|
||||
if (operation === "resolve_containing_procedure")
|
||||
return Promise.resolve(
|
||||
ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
query_address: "0x401000",
|
||||
found: false,
|
||||
procedure: null,
|
||||
reason: "not_in_procedure",
|
||||
},
|
||||
provider,
|
||||
),
|
||||
),
|
||||
);
|
||||
return Promise.resolve(
|
||||
err(new AnalysisProtocolError(`unexpected ${operation}`)),
|
||||
);
|
||||
},
|
||||
};
|
||||
|
||||
await expect(getNavigationContext(analysis, {})).resolves.toEqual(
|
||||
ok({
|
||||
document: "fixture",
|
||||
address: "0x401000",
|
||||
procedure: null,
|
||||
}),
|
||||
);
|
||||
expect(calls).toContainEqual({
|
||||
operation: "current_document",
|
||||
parameters: {},
|
||||
});
|
||||
expect(calls).toContainEqual({
|
||||
operation: "resolve_containing_procedure",
|
||||
parameters: { document: "fixture", address: "0x401000" },
|
||||
});
|
||||
});
|
||||
|
||||
it("uses an explicit document without passing it to current_document and preserves procedure failures", async () => {
|
||||
const calls: string[] = [];
|
||||
const failure = new AnalysisProtocolError("provider response malformed");
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: (operation) => {
|
||||
calls.push(operation);
|
||||
if (operation === "current_address")
|
||||
return Promise.resolve(
|
||||
ok(createAnalysisExecution("0x401000", provider)),
|
||||
);
|
||||
return Promise.resolve(err(failure));
|
||||
},
|
||||
};
|
||||
|
||||
await expect(
|
||||
getNavigationContext(analysis, { document: "fixture" }),
|
||||
).resolves.toEqual(err(failure));
|
||||
expect(calls).toEqual(["current_address", "resolve_containing_procedure"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("analysis context queries: address facets", () => {
|
||||
it("keeps unsupported address facets local and filters bookmarks", async () => {
|
||||
const bookmarkInputs: Readonly<Record<string, unknown>>[] = [];
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: (operation, input) => {
|
||||
if (operation === "current_document")
|
||||
return Promise.resolve(
|
||||
ok(createAnalysisExecution("fixture", provider)),
|
||||
);
|
||||
if (operation === "comment")
|
||||
return Promise.resolve(
|
||||
err(new AnalysisProtocolError("comments unavailable")),
|
||||
);
|
||||
switch (operation) {
|
||||
case "address_name":
|
||||
return Promise.resolve(
|
||||
ok(createAnalysisExecution("entry", provider)),
|
||||
);
|
||||
case "resolve_containing_procedure":
|
||||
return Promise.resolve(
|
||||
ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
query_address: "0x401000",
|
||||
found: true,
|
||||
procedure: { address: "0x401000", name: "main" },
|
||||
},
|
||||
provider,
|
||||
),
|
||||
),
|
||||
);
|
||||
case "inline_comment":
|
||||
return Promise.resolve(ok(createAnalysisExecution(null, provider)));
|
||||
case "list_bookmarks":
|
||||
bookmarkInputs.push(input);
|
||||
return Promise.resolve(
|
||||
ok(
|
||||
createAnalysisExecution(
|
||||
[
|
||||
{ address: "0x401000", name: "review" },
|
||||
{ address: "0x402000", name: "other" },
|
||||
],
|
||||
provider,
|
||||
),
|
||||
),
|
||||
);
|
||||
default:
|
||||
return Promise.resolve(
|
||||
err(new AnalysisProtocolError(`unexpected ${operation}`)),
|
||||
);
|
||||
}
|
||||
},
|
||||
};
|
||||
|
||||
const result = await inspectAddressContext(analysis, {
|
||||
address: "401000",
|
||||
});
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
document: "fixture",
|
||||
name: { state: "available", value: "entry" },
|
||||
comment: {
|
||||
state: "unavailable",
|
||||
reason: "comments unavailable",
|
||||
},
|
||||
bookmarks: {
|
||||
state: "available",
|
||||
value: [{ address: "0x401000", name: "review" }],
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(bookmarkInputs).toEqual([{ document: "fixture" }]);
|
||||
});
|
||||
|
||||
it("propagates cancellation instead of degrading it to an unavailable facet", async () => {
|
||||
const cancelled = new AnalysisCancelledError("comment");
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: (operation) =>
|
||||
Promise.resolve(
|
||||
operation === "comment"
|
||||
? err(cancelled)
|
||||
: ok(createAnalysisExecution(null, provider)),
|
||||
),
|
||||
};
|
||||
|
||||
await expect(
|
||||
inspectAddressContext(analysis, {
|
||||
address: "0x401000",
|
||||
document: "fixture",
|
||||
}),
|
||||
).resolves.toEqual(err(cancelled));
|
||||
});
|
||||
|
||||
it("reports malformed bookmark output as unavailable instead of empty", async () => {
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: (operation) =>
|
||||
Promise.resolve(
|
||||
operation === "list_bookmarks"
|
||||
? ok(createAnalysisExecution({ malformed: true }, provider))
|
||||
: ok(createAnalysisExecution(null, provider)),
|
||||
),
|
||||
};
|
||||
|
||||
await expect(
|
||||
inspectAddressContext(analysis, {
|
||||
address: "0x401000",
|
||||
document: "fixture",
|
||||
}),
|
||||
).resolves.toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
bookmarks: {
|
||||
state: "unavailable",
|
||||
reason: expect.stringContaining("malformed"),
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,82 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { createAnalysisProfile } from "../domain/analysisProfile.js";
|
||||
import {
|
||||
ANALYSIS_SNAPSHOT_PROFILE,
|
||||
ANALYSIS_SNAPSHOT_PROVIDER,
|
||||
ANALYSIS_SNAPSHOT_TARGET,
|
||||
} from "../domain/analysisSnapshot.fixture.js";
|
||||
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { createAnalysisExecution } from "./AnalysisProvider.js";
|
||||
import { AnalysisSnapshotCache } from "./AnalysisSnapshotCache.js";
|
||||
|
||||
describe("analysis snapshot cache partitioning", () => {
|
||||
it("returns detached data only from the exact provider/profile partition", () => {
|
||||
const cache = new AnalysisSnapshotCache();
|
||||
const execution = createAnalysisExecution(
|
||||
"main",
|
||||
ANALYSIS_SNAPSHOT_PROVIDER,
|
||||
{ analysisProfile: ANALYSIS_SNAPSHOT_PROFILE },
|
||||
);
|
||||
cache.record({
|
||||
target: ANALYSIS_SNAPSHOT_TARGET,
|
||||
profile: ANALYSIS_SNAPSHOT_PROFILE,
|
||||
operation: "address_name",
|
||||
parameters: { address: "0x1000", document: "fixture" },
|
||||
execution,
|
||||
});
|
||||
const exported = cache.export(
|
||||
ANALYSIS_SNAPSHOT_TARGET,
|
||||
ANALYSIS_SNAPSHOT_PROFILE,
|
||||
createEvidenceBundle([]),
|
||||
);
|
||||
expect(exported.ok).toBe(true);
|
||||
if (!exported.ok) return;
|
||||
const entry = exported.value.entries[0];
|
||||
if (entry !== undefined) {
|
||||
Reflect.set(entry.execution, "provider", {
|
||||
id: "forged",
|
||||
name: "Forged",
|
||||
version: "9",
|
||||
});
|
||||
entry.execution.limitations.push("forged");
|
||||
}
|
||||
|
||||
expect(
|
||||
cache.lookup(
|
||||
ANALYSIS_SNAPSHOT_TARGET,
|
||||
ANALYSIS_SNAPSHOT_PROFILE,
|
||||
"address_name",
|
||||
{ address: "0x1000", document: "fixture" },
|
||||
),
|
||||
).toMatchObject({
|
||||
provider: ANALYSIS_SNAPSHOT_PROVIDER,
|
||||
analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
|
||||
limitations: [expect.stringContaining("local REA analysis snapshot")],
|
||||
});
|
||||
const changedProfile = createAnalysisProfile(
|
||||
ANALYSIS_SNAPSHOT_PROVIDER,
|
||||
1,
|
||||
{ loader: "configured-override" },
|
||||
);
|
||||
expect(
|
||||
cache.lookup(ANALYSIS_SNAPSHOT_TARGET, changedProfile, "address_name", {
|
||||
address: "0x1000",
|
||||
document: "fixture",
|
||||
}),
|
||||
).toBeUndefined();
|
||||
const changedProviderProfile = createAnalysisProfile(
|
||||
{ id: "other", name: "Other", version: "1" },
|
||||
1,
|
||||
{ loader: "mach-o-arm64" },
|
||||
);
|
||||
expect(
|
||||
cache.lookup(
|
||||
ANALYSIS_SNAPSHOT_TARGET,
|
||||
changedProviderProfile,
|
||||
"address_name",
|
||||
{ address: "0x1000", document: "fixture" },
|
||||
),
|
||||
).toBeUndefined();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,41 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
resolveArtifactIntegrityPolicy,
|
||||
resolveNativeMountPolicy,
|
||||
} from "./ArtifactInventory/policy.js";
|
||||
|
||||
describe("artifact inventory policy resolution", () => {
|
||||
it("admits native mounting only when caller and operator both allow it", () => {
|
||||
expect(resolveNativeMountPolicy(false, true)).toEqual({
|
||||
status: "disabled",
|
||||
});
|
||||
expect(() => resolveNativeMountPolicy(true, false)).toThrow(
|
||||
"disabled by operator policy",
|
||||
);
|
||||
expect(resolveNativeMountPolicy(true, true)).toEqual({
|
||||
status: "approved",
|
||||
});
|
||||
});
|
||||
|
||||
it("projects strict integrity without dormant continuation state", () => {
|
||||
expect(resolveArtifactIntegrityPolicy({ mode: "fail" }, true)).toEqual({
|
||||
mode: "fail",
|
||||
});
|
||||
});
|
||||
|
||||
it("admits parsed continuation intent only under operator policy", () => {
|
||||
expect(() =>
|
||||
resolveArtifactIntegrityPolicy(
|
||||
{ mode: "record-and-continue", maxMismatches: 10 },
|
||||
false,
|
||||
),
|
||||
).toThrow("requires explicit approval and operator policy");
|
||||
expect(
|
||||
resolveArtifactIntegrityPolicy(
|
||||
{ mode: "record-and-continue", maxMismatches: 10 },
|
||||
true,
|
||||
),
|
||||
).toEqual({ mode: "record-and-continue", maxMismatches: 10 });
|
||||
});
|
||||
});
|
||||
@@ -15,12 +15,8 @@ import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import type {
|
||||
AnalysisClient,
|
||||
AnalysisExecution,
|
||||
AnalysisClientFactory,
|
||||
ExecutionOptions,
|
||||
AnalysisProfileResolution,
|
||||
AnalysisProfileResolutionOptions,
|
||||
AnalysisOperationPort,
|
||||
AnalysisProvider,
|
||||
ProviderIdentity,
|
||||
} from "./AnalysisProvider.js";
|
||||
import type { AnalysisOperation } from "./AnalysisProvider.js";
|
||||
@@ -80,23 +76,9 @@ export class BinarySession
|
||||
>();
|
||||
readonly #availabilityListeners = new Set<() => void | Promise<void>>();
|
||||
|
||||
constructor(
|
||||
readonly provider:
|
||||
| AnalysisProvider
|
||||
| AnalysisClientFactory
|
||||
| SessionProviderRouter,
|
||||
options: {
|
||||
readonly resolveAnalysisProfile?: (
|
||||
target: BinaryTarget,
|
||||
options?: AnalysisProfileResolutionOptions,
|
||||
) => Promise<Result<AnalysisProfileResolution, AnalysisError>>;
|
||||
} = {},
|
||||
) {
|
||||
constructor(providerRouter: SessionProviderRouter) {
|
||||
super();
|
||||
this.#providerRouter =
|
||||
provider instanceof SessionProviderRouter
|
||||
? provider
|
||||
: SessionProviderRouter.legacy(provider, options);
|
||||
this.#providerRouter = providerRouter;
|
||||
}
|
||||
|
||||
/** Identify the provider producing evidence for this session. */
|
||||
|
||||
@@ -1,33 +1,7 @@
|
||||
import type {
|
||||
AnalysisClientFactory,
|
||||
AnalysisProfileResolution,
|
||||
AnalysisProfileResolutionOptions,
|
||||
AnalysisProvider,
|
||||
} from "./AnalysisProvider.js";
|
||||
import type { AnalysisProvider } from "./AnalysisProvider.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { BinarySession } from "./BinarySession.js";
|
||||
import { SessionProviderRouter } from "./SessionProviderRouter.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import type { AnalysisError } from "../domain/errors.js";
|
||||
import type { Result } from "../domain/result.js";
|
||||
|
||||
type BinarySessionOptions = {
|
||||
readonly resolveAnalysisProfile?: (
|
||||
target: BinaryTarget,
|
||||
options?: AnalysisProfileResolutionOptions,
|
||||
) => Promise<Result<AnalysisProfileResolution, AnalysisError>>;
|
||||
};
|
||||
|
||||
type BinarySessionOptionsOrResolver =
|
||||
| BinarySessionOptions
|
||||
| BinarySessionOptions["resolveAnalysisProfile"];
|
||||
|
||||
const normalizeBinarySessionOptions = (
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySessionOptions =>
|
||||
typeof optionsOrResolver === "function"
|
||||
? { resolveAnalysisProfile: optionsOrResolver }
|
||||
: (optionsOrResolver ?? {});
|
||||
|
||||
/**
|
||||
* Compose one provider-neutral session from deep-provider selection and
|
||||
@@ -42,21 +16,3 @@ export const composeBinarySession = (
|
||||
? registry
|
||||
: SessionProviderRouter.selectable(registry, auxiliaryProviders),
|
||||
);
|
||||
|
||||
/**
|
||||
* Compose a session through the same internal seam for focused adapter tests.
|
||||
* The constructor remains private to this composition module, so callers test
|
||||
* provider behavior without coupling to BinarySession construction.
|
||||
*/
|
||||
export const composeBinarySessionFromFactory = (
|
||||
provider: AnalysisProvider | AnalysisClientFactory | SessionProviderRouter,
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySession =>
|
||||
new BinarySession(provider, normalizeBinarySessionOptions(optionsOrResolver));
|
||||
|
||||
/** Compose a focused session from any provider-shaped test seam. */
|
||||
export const composeBinarySessionFromProvider = (
|
||||
provider: AnalysisProvider | AnalysisClientFactory | SessionProviderRouter,
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySession =>
|
||||
new BinarySession(provider, normalizeBinarySessionOptions(optionsOrResolver));
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { listBrowserTargetsInputSchema } from "../domain/browserObservation.js";
|
||||
import { listBrowserTargets } from "./BrowserObservationService.js";
|
||||
import { createPermissionAuthority } from "./PermissionAuthority.js";
|
||||
|
||||
describe("browser observation authorization", () => {
|
||||
it("requests loopback authority for an IPv6-only browser origin", async () => {
|
||||
const endpoint = "http://127.0.0.1:9222";
|
||||
const origin = "http://[::1]:3000";
|
||||
const ceiling = {
|
||||
capability: "browser_observe" as const,
|
||||
roots: [],
|
||||
executables: [],
|
||||
environment_names: [],
|
||||
origins: [endpoint, origin],
|
||||
network: "loopback" as const,
|
||||
mount: false,
|
||||
};
|
||||
const authority = await createPermissionAuthority(
|
||||
[ceiling],
|
||||
[
|
||||
{
|
||||
...ceiling,
|
||||
grant_id: "administrator:browser_observe",
|
||||
lifetime: "administrator",
|
||||
operation_identity: null,
|
||||
expires_at: null,
|
||||
},
|
||||
],
|
||||
);
|
||||
if (!authority.ok) throw authority.error;
|
||||
|
||||
const result = await listBrowserTargets(
|
||||
undefined,
|
||||
authority.value,
|
||||
listBrowserTargetsInputSchema.parse({
|
||||
cdp_endpoint: endpoint,
|
||||
allowed_origins: [origin],
|
||||
approved: true,
|
||||
}),
|
||||
);
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "AnalysisCapabilityUnavailableError" },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,30 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { toolAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
|
||||
import { buildCapabilityInventory } from "./CapabilityInventory.js";
|
||||
|
||||
describe("capability inventory contract", () => {
|
||||
it("produces valid availability and rejects contradictory states", () => {
|
||||
const inventory = buildCapabilityInventory(
|
||||
{ open: false, capabilities: [] },
|
||||
{
|
||||
processCaptureEnabled: false,
|
||||
evidenceFileRoots: 0,
|
||||
investigationInputRoots: 0,
|
||||
},
|
||||
);
|
||||
const unavailable = inventory.find(({ available }) => !available);
|
||||
expect(unavailable).toBeDefined();
|
||||
expect(toolAvailability.safeParse(unavailable).success).toBe(true);
|
||||
expect(
|
||||
toolAvailability.safeParse({ ...unavailable, available: true }).success,
|
||||
).toBe(false);
|
||||
expect(
|
||||
toolAvailability.safeParse({
|
||||
...unavailable,
|
||||
available: false,
|
||||
reason: "available",
|
||||
}).success,
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,310 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { buildCapabilityInventory } from "./CapabilityInventory.js";
|
||||
|
||||
const enabledPolicy: Parameters<typeof buildCapabilityInventory>[1] = {
|
||||
processCaptureEnabled: true,
|
||||
evidenceFileRoots: 1,
|
||||
investigationInputRoots: 1,
|
||||
browserObservationEnabled: true,
|
||||
browserScenarioEnabled: true,
|
||||
electronObservationEnabled: true,
|
||||
v8InspectorObservationEnabled: true,
|
||||
javascriptReplayEnabled: true,
|
||||
managedRuntimeEnabled: true,
|
||||
};
|
||||
|
||||
const status = (
|
||||
options: {
|
||||
readonly open?: boolean;
|
||||
readonly kind?: "executable" | "database" | "archive" | "artifact";
|
||||
readonly capabilities?: readonly {
|
||||
readonly operation: string;
|
||||
readonly available: boolean;
|
||||
readonly reason: string | null;
|
||||
readonly availability_code?: "unsupported_host";
|
||||
}[];
|
||||
} = {},
|
||||
) => ({
|
||||
open: options.open ?? false,
|
||||
...(options.kind === undefined ? {} : { kind: options.kind }),
|
||||
capabilities: (options.capabilities ?? []).map((capability) => ({
|
||||
...capability,
|
||||
availability_code: capability.available
|
||||
? null
|
||||
: (capability.availability_code ?? null),
|
||||
input_contract_version: 1,
|
||||
output_contract_version: 1,
|
||||
pagination: "none" as const,
|
||||
exhaustive: true,
|
||||
effects: {
|
||||
mutates_artifact: false,
|
||||
launches_process: false,
|
||||
may_show_ui: false,
|
||||
may_access_network: false,
|
||||
may_write_filesystem: false,
|
||||
changes_permissions: false,
|
||||
requires_root: false,
|
||||
},
|
||||
limits: {
|
||||
max_results: null,
|
||||
max_payload_bytes: null,
|
||||
timeout_ms: null,
|
||||
},
|
||||
limitations: [],
|
||||
})),
|
||||
});
|
||||
|
||||
const entry = (
|
||||
name: string,
|
||||
sessionStatus: ReturnType<typeof status>,
|
||||
policy = enabledPolicy,
|
||||
) => {
|
||||
const found = buildCapabilityInventory(sessionStatus, policy).find(
|
||||
(candidate) => candidate.name === name,
|
||||
);
|
||||
if (found === undefined) throw new Error(`missing capability ${name}`);
|
||||
return found;
|
||||
};
|
||||
|
||||
describe("capability inventory: provider status", () => {
|
||||
it.each([
|
||||
{
|
||||
label: "requires a target",
|
||||
name: "current_address",
|
||||
sessionStatus: status(),
|
||||
reason: "target_required",
|
||||
remediation: "open_binary",
|
||||
},
|
||||
{
|
||||
label: "rejects an incompatible target family",
|
||||
name: "current_address",
|
||||
sessionStatus: status({ open: true, kind: "archive" }),
|
||||
reason: "target_unsupported",
|
||||
remediation: "native executable",
|
||||
},
|
||||
{
|
||||
label: "reports a missing provider operation",
|
||||
name: "current_address",
|
||||
sessionStatus: status({ open: true, kind: "executable" }),
|
||||
reason: "provider_missing",
|
||||
remediation: "provider",
|
||||
},
|
||||
{
|
||||
label: "distinguishes an unsupported host",
|
||||
name: "current_address",
|
||||
sessionStatus: status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: [
|
||||
{
|
||||
operation: "current_address",
|
||||
available: false,
|
||||
availability_code: "unsupported_host",
|
||||
reason: "Operation requires macOS",
|
||||
},
|
||||
],
|
||||
}),
|
||||
reason: "unsupported_host",
|
||||
remediation: "macOS",
|
||||
},
|
||||
{
|
||||
label: "retains a provider failure",
|
||||
name: "current_address",
|
||||
sessionStatus: status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: [
|
||||
{
|
||||
operation: "current_address",
|
||||
available: false,
|
||||
reason: "Provider session is unhealthy",
|
||||
},
|
||||
],
|
||||
}),
|
||||
reason: "provider_unavailable",
|
||||
remediation: "unhealthy",
|
||||
},
|
||||
{
|
||||
label: "reports an available provider operation",
|
||||
name: "current_address",
|
||||
sessionStatus: status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: [
|
||||
{
|
||||
operation: "current_address",
|
||||
available: true,
|
||||
reason: null,
|
||||
},
|
||||
],
|
||||
}),
|
||||
reason: "available",
|
||||
remediation: null,
|
||||
},
|
||||
])("$label", ({ name, sessionStatus, reason, remediation }) => {
|
||||
const availability = entry(name, sessionStatus);
|
||||
expect(availability).toMatchObject({
|
||||
reason,
|
||||
available: reason === "available",
|
||||
});
|
||||
if (remediation === null) expect(availability.remediation).toBeNull();
|
||||
else expect(availability.remediation).toContain(remediation);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["capture_process_scenario", { processCaptureEnabled: false }],
|
||||
["inspect_web_page", { browserObservationEnabled: false }],
|
||||
["capture_browser_scenario", { browserScenarioEnabled: false }],
|
||||
["inspect_electron_page", { electronObservationEnabled: false }],
|
||||
["observe_javascript_runtime", { v8InspectorObservationEnabled: false }],
|
||||
["run_controlled_replay", { javascriptReplayEnabled: false }],
|
||||
["plan_managed_runtime_correlation", { managedRuntimeEnabled: false }],
|
||||
] as const)("reports stable policy denial for %s", (name, override) => {
|
||||
const availability = entry(name, status(), {
|
||||
...enabledPolicy,
|
||||
...override,
|
||||
});
|
||||
expect(availability).toMatchObject({
|
||||
available: false,
|
||||
reason: "policy_disabled",
|
||||
});
|
||||
expect(availability.remediation).toEqual(expect.any(String));
|
||||
expect(availability.remediation?.length).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("capability inventory: caller guidance", () => {
|
||||
it("gives every unavailable public tool an actionable remediation", () => {
|
||||
const inventory = buildCapabilityInventory(status(), {
|
||||
...enabledPolicy,
|
||||
processCaptureEnabled: false,
|
||||
evidenceFileRoots: 0,
|
||||
investigationInputRoots: 0,
|
||||
browserObservationEnabled: false,
|
||||
electronObservationEnabled: false,
|
||||
v8InspectorObservationEnabled: false,
|
||||
javascriptReplayEnabled: false,
|
||||
managedRuntimeEnabled: false,
|
||||
});
|
||||
for (const availability of inventory)
|
||||
if (!availability.available) {
|
||||
expect(availability.reason).not.toBe("available");
|
||||
expect(availability.remediation).toEqual(expect.any(String));
|
||||
expect(availability.remediation?.length).toBeGreaterThan(0);
|
||||
}
|
||||
});
|
||||
|
||||
it("projects negotiated client features into per-tool requirements", () => {
|
||||
const withoutElicitation = buildCapabilityInventory(
|
||||
status(),
|
||||
enabledPolicy,
|
||||
).find(({ name }) => name === "capture_process_scenario");
|
||||
const withElicitation = buildCapabilityInventory(status(), enabledPolicy, {
|
||||
elicitation_form: true,
|
||||
elicitation_url: false,
|
||||
roots: false,
|
||||
sampling: false,
|
||||
}).find(({ name }) => name === "capture_process_scenario");
|
||||
|
||||
expect(withoutElicitation?.client_requirements).toEqual({
|
||||
required: [],
|
||||
optional: ["elicitation_form"],
|
||||
missing_required: [],
|
||||
missing_optional: ["elicitation_form"],
|
||||
});
|
||||
expect(withElicitation?.client_requirements).toEqual({
|
||||
required: [],
|
||||
optional: ["elicitation_form"],
|
||||
missing_required: [],
|
||||
missing_optional: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("allows explicit documents when the provider has no current-document getter", () => {
|
||||
const capabilities = [
|
||||
"current_document",
|
||||
"current_address",
|
||||
"resolve_containing_procedure",
|
||||
].map((operation) => ({
|
||||
operation,
|
||||
available: true,
|
||||
reason: null,
|
||||
}));
|
||||
expect(
|
||||
entry(
|
||||
"get_navigation_context",
|
||||
status({ open: true, kind: "executable", capabilities }),
|
||||
),
|
||||
).toMatchObject({
|
||||
available: true,
|
||||
reason: "available",
|
||||
default_mode_available: true,
|
||||
modes: [
|
||||
{ name: "current_selection", available: true },
|
||||
{ name: "explicit_document", available: true },
|
||||
],
|
||||
});
|
||||
expect(
|
||||
entry(
|
||||
"get_navigation_context",
|
||||
status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: capabilities.slice(1),
|
||||
}),
|
||||
),
|
||||
).toMatchObject({
|
||||
available: true,
|
||||
reason: "available",
|
||||
default_mode_available: false,
|
||||
modes: [
|
||||
{ name: "current_selection", available: false },
|
||||
{ name: "explicit_document", available: true },
|
||||
],
|
||||
});
|
||||
expect(
|
||||
entry(
|
||||
"get_navigation_context",
|
||||
status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: capabilities.slice(1, 2),
|
||||
}),
|
||||
),
|
||||
).toMatchObject({
|
||||
available: false,
|
||||
reason: "provider_missing",
|
||||
remediation: expect.stringContaining("resolve_containing_procedure"),
|
||||
});
|
||||
});
|
||||
|
||||
it("preserves the most specific navigation mode failure", () => {
|
||||
expect(
|
||||
entry(
|
||||
"get_navigation_context",
|
||||
status({
|
||||
open: true,
|
||||
kind: "executable",
|
||||
capabilities: [
|
||||
{
|
||||
operation: "current_address",
|
||||
available: false,
|
||||
availability_code: "unsupported_host",
|
||||
reason: "Navigation requires macOS.",
|
||||
},
|
||||
{
|
||||
operation: "resolve_containing_procedure",
|
||||
available: true,
|
||||
reason: null,
|
||||
},
|
||||
],
|
||||
}),
|
||||
),
|
||||
).toMatchObject({
|
||||
available: false,
|
||||
reason: "unsupported_host",
|
||||
remediation: "Navigation requires macOS.",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -8,14 +8,37 @@ import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
|
||||
import { supportedClients } from "./SupportedClients.js";
|
||||
|
||||
export interface ClientRegistrationStatus {
|
||||
interface ClientRegistrationStatusBase {
|
||||
readonly client: string;
|
||||
readonly config_path: string;
|
||||
readonly command: readonly string[];
|
||||
readonly state: "aligned" | "stale" | "missing" | "invalid";
|
||||
readonly remediation: string | null;
|
||||
}
|
||||
|
||||
type RegistrationCommand = readonly [string, ...string[]];
|
||||
|
||||
export type ClientRegistrationStatus = ClientRegistrationStatusBase &
|
||||
(
|
||||
| {
|
||||
readonly command: RegistrationCommand;
|
||||
readonly state: "aligned";
|
||||
readonly remediation: null;
|
||||
}
|
||||
| {
|
||||
readonly command: RegistrationCommand;
|
||||
readonly state: "stale";
|
||||
readonly remediation: string;
|
||||
}
|
||||
| {
|
||||
readonly command: readonly [];
|
||||
readonly state: "missing" | "invalid";
|
||||
readonly remediation: string;
|
||||
}
|
||||
);
|
||||
|
||||
export type UnhealthyClientRegistrationStatus = Exclude<
|
||||
ClientRegistrationStatus,
|
||||
{ readonly state: "aligned" }
|
||||
>;
|
||||
|
||||
const objectSchema = z.record(z.string(), z.unknown());
|
||||
const registrationSchema = z
|
||||
.object({
|
||||
@@ -44,13 +67,18 @@ export const readClientRegistrationStatuses = async (
|
||||
);
|
||||
const raw = servers[PRODUCT_IDENTITY.mcpServerKey];
|
||||
if (raw === undefined) {
|
||||
statuses.push(status(client.name, client.configPath, [], "missing"));
|
||||
statuses.push(
|
||||
unavailableStatus(client.name, client.configPath, "missing"),
|
||||
);
|
||||
continue;
|
||||
}
|
||||
const registration = registrationSchema.parse(raw);
|
||||
const command = [registration.command, ...registration.args];
|
||||
const command: RegistrationCommand = [
|
||||
registration.command,
|
||||
...registration.args,
|
||||
];
|
||||
statuses.push(
|
||||
status(
|
||||
configuredStatus(
|
||||
client.name,
|
||||
client.configPath,
|
||||
command,
|
||||
@@ -61,10 +89,9 @@ export const readClientRegistrationStatuses = async (
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
statuses.push(
|
||||
status(
|
||||
unavailableStatus(
|
||||
client.name,
|
||||
client.configPath,
|
||||
[],
|
||||
isMissing(cause) ? "missing" : "invalid",
|
||||
),
|
||||
);
|
||||
@@ -102,20 +129,29 @@ const registrationAligned = (
|
||||
);
|
||||
};
|
||||
|
||||
const status = (
|
||||
const remediation =
|
||||
"Run rea setup to refresh this registration, then restart the client.";
|
||||
|
||||
const configuredStatus = (
|
||||
client: string,
|
||||
configPath: string,
|
||||
command: readonly string[],
|
||||
state: ClientRegistrationStatus["state"],
|
||||
command: RegistrationCommand,
|
||||
state: "aligned" | "stale",
|
||||
): ClientRegistrationStatus =>
|
||||
state === "aligned"
|
||||
? { client, config_path: configPath, command, state, remediation: null }
|
||||
: { client, config_path: configPath, command, state, remediation };
|
||||
|
||||
const unavailableStatus = (
|
||||
client: string,
|
||||
configPath: string,
|
||||
state: "missing" | "invalid",
|
||||
): ClientRegistrationStatus => ({
|
||||
client,
|
||||
config_path: configPath,
|
||||
command,
|
||||
command: [],
|
||||
state,
|
||||
remediation:
|
||||
state === "aligned"
|
||||
? null
|
||||
: "Run rea setup to refresh this registration, then restart the client.",
|
||||
remediation,
|
||||
});
|
||||
|
||||
const exists = async (path: string | undefined): Promise<boolean> => {
|
||||
|
||||
@@ -19,6 +19,7 @@ import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
|
||||
import {
|
||||
readClientRegistrationStatuses,
|
||||
type ClientRegistrationStatus,
|
||||
type UnhealthyClientRegistrationStatus,
|
||||
} from "./ClientRegistrationStatus.js";
|
||||
import {
|
||||
inspectRuntimeExecutables,
|
||||
@@ -214,7 +215,10 @@ const collectDoctorIdentity = async (
|
||||
checks: [
|
||||
...(skillAligned ? [] : [skillIdentityCheck(installedSkillIdentity)]),
|
||||
...registrations
|
||||
.filter(({ state }) => state !== "aligned")
|
||||
.filter(
|
||||
(registration): registration is UnhealthyClientRegistrationStatus =>
|
||||
registration.state !== "aligned",
|
||||
)
|
||||
.map(registrationCheck),
|
||||
],
|
||||
value: {
|
||||
@@ -283,15 +287,13 @@ const skillIdentityCheck = (
|
||||
});
|
||||
|
||||
const registrationCheck = (
|
||||
registration: ClientRegistrationStatus,
|
||||
registration: UnhealthyClientRegistrationStatus,
|
||||
): DoctorCheck => ({
|
||||
name: `registration:${registration.client}`,
|
||||
ok: false,
|
||||
classification: "config_drift",
|
||||
detail: registration.config_path,
|
||||
remediation:
|
||||
registration.remediation ??
|
||||
"Run rea setup, then restart the affected client.",
|
||||
remediation: registration.remediation,
|
||||
});
|
||||
|
||||
const installationState = (
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
import type { ClientRegistrationStatus } from "./ClientRegistrationStatus.js";
|
||||
import type {
|
||||
ClientRegistrationStatus,
|
||||
UnhealthyClientRegistrationStatus,
|
||||
} from "./ClientRegistrationStatus.js";
|
||||
import type {
|
||||
DoctorCheck,
|
||||
DoctorProviderInspection,
|
||||
@@ -174,13 +177,14 @@ const selectedRegistrationCheck = (
|
||||
}
|
||||
: registrationCheck(status);
|
||||
|
||||
const registrationCheck = (status: ClientRegistrationStatus): DoctorCheck => ({
|
||||
const registrationCheck = (
|
||||
status: UnhealthyClientRegistrationStatus,
|
||||
): DoctorCheck => ({
|
||||
name: `registration:${status.client}`,
|
||||
ok: false,
|
||||
classification: "config_drift",
|
||||
detail: status.config_path,
|
||||
remediation:
|
||||
status.remediation ?? "Run rea setup, then restart the affected client.",
|
||||
remediation: status.remediation,
|
||||
});
|
||||
|
||||
const selectedSkillCheck = (
|
||||
|
||||
@@ -151,13 +151,15 @@ export const summarizeElectronBoundaries = (
|
||||
},
|
||||
sender_validation_observations: validations.length,
|
||||
utility_processes: utilities.length,
|
||||
resolved_utility_entrypoints: utilities.filter(({ file, finding }) =>
|
||||
resolvesToFile({
|
||||
file,
|
||||
specifier: finding.module_path,
|
||||
context: finding.module_resolution_context ?? "module-specifier",
|
||||
files,
|
||||
}),
|
||||
resolved_utility_entrypoints: utilities.filter(
|
||||
({ file, finding }) =>
|
||||
finding.module_path !== null &&
|
||||
resolvesToFile({
|
||||
file,
|
||||
specifier: finding.module_path,
|
||||
context: finding.module_resolution_context,
|
||||
files,
|
||||
}),
|
||||
).length,
|
||||
native_addon_bindings: nativeBindings.length,
|
||||
resolved_native_addon_bindings: nativeBindings.filter(({ file, finding }) =>
|
||||
@@ -195,14 +197,13 @@ const isMainHandler = ({ finding }: ElectronIpcRecord): boolean =>
|
||||
|
||||
interface ResolveToFileInput {
|
||||
readonly file: JavaScriptArtifactFile;
|
||||
readonly specifier: string | null;
|
||||
readonly specifier: string;
|
||||
readonly context: "module-specifier" | "filesystem-expression";
|
||||
readonly files: ReadonlyMap<string, JavaScriptArtifactFile>;
|
||||
readonly kind?: JavaScriptArtifactFile["kind"];
|
||||
}
|
||||
|
||||
const resolvesToFile = (input: ResolveToFileInput): boolean => {
|
||||
if (input.specifier === null) return false;
|
||||
const resolved = resolveArtifactPathByContext({
|
||||
declaredPath: input.specifier,
|
||||
sourcePath: input.file.path,
|
||||
|
||||
@@ -162,7 +162,7 @@ const addHandlerNode = (input: IpcHandlerInput): ApplicationNode => {
|
||||
identity: artifactLocalIdentity(
|
||||
file.sha256,
|
||||
"electron-ipc-handler",
|
||||
`${finding.side}:${finding.operation}:${finding.channel ?? finding.channel_expression ?? "[missing]"}:${electronRangeKey(handlerRange)}`,
|
||||
`${finding.side}:${finding.operation}:${finding.channel ?? finding.channel_expression}:${electronRangeKey(handlerRange)}`,
|
||||
),
|
||||
observations: [
|
||||
{
|
||||
|
||||
@@ -110,12 +110,15 @@ const addWindowPreload = (
|
||||
input: FindingInput<ElectronBrowserWindowFinding>,
|
||||
window: ApplicationNode,
|
||||
): void => {
|
||||
const declared = input.value.preload_path;
|
||||
if (declared === null) return;
|
||||
if (input.value.preload_path === null) return;
|
||||
const {
|
||||
preload_path: declared,
|
||||
preload_resolution_context: resolutionContext,
|
||||
} = input.value;
|
||||
const resolution = resolveArtifactPathByContext({
|
||||
declaredPath: declared,
|
||||
sourcePath: input.file.path,
|
||||
context: input.value.preload_resolution_context ?? "module-specifier",
|
||||
context: resolutionContext,
|
||||
files: input.context.filesByPath,
|
||||
});
|
||||
const role = createElectronRoleNode(input.context, {
|
||||
@@ -210,7 +213,7 @@ const addUtilityProcess = (
|
||||
identity: artifactLocalIdentity(
|
||||
file.sha256,
|
||||
"electron-utility-process",
|
||||
`${value.module_path ?? value.module_expression ?? "[missing]"}:${electronRangeKey(value.location)}`,
|
||||
`${value.module_path ?? value.module_expression}:${electronRangeKey(value.location)}`,
|
||||
),
|
||||
observations: [
|
||||
{
|
||||
@@ -248,7 +251,7 @@ const addUtilityProcess = (
|
||||
const resolution = resolveArtifactPathByContext({
|
||||
declaredPath: value.module_path,
|
||||
sourcePath: file.path,
|
||||
context: value.module_resolution_context ?? "module-specifier",
|
||||
context: value.module_resolution_context,
|
||||
files: context.filesByPath,
|
||||
});
|
||||
const resolved = resolution.resolved_path;
|
||||
|
||||
@@ -0,0 +1,320 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { EvidenceLedger } from "./EvidenceLedger.js";
|
||||
import { createEvidence } from "../domain/evidence.js";
|
||||
import {
|
||||
createEvidenceBundle,
|
||||
parseEvidenceBundle,
|
||||
serializeEvidenceBundle,
|
||||
} from "../domain/evidenceBundle.js";
|
||||
import {
|
||||
createResidualUnknown,
|
||||
recordUnknownInputSchema,
|
||||
updateUnknownInputSchema,
|
||||
type RecordUnknownInput,
|
||||
type ResidualUnknown,
|
||||
} from "../domain/residualUnknown.js";
|
||||
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
const ledger = (): EvidenceLedger =>
|
||||
new EvidenceLedger({ maxRecords: 1_000, maxBytes: 4 * 1024 * 1024 });
|
||||
const evidence = (
|
||||
label: string,
|
||||
confidence: "observed" | "derived" | "inferred" = "derived",
|
||||
) =>
|
||||
createEvidence(undefined, provider, {
|
||||
operation: label,
|
||||
parameters: {},
|
||||
result: { label },
|
||||
confidence,
|
||||
authority:
|
||||
confidence === "observed" ? "controlled-replay" : "analyst-inference",
|
||||
environment:
|
||||
confidence === "observed"
|
||||
? {
|
||||
id: "fixture-linux",
|
||||
platform: "linux",
|
||||
architecture: "x86_64",
|
||||
isolation: "process",
|
||||
}
|
||||
: null,
|
||||
});
|
||||
const input = (
|
||||
question: string,
|
||||
overrides: Partial<RecordUnknownInput> = {},
|
||||
): RecordUnknownInput =>
|
||||
recordUnknownInputSchema.parse({
|
||||
approved: true,
|
||||
question,
|
||||
severity: "high",
|
||||
domain: "protocol",
|
||||
required_authority: "controlled-replay",
|
||||
required_confidence: "observed",
|
||||
required_environment: null,
|
||||
recommended_probes: [],
|
||||
relationships: [],
|
||||
...overrides,
|
||||
});
|
||||
const mutation = (label: string) => evidence(`mutation-${label}`);
|
||||
const update = (
|
||||
unknown: ResidualUnknown,
|
||||
overrides: Readonly<Record<string, unknown>> = {},
|
||||
) =>
|
||||
updateUnknownInputSchema.parse({
|
||||
approved: true,
|
||||
unknown_id: unknown.unknown_id,
|
||||
expected_revision: unknown.revision,
|
||||
status: "investigating",
|
||||
severity: unknown.severity,
|
||||
supporting_evidence_ids: unknown.supporting_evidence_ids,
|
||||
contradicting_evidence_ids: unknown.contradicting_evidence_ids,
|
||||
required_authority: unknown.required_authority,
|
||||
required_confidence: unknown.required_confidence,
|
||||
required_environment: unknown.required_environment,
|
||||
recommended_probes: unknown.recommended_probes,
|
||||
relationships: unknown.relationships,
|
||||
resolution: null,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
describe("residual unknown registry reads and identity", () => {
|
||||
it("returns detached unknowns and evidence bundles from every read surface", () => {
|
||||
const store = ledger();
|
||||
expect(store.record(evidence("detached-record")).ok).toBe(true);
|
||||
const created = store.recordUnknown(
|
||||
input("Does detached state remain intact?"),
|
||||
mutation("detached-unknown"),
|
||||
);
|
||||
expect(created.ok).toBe(true);
|
||||
if (!created.ok) return;
|
||||
|
||||
Reflect.set(created.value, "status", "resolved");
|
||||
const listed = store.listUnknowns();
|
||||
expect(listed[0]?.status).toBe("open");
|
||||
if (listed[0] !== undefined) Reflect.set(listed[0], "status", "resolved");
|
||||
const verified = store.verifyUnknownResolution(created.value.unknown_id);
|
||||
expect(verified).toMatchObject({ ok: true, value: { valid: false } });
|
||||
if (verified.ok) Reflect.set(verified.value.unknown, "status", "resolved");
|
||||
|
||||
const exported = store.export();
|
||||
const exportedRecord = exported.records.find(
|
||||
({ operation }) => operation === "detached-record",
|
||||
);
|
||||
if (exportedRecord !== undefined)
|
||||
Reflect.set(exportedRecord, "operation", "forged");
|
||||
expect(store.export().records.map(({ operation }) => operation)).toContain(
|
||||
"detached-record",
|
||||
);
|
||||
expect(
|
||||
store.verifyUnknownResolution(created.value.unknown_id),
|
||||
).toMatchObject({ ok: true, value: { valid: false } });
|
||||
});
|
||||
|
||||
it("requires approval, derives stable IDs, filters heads, and rejects duplicate creation", () => {
|
||||
expect(() =>
|
||||
recordUnknownInputSchema.parse({
|
||||
...input("Is branch live?"),
|
||||
approved: false,
|
||||
}),
|
||||
).toThrow();
|
||||
const store = ledger();
|
||||
const first = store.recordUnknown(
|
||||
input(" Is branch live? "),
|
||||
mutation("one"),
|
||||
);
|
||||
expect(first.ok).toBe(true);
|
||||
if (!first.ok) return;
|
||||
expect(first.value.unknown_id).toMatch(/^unk_[a-f0-9]{64}$/u);
|
||||
expect(first.value.revision).toBe(1);
|
||||
expect(store.listUnknowns({ severity: "high" })).toHaveLength(1);
|
||||
expect(store.listUnknowns({ status: "resolved" })).toEqual([]);
|
||||
const duplicate = store.recordUnknown(
|
||||
input("Is branch live?"),
|
||||
mutation("two"),
|
||||
);
|
||||
expect(duplicate.ok).toBe(false);
|
||||
if (!duplicate.ok)
|
||||
expect(duplicate.error._tag).toBe("UnknownRegistryError");
|
||||
const mutationId = `ev_${"a".repeat(64)}`;
|
||||
const normalized = createResidualUnknown(
|
||||
input("A scoped question"),
|
||||
mutationId,
|
||||
"0".repeat(64),
|
||||
);
|
||||
expect(
|
||||
createResidualUnknown(
|
||||
input("A scoped question"),
|
||||
mutationId,
|
||||
"0".repeat(64),
|
||||
).unknown_id,
|
||||
).toBe(normalized.unknown_id);
|
||||
expect(
|
||||
createResidualUnknown(
|
||||
input("A scoped question"),
|
||||
mutationId,
|
||||
"1".repeat(64),
|
||||
).unknown_id,
|
||||
).not.toBe(normalized.unknown_id);
|
||||
});
|
||||
|
||||
it("uses immutable CAS revisions and rejects a stale concurrent writer atomically", () => {
|
||||
const store = ledger();
|
||||
const created = store.recordUnknown(
|
||||
input("Which codec wins?"),
|
||||
mutation("create"),
|
||||
);
|
||||
if (!created.ok) throw created.error;
|
||||
const command = update(created.value);
|
||||
const winner = store.updateUnknown(command, mutation("winner"));
|
||||
expect(winner.ok).toBe(true);
|
||||
const loser = store.updateUnknown(command, mutation("loser"));
|
||||
expect(loser.ok).toBe(false);
|
||||
if (!loser.ok) expect(loser.error.message).toContain("revision-conflict");
|
||||
expect(store.export().unknowns.map(({ revision }) => revision)).toEqual([
|
||||
1, 2,
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("residual unknown registry resolution and history", () => {
|
||||
it("rejects inference for observed resolution, then accepts matching live evidence", () => {
|
||||
const store = ledger();
|
||||
const inferred = evidence("inference", "inferred");
|
||||
expect(store.record(inferred).ok).toBe(true);
|
||||
const created = store.recordUnknown(
|
||||
input("Does replay confirm response?", {
|
||||
supporting_evidence_ids: [inferred.evidence_id],
|
||||
required_environment: {
|
||||
id: "fixture-linux",
|
||||
platform: "linux",
|
||||
architecture: "x86_64",
|
||||
isolation: "process",
|
||||
},
|
||||
}),
|
||||
mutation("create-resolution"),
|
||||
);
|
||||
if (!created.ok) throw created.error;
|
||||
const invalid = store.updateUnknown(
|
||||
update(created.value, {
|
||||
status: "resolved",
|
||||
resolution: {
|
||||
disposition: "verified",
|
||||
rationale: "Inference alone is insufficient.",
|
||||
evidence_ids: [inferred.evidence_id],
|
||||
},
|
||||
}),
|
||||
mutation("invalid-resolution"),
|
||||
);
|
||||
expect(invalid.ok).toBe(false);
|
||||
expect(store.listUnknowns()[0]?.revision).toBe(1);
|
||||
|
||||
const observed = evidence("replay", "observed");
|
||||
expect(store.record(observed).ok).toBe(true);
|
||||
const valid = store.updateUnknown(
|
||||
update(created.value, {
|
||||
status: "resolved",
|
||||
supporting_evidence_ids: [inferred.evidence_id, observed.evidence_id],
|
||||
resolution: {
|
||||
disposition: "verified",
|
||||
rationale: "Controlled replay directly observed response.",
|
||||
evidence_ids: [observed.evidence_id],
|
||||
},
|
||||
}),
|
||||
mutation("valid-resolution"),
|
||||
);
|
||||
expect(valid.ok).toBe(true);
|
||||
if (valid.ok)
|
||||
expect(store.verifyUnknownResolution(valid.value.unknown_id)).toEqual({
|
||||
ok: true,
|
||||
value: { valid: true, truthVerified: true, unknown: valid.value },
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects broken references, dependency cycles, deletion, and tampering", () => {
|
||||
const store = ledger();
|
||||
const first = store.recordUnknown(input("First?"), mutation("first"));
|
||||
if (!first.ok) throw first.error;
|
||||
const second = store.recordUnknown(
|
||||
input("Second?", {
|
||||
relationships: [
|
||||
{ type: "depends-on", unknown_id: first.value.unknown_id },
|
||||
],
|
||||
}),
|
||||
mutation("second"),
|
||||
);
|
||||
if (!second.ok) throw second.error;
|
||||
const cycle = store.updateUnknown(
|
||||
update(first.value, {
|
||||
relationships: [
|
||||
{ type: "depends-on", unknown_id: second.value.unknown_id },
|
||||
],
|
||||
}),
|
||||
mutation("cycle"),
|
||||
);
|
||||
expect(cycle.ok).toBe(false);
|
||||
|
||||
const bundle = store.export();
|
||||
expect(parseEvidenceBundle(bundle)).toEqual(bundle);
|
||||
expect(serializeEvidenceBundle(bundle)).toBe(
|
||||
serializeEvidenceBundle(
|
||||
createEvidenceBundle(
|
||||
[...bundle.records].reverse(),
|
||||
[...bundle.unknowns].reverse(),
|
||||
),
|
||||
),
|
||||
);
|
||||
expect(() =>
|
||||
parseEvidenceBundle({ ...bundle, records: bundle.records.slice(1) }),
|
||||
).toThrow(/missing evidence/u);
|
||||
expect(() =>
|
||||
parseEvidenceBundle({
|
||||
...bundle,
|
||||
unknowns: bundle.unknowns.map((unknown, index) =>
|
||||
index === 0 ? { ...unknown, question: "tampered" } : unknown,
|
||||
),
|
||||
}),
|
||||
).toThrow();
|
||||
});
|
||||
|
||||
it("merges independent histories commutatively and rejects divergent heads atomically", () => {
|
||||
const left = ledger();
|
||||
const right = ledger();
|
||||
expect(left.recordUnknown(input("Left?"), mutation("left")).ok).toBe(true);
|
||||
expect(right.recordUnknown(input("Right?"), mutation("right")).ok).toBe(
|
||||
true,
|
||||
);
|
||||
const leftThenRight = ledger();
|
||||
const rightThenLeft = ledger();
|
||||
expect(leftThenRight.import(left.export()).ok).toBe(true);
|
||||
expect(leftThenRight.import(right.export()).ok).toBe(true);
|
||||
expect(rightThenLeft.import(right.export()).ok).toBe(true);
|
||||
expect(rightThenLeft.import(left.export()).ok).toBe(true);
|
||||
expect(serializeEvidenceBundle(leftThenRight.export())).toBe(
|
||||
serializeEvidenceBundle(rightThenLeft.export()),
|
||||
);
|
||||
|
||||
const base = ledger();
|
||||
const created = base.recordUnknown(input("Divergent?"), mutation("base"));
|
||||
if (!created.ok) throw created.error;
|
||||
const branch = ledger();
|
||||
expect(branch.import(base.export()).ok).toBe(true);
|
||||
expect(
|
||||
base.updateUnknown(update(created.value), mutation("branch-left")).ok,
|
||||
).toBe(true);
|
||||
expect(
|
||||
branch.updateUnknown(
|
||||
update(created.value, { severity: "critical" }),
|
||||
mutation("branch-right"),
|
||||
).ok,
|
||||
).toBe(true);
|
||||
const before = serializeEvidenceBundle(base.export());
|
||||
expect(base.import(branch.export()).ok).toBe(false);
|
||||
expect(serializeEvidenceBundle(base.export())).toBe(before);
|
||||
|
||||
const bounded = new EvidenceLedger({ maxRecords: 1, maxBytes: 1_000_000 });
|
||||
expect(
|
||||
bounded.recordUnknown(input("Too many?"), mutation("bounded")).ok,
|
||||
).toBe(false);
|
||||
expect(bounded.export()).toMatchObject({ records: [], unknowns: [] });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,194 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import { createEvidence, evidenceSchema } from "../domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { recordUnknownInputSchema } from "../domain/residualUnknown.js";
|
||||
import { EvidenceLedger } from "./EvidenceLedger.js";
|
||||
|
||||
const TARGET: BinaryTarget = {
|
||||
path: "/tmp/fixture",
|
||||
sha256: "a".repeat(64),
|
||||
kind: "executable",
|
||||
format: "mach-o",
|
||||
architecture: "arm64",
|
||||
availableArchitectures: ["arm64"],
|
||||
};
|
||||
const PROVIDER = { id: "fixture", name: "Fixture provider", version: "1" };
|
||||
|
||||
describe("evidence ledger recording", () => {
|
||||
it("deduplicates and atomically imports bounded bundles", () => {
|
||||
const evidence = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
});
|
||||
const ledger = new EvidenceLedger({ maxRecords: 1, maxBytes: 1_000_000 });
|
||||
expect(ledger.record(evidence)).toEqual({ ok: true, value: "added" });
|
||||
expect(ledger.record(evidence)).toEqual({ ok: true, value: "duplicate" });
|
||||
const relocated = createEvidence(
|
||||
{ ...TARGET, path: "/relocated/different-name" },
|
||||
PROVIDER,
|
||||
{ operation: "health", parameters: {}, result: true },
|
||||
);
|
||||
expect(relocated.evidence_id).toBe(evidence.evidence_id);
|
||||
expect(ledger.record(relocated)).toEqual({
|
||||
ok: true,
|
||||
value: "duplicate",
|
||||
});
|
||||
expect(ledger.import(createEvidenceBundle([evidence]))).toEqual({
|
||||
ok: true,
|
||||
value: { recordsAdded: 0, unknownsAdded: 0, changed: false },
|
||||
});
|
||||
expect(ledger.export().records).toEqual([evidence]);
|
||||
ledger.clear();
|
||||
expect(ledger.export().records).toEqual([]);
|
||||
});
|
||||
|
||||
it("treats canonical JSON key order as semantically irrelevant", () => {
|
||||
const evidence = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: { alpha: 1, beta: 2 },
|
||||
result: { alpha: 1, beta: 2 },
|
||||
});
|
||||
const reordered = evidenceSchema.parse({
|
||||
...evidence,
|
||||
parameters: { beta: 2, alpha: 1 },
|
||||
normalized_result: { beta: 2, alpha: 1 },
|
||||
});
|
||||
const ledger = new EvidenceLedger({ maxRecords: 1, maxBytes: 1_000_000 });
|
||||
expect(ledger.record(evidence)).toEqual({ ok: true, value: "added" });
|
||||
expect(ledger.record(reordered)).toEqual({
|
||||
ok: true,
|
||||
value: "duplicate",
|
||||
});
|
||||
});
|
||||
|
||||
it("returns typed record and byte limit failures without eviction", () => {
|
||||
const first = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
});
|
||||
const second = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: { changed: true },
|
||||
result: true,
|
||||
});
|
||||
const recordBound = new EvidenceLedger({
|
||||
maxRecords: 1,
|
||||
maxBytes: 1_000_000,
|
||||
});
|
||||
expect(recordBound.record(first).ok).toBe(true);
|
||||
expect(recordBound.record(second)).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "EvidenceLimitError", limit: "records", maximum: 1 },
|
||||
});
|
||||
expect(recordBound.export().records).toEqual([first]);
|
||||
|
||||
const byteBound = new EvidenceLedger({ maxRecords: 10, maxBytes: 1 });
|
||||
expect(byteBound.record(first)).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "EvidenceLimitError", limit: "bytes", maximum: 1 },
|
||||
});
|
||||
expect(byteBound.export().records).toEqual([]);
|
||||
});
|
||||
|
||||
it("counts unknown revisions when enforcing direct record limits", () => {
|
||||
const ledger = new EvidenceLedger({
|
||||
maxRecords: 2,
|
||||
maxBytes: 1_000_000,
|
||||
});
|
||||
const mutation = createEvidence(undefined, PROVIDER, {
|
||||
predicateType: "rea.residual-unknown-mutation/v1",
|
||||
operation: "record_unknown",
|
||||
parameters: {},
|
||||
result: { action: "record" },
|
||||
});
|
||||
const unknown = recordUnknownInputSchema.parse({
|
||||
approved: true,
|
||||
question: "What remains unresolved?",
|
||||
severity: "high",
|
||||
domain: "record-limit-test",
|
||||
supporting_evidence_ids: [],
|
||||
contradicting_evidence_ids: [],
|
||||
required_authority: "shipped-artifact",
|
||||
required_confidence: "observed",
|
||||
required_environment: null,
|
||||
recommended_probes: [],
|
||||
relationships: [],
|
||||
});
|
||||
expect(ledger.recordUnknown(unknown, mutation).ok).toBe(true);
|
||||
|
||||
const direct = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
});
|
||||
expect(ledger.record(direct)).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "EvidenceLimitError", limit: "records", maximum: 2 },
|
||||
});
|
||||
expect(ledger.export()).toMatchObject({
|
||||
records: [mutation],
|
||||
unknowns: [expect.objectContaining({ domain: "record-limit-test" })],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("evidence bundle imports", () => {
|
||||
it("rejects conflicting duplicate IDs without mutating the ledger", () => {
|
||||
const ledger = new EvidenceLedger({ maxRecords: 2, maxBytes: 1_000_000 });
|
||||
const first = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
rawResult: { pid: 1 },
|
||||
});
|
||||
expect(ledger.record(first).ok).toBe(true);
|
||||
const bundle = createEvidenceBundle([first]);
|
||||
expect(
|
||||
ledger.import({
|
||||
...bundle,
|
||||
records: [{ ...first, normalized_result: false }],
|
||||
}),
|
||||
).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "EvidenceIntegrityError" },
|
||||
});
|
||||
expect(ledger.export().records).toEqual([first]);
|
||||
});
|
||||
|
||||
it("atomically rejects Evidence plus unknown when the batch exceeds limits", () => {
|
||||
const ledger = new EvidenceLedger({ maxRecords: 2, maxBytes: 1_000_000 });
|
||||
const output = createEvidence(undefined, PROVIDER, {
|
||||
operation: "derived",
|
||||
parameters: {},
|
||||
result: { status: "unknown" },
|
||||
});
|
||||
const mutation = createEvidence(undefined, PROVIDER, {
|
||||
predicateType: "rea.residual-unknown-mutation/v1",
|
||||
operation: "record_unknown",
|
||||
parameters: {},
|
||||
result: { action: "record" },
|
||||
});
|
||||
const unknown = recordUnknownInputSchema.parse({
|
||||
approved: true,
|
||||
question: "What remains unresolved?",
|
||||
severity: "high",
|
||||
domain: "atomic-test",
|
||||
supporting_evidence_ids: [],
|
||||
contradicting_evidence_ids: [],
|
||||
required_authority: "shipped-artifact",
|
||||
required_confidence: "observed",
|
||||
required_environment: null,
|
||||
recommended_probes: [],
|
||||
relationships: [],
|
||||
});
|
||||
expect(ledger.recordWithUnknown(output, unknown, mutation)).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "EvidenceLimitError" },
|
||||
});
|
||||
expect(ledger.export()).toMatchObject({ records: [], unknowns: [] });
|
||||
});
|
||||
});
|
||||
@@ -277,7 +277,7 @@ const invalidPackage = (
|
||||
const unavailablePackage = (
|
||||
file: JavaScriptArtifactFile,
|
||||
limitation: string,
|
||||
): JavaScriptPackageObservation => ({
|
||||
): JavaScriptPackageObservation & { readonly status: "unavailable" } => ({
|
||||
path: file.path,
|
||||
sha256: file.sha256,
|
||||
status: "unavailable",
|
||||
@@ -394,17 +394,24 @@ const collectSourceMapOriginals = (
|
||||
}
|
||||
}
|
||||
const omitted = total - sources.length;
|
||||
return {
|
||||
path: file.path,
|
||||
sha256: file.sha256,
|
||||
status: omitted === 0 ? "included" : "truncated",
|
||||
sources,
|
||||
omitted_sources: omitted,
|
||||
limitation:
|
||||
omitted === 0
|
||||
? null
|
||||
: "Original-source inventory reached the approved source-map limit.",
|
||||
};
|
||||
return omitted === 0
|
||||
? {
|
||||
path: file.path,
|
||||
sha256: file.sha256,
|
||||
status: "included",
|
||||
sources,
|
||||
omitted_sources: 0,
|
||||
limitation: null,
|
||||
}
|
||||
: {
|
||||
path: file.path,
|
||||
sha256: file.sha256,
|
||||
status: "truncated",
|
||||
sources,
|
||||
omitted_sources: omitted,
|
||||
limitation:
|
||||
"Original-source inventory reached the approved source-map limit.",
|
||||
};
|
||||
};
|
||||
|
||||
const unavailableSourceMap = (
|
||||
|
||||
@@ -8,18 +8,35 @@ import type {
|
||||
} from "../domain/javascriptSemanticIr.js";
|
||||
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
|
||||
|
||||
/** Parsed package metadata used only for static entrypoint discovery. */
|
||||
export interface JavaScriptPackageObservation {
|
||||
interface JavaScriptStructuredObservation {
|
||||
readonly path: string;
|
||||
readonly sha256: string;
|
||||
readonly status: "included" | "invalid" | "unavailable";
|
||||
}
|
||||
|
||||
interface JavaScriptPackageValues {
|
||||
readonly name: string | null;
|
||||
readonly version: string | null;
|
||||
readonly main: string | null;
|
||||
readonly renderer: string | null;
|
||||
readonly limitation: string | null;
|
||||
}
|
||||
|
||||
/** Parsed package metadata used only for static entrypoint discovery. */
|
||||
export type JavaScriptPackageObservation = JavaScriptStructuredObservation &
|
||||
(
|
||||
| (JavaScriptPackageValues & {
|
||||
readonly status: "included";
|
||||
readonly limitation: null;
|
||||
})
|
||||
| {
|
||||
readonly status: "invalid" | "unavailable";
|
||||
readonly name: null;
|
||||
readonly version: null;
|
||||
readonly main: null;
|
||||
readonly renderer: null;
|
||||
readonly limitation: string;
|
||||
}
|
||||
);
|
||||
|
||||
/** One HTML script source observed without building or executing a DOM. */
|
||||
export interface JavaScriptHtmlScriptObservation {
|
||||
readonly html_path: string;
|
||||
@@ -36,24 +53,50 @@ export interface JavaScriptSourceMapOriginal {
|
||||
}
|
||||
|
||||
/** Bounded local source-map parse result. */
|
||||
export interface JavaScriptSourceMapObservation {
|
||||
readonly path: string;
|
||||
readonly sha256: string;
|
||||
readonly status: "included" | "truncated" | "invalid" | "not-approved";
|
||||
readonly sources: readonly JavaScriptSourceMapOriginal[];
|
||||
readonly omitted_sources: number | null;
|
||||
readonly limitation: string | null;
|
||||
}
|
||||
export type JavaScriptSourceMapObservation = JavaScriptStructuredObservation &
|
||||
(
|
||||
| {
|
||||
readonly status: "included";
|
||||
readonly sources: readonly JavaScriptSourceMapOriginal[];
|
||||
readonly omitted_sources: 0;
|
||||
readonly limitation: null;
|
||||
}
|
||||
| {
|
||||
readonly status: "truncated";
|
||||
readonly sources: readonly JavaScriptSourceMapOriginal[];
|
||||
readonly omitted_sources: number | null;
|
||||
readonly limitation: string;
|
||||
}
|
||||
| {
|
||||
readonly status: "invalid" | "not-approved";
|
||||
readonly sources: readonly [];
|
||||
readonly omitted_sources: 0;
|
||||
readonly limitation: string;
|
||||
}
|
||||
);
|
||||
|
||||
/** Bounded parse status for one inventoried JSON module. */
|
||||
export interface JavaScriptJsonModuleObservation {
|
||||
readonly path: string;
|
||||
readonly sha256: string;
|
||||
readonly status: "included" | "invalid" | "unavailable";
|
||||
readonly top_level_keys: readonly string[];
|
||||
readonly omitted_top_level_keys: number | null;
|
||||
readonly limitation: string | null;
|
||||
}
|
||||
export type JavaScriptJsonModuleObservation = JavaScriptStructuredObservation &
|
||||
(
|
||||
| {
|
||||
readonly status: "included";
|
||||
readonly top_level_keys: readonly string[];
|
||||
readonly omitted_top_level_keys: number;
|
||||
readonly limitation: null;
|
||||
}
|
||||
| {
|
||||
readonly status: "invalid";
|
||||
readonly top_level_keys: readonly [];
|
||||
readonly omitted_top_level_keys: 0;
|
||||
readonly limitation: string;
|
||||
}
|
||||
| {
|
||||
readonly status: "unavailable";
|
||||
readonly top_level_keys: readonly [];
|
||||
readonly omitted_top_level_keys: null;
|
||||
readonly limitation: string;
|
||||
}
|
||||
);
|
||||
|
||||
/** One relevant file plus optional AST-only JavaScript facts. */
|
||||
export interface AnalyzedJavaScriptArtifactFile {
|
||||
|
||||
@@ -20,9 +20,10 @@ import {
|
||||
addJavaScriptSourceModules,
|
||||
} from "./JavaScriptModuleRelationships.js";
|
||||
import {
|
||||
completeReconstructionCoverage,
|
||||
partialReconstructionCoverage,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
completeApplicationCoverage,
|
||||
partialApplicationCoverage,
|
||||
truncatedApplicationCoverage,
|
||||
} from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import {
|
||||
addJavaScriptArtifactContainers,
|
||||
addJavaScriptArtifactFiles,
|
||||
@@ -108,24 +109,21 @@ const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
|
||||
malformedStructuredData ||
|
||||
partialJavaScript;
|
||||
if (context.analysis.truncated_scopes > 0)
|
||||
return partialReconstructionCoverage(
|
||||
return truncatedApplicationCoverage(
|
||||
reconstructionLimits(context.input),
|
||||
truncationOmittedCount(context),
|
||||
true,
|
||||
);
|
||||
if (exactLimitOmissions > 0)
|
||||
return partialReconstructionCoverage(
|
||||
return truncatedApplicationCoverage(
|
||||
reconstructionLimits(context.input),
|
||||
exactLimitOmissions,
|
||||
true,
|
||||
);
|
||||
if (unknownGap)
|
||||
return partialReconstructionCoverage(
|
||||
return partialApplicationCoverage(
|
||||
reconstructionLimits(context.input),
|
||||
null,
|
||||
false,
|
||||
);
|
||||
return completeReconstructionCoverage(reconstructionLimits(context.input));
|
||||
return completeApplicationCoverage(reconstructionLimits(context.input));
|
||||
};
|
||||
|
||||
const truncationOmittedCount = (
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
|
||||
import type { ApplicationGraphEvidence } from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import {
|
||||
completeApplicationCoverage,
|
||||
partialApplicationCoverage,
|
||||
truncatedApplicationCoverage,
|
||||
type ApplicationGraphEvidence,
|
||||
} from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
|
||||
import type { JavaScriptSourceRange } from "../domain/javascriptStaticAnalysisTypes.js";
|
||||
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
@@ -12,8 +17,6 @@ import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAcc
|
||||
import {
|
||||
artifactObservationEvidence,
|
||||
astObservationEvidence,
|
||||
completeReconstructionCoverage,
|
||||
partialReconstructionCoverage,
|
||||
staticInferenceEvidence,
|
||||
unavailableAstEvidence,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
@@ -117,7 +120,7 @@ export const addArtifactContainsEdge = (
|
||||
: input.file.sha256,
|
||||
path: input.file.path,
|
||||
operation: input.operation,
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
});
|
||||
};
|
||||
@@ -186,7 +189,7 @@ export const addUnavailableStaticParseScope = (
|
||||
sha256: input.file.sha256,
|
||||
path: input.file.path,
|
||||
operation: input.operation,
|
||||
coverage: partialReconstructionCoverage([], null, false),
|
||||
coverage: partialApplicationCoverage([], null),
|
||||
limitation: input.limitation,
|
||||
}),
|
||||
},
|
||||
@@ -201,7 +204,7 @@ export const addUnavailableStaticParseScope = (
|
||||
sha256: input.file.sha256,
|
||||
path: input.file.path,
|
||||
operation: "associate-unavailable-parse-scope",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
});
|
||||
};
|
||||
@@ -214,13 +217,10 @@ export const javascriptAnalysisCoverage = (
|
||||
input: JavaScriptArtifactReconstructionInput,
|
||||
): JavaScriptArtifactGraphCoverage =>
|
||||
analysis.parse_status === "complete"
|
||||
? completeReconstructionCoverage(javaScriptAnalysisLimits(input))
|
||||
: {
|
||||
status: "partial",
|
||||
truncated: analysis.parse_status === "truncated",
|
||||
omitted_count: null,
|
||||
limits: javaScriptAnalysisLimits(input),
|
||||
};
|
||||
? completeApplicationCoverage(javaScriptAnalysisLimits(input))
|
||||
: analysis.parse_status === "truncated"
|
||||
? truncatedApplicationCoverage(javaScriptAnalysisLimits(input), null)
|
||||
: partialApplicationCoverage(javaScriptAnalysisLimits(input), null);
|
||||
|
||||
/** Stable identity for a fact scoped to one exact artifact. */
|
||||
export const artifactLocalIdentity = (
|
||||
@@ -274,7 +274,7 @@ export const createElectronRoleNode = (
|
||||
sha256: input.anchor.sha256,
|
||||
path: input.anchor.path,
|
||||
operation: "discover-electron-entrypoint",
|
||||
coverage: input.coverage ?? completeReconstructionCoverage(),
|
||||
coverage: input.coverage ?? completeApplicationCoverage(),
|
||||
limitations: input.resolution.limitations,
|
||||
...(input.range === undefined ? {} : { range: input.range }),
|
||||
}),
|
||||
@@ -305,7 +305,7 @@ export const linkElectronRoleToAsset = (
|
||||
sha256: input.anchor.sha256,
|
||||
path: input.anchor.path,
|
||||
operation: "resolve-electron-entrypoint",
|
||||
coverage: input.coverage ?? completeReconstructionCoverage(),
|
||||
coverage: input.coverage ?? completeApplicationCoverage(),
|
||||
limitations: input.resolution.limitations,
|
||||
...(input.range === undefined ? {} : { range: input.range }),
|
||||
}),
|
||||
|
||||
@@ -5,11 +5,11 @@ import {
|
||||
linkElectronRoleToAsset,
|
||||
type JavaScriptArtifactGraphContext,
|
||||
} from "./JavaScriptArtifactGraphContext.js";
|
||||
import { artifactObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
|
||||
import {
|
||||
artifactObservationEvidence,
|
||||
completeReconstructionCoverage,
|
||||
partialReconstructionCoverage,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
completeApplicationCoverage,
|
||||
truncatedApplicationCoverage,
|
||||
} from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
|
||||
|
||||
/** Project HTML renderer entrypoints and their local script assets. */
|
||||
@@ -68,7 +68,7 @@ export const addJavaScriptHtmlRoles = (
|
||||
target: resolved,
|
||||
file: html,
|
||||
range: script.location,
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
relation: "loads",
|
||||
properties: {
|
||||
script_path: script.script_path,
|
||||
@@ -93,7 +93,7 @@ export const addJavaScriptSourceMapOriginals = (
|
||||
if (mapFile === undefined || mapNode === undefined) continue;
|
||||
const coverage =
|
||||
sourceMap.status === "truncated"
|
||||
? partialReconstructionCoverage(
|
||||
? truncatedApplicationCoverage(
|
||||
[
|
||||
{
|
||||
name: "max-source-map-sources",
|
||||
@@ -102,9 +102,8 @@ export const addJavaScriptSourceMapOriginals = (
|
||||
},
|
||||
],
|
||||
sourceMap.omitted_sources,
|
||||
true,
|
||||
)
|
||||
: completeReconstructionCoverage();
|
||||
: completeApplicationCoverage();
|
||||
for (const original of sourceMap.sources) {
|
||||
const node = context.accumulator.addNode({
|
||||
kind: "source-module",
|
||||
|
||||
@@ -111,28 +111,6 @@ export const unavailableAstEvidence = (
|
||||
evidence_ids: [],
|
||||
});
|
||||
|
||||
/** Complete local projection coverage under named hard limits. */
|
||||
export const completeReconstructionCoverage = (
|
||||
limits: ReconstructionEvidenceCoverage["limits"] = [],
|
||||
): ReconstructionEvidenceCoverage => ({
|
||||
status: "complete",
|
||||
truncated: false,
|
||||
omitted_count: 0,
|
||||
limits: [...limits],
|
||||
});
|
||||
|
||||
/** Partial reconstruction coverage with either exact truncation or a policy gap. */
|
||||
export const partialReconstructionCoverage = (
|
||||
limits: ReconstructionEvidenceCoverage["limits"],
|
||||
omitted: number | null,
|
||||
truncated: boolean,
|
||||
): ReconstructionEvidenceCoverage => ({
|
||||
status: "partial",
|
||||
truncated,
|
||||
omitted_count: omitted,
|
||||
limits: [...limits],
|
||||
});
|
||||
|
||||
const artifactReference = (sha256: string) => ({
|
||||
available: true as const,
|
||||
artifact_id: `art_${sha256}`,
|
||||
|
||||
@@ -78,7 +78,7 @@ const addReference = (
|
||||
identity: artifactLocalIdentity(
|
||||
input.file.sha256,
|
||||
input.value.kind,
|
||||
input.value.specifier ?? input.value.expression ?? "[dynamic]",
|
||||
input.value.specifier ?? input.value.expression,
|
||||
),
|
||||
observations: [
|
||||
{
|
||||
@@ -406,7 +406,7 @@ const unresolvedReferenceNode = (
|
||||
identity: artifactLocalIdentity(
|
||||
file.sha256,
|
||||
"unresolved-reference",
|
||||
`${reference.kind}:${reference.specifier ?? reference.expression ?? "[dynamic]"}`,
|
||||
`${reference.kind}:${reference.specifier ?? reference.expression}`,
|
||||
),
|
||||
observations: [
|
||||
{
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
|
||||
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
|
||||
import { completeApplicationCoverage } from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
import type {
|
||||
JavaScriptArtifactContainer,
|
||||
@@ -17,7 +18,6 @@ import {
|
||||
} from "./JavaScriptArtifactGraphContext.js";
|
||||
import {
|
||||
artifactObservationEvidence,
|
||||
completeReconstructionCoverage,
|
||||
staticInferenceEvidence,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
|
||||
@@ -61,7 +61,7 @@ export const createJavaScriptArtifactRootNode = (
|
||||
sha256: root.sha256,
|
||||
path: "artifact-root",
|
||||
operation: "inventory-root",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
limitations: [
|
||||
"artifact-root is a path-independent alias; the application result retains the canonical local input path.",
|
||||
],
|
||||
@@ -91,7 +91,7 @@ export const addJavaScriptArtifactContainers = (
|
||||
sha256: container.sha256,
|
||||
path: container.path,
|
||||
operation: "inventory-nested-asar",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
},
|
||||
],
|
||||
@@ -106,7 +106,7 @@ export const addJavaScriptArtifactContainers = (
|
||||
sha256: context.snapshot.manifest.root_sha256,
|
||||
path: container.path,
|
||||
operation: "inventory-nested-asar",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
});
|
||||
}
|
||||
@@ -147,7 +147,7 @@ export const addJavaScriptArtifactFiles = (
|
||||
sha256: file.container_sha256,
|
||||
path: file.path,
|
||||
operation: "map-entry-content",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
});
|
||||
}
|
||||
@@ -167,16 +167,12 @@ export const addJavaScriptArtifactFiles = (
|
||||
const packageValue = context.analysis.packages.find(
|
||||
({ path }) => path === file.path,
|
||||
);
|
||||
if (
|
||||
packageValue?.status !== undefined &&
|
||||
packageValue.status !== "included"
|
||||
)
|
||||
if (packageValue !== undefined && packageValue.status !== "included")
|
||||
addUnavailableStaticParseScope(context, {
|
||||
file,
|
||||
asset: target,
|
||||
operation: "parse-package-json",
|
||||
limitation:
|
||||
packageValue.limitation ?? "Package metadata could not be parsed.",
|
||||
limitation: packageValue.limitation,
|
||||
});
|
||||
const jsonValue = context.analysis.json_modules.find(
|
||||
({ path }) => path === file.path,
|
||||
@@ -186,8 +182,7 @@ export const addJavaScriptArtifactFiles = (
|
||||
file,
|
||||
asset: target,
|
||||
operation: "parse-json-module",
|
||||
limitation:
|
||||
jsonValue.limitation ?? "JSON module content could not be parsed.",
|
||||
limitation: jsonValue.limitation,
|
||||
});
|
||||
const sourceMap = context.analysis.source_maps.find(
|
||||
({ path }) => path === file.path,
|
||||
@@ -200,8 +195,7 @@ export const addJavaScriptArtifactFiles = (
|
||||
file,
|
||||
asset: target,
|
||||
operation: "parse-local-source-map",
|
||||
limitation:
|
||||
sourceMap.limitation ?? "Source-map content could not be parsed.",
|
||||
limitation: sourceMap.limitation,
|
||||
});
|
||||
}
|
||||
};
|
||||
@@ -232,7 +226,7 @@ export const addJavaScriptPackageNodes = (
|
||||
sha256: file.sha256,
|
||||
path: file.path,
|
||||
operation: "parse-package-json",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
limitations:
|
||||
packageValue.limitation === null ? [] : [packageValue.limitation],
|
||||
}),
|
||||
@@ -250,7 +244,7 @@ export const addJavaScriptPackageNodes = (
|
||||
sha256: file.sha256,
|
||||
path: file.path,
|
||||
operation: "associate-package-artifact",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
});
|
||||
} else
|
||||
@@ -312,7 +306,7 @@ const createFileTarget = (
|
||||
sha256: file.sha256,
|
||||
path: file.path,
|
||||
operation: "inventory-relevant-file",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
},
|
||||
],
|
||||
@@ -348,7 +342,7 @@ const createAsarEntry = (
|
||||
sha256: file.container_sha256,
|
||||
path: file.path,
|
||||
operation: "inventory-asar-entry",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
}),
|
||||
},
|
||||
],
|
||||
@@ -390,7 +384,7 @@ const addPackageRole = (
|
||||
sha256: input.packageFile.sha256,
|
||||
path: input.packageFile.path,
|
||||
operation: "discover-package-entrypoint",
|
||||
coverage: completeReconstructionCoverage(),
|
||||
coverage: completeApplicationCoverage(),
|
||||
limitations: resolution.limitations,
|
||||
}),
|
||||
});
|
||||
|
||||
@@ -0,0 +1,322 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
resolveArtifactPathByContext,
|
||||
type ResolveArtifactPathInput,
|
||||
} from "./JavaScriptArtifactPathResolution.js";
|
||||
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
|
||||
import { analyzeJavaScriptStaticSource } from "../domain/javascriptStaticAnalysis.js";
|
||||
|
||||
describe("contextual JavaScript artifact path resolution", () => {
|
||||
it.each([
|
||||
["main.js", "app/main.js"],
|
||||
["./main.js", "app/main.js"],
|
||||
["src/main", "app/src/main.cjs"],
|
||||
["entry", "app/entry/start.mjs"],
|
||||
["fallback", "app/fallback/index.ts"],
|
||||
])("resolves package entrypoint %s", (declaredPath, expected) => {
|
||||
const files = fileMap([
|
||||
file("app/package.json", "root"),
|
||||
file("app/main.js", "root"),
|
||||
file("app/src/main.cjs", "root"),
|
||||
file("app/entry/package.json", "root", '{"main":"start"}'),
|
||||
file("app/entry/start.mjs", "root"),
|
||||
file("app/fallback/index.ts", "root"),
|
||||
]);
|
||||
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath,
|
||||
sourcePath: "app/package.json",
|
||||
context: "package-entrypoint",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_context: "package-entrypoint",
|
||||
resolution_status: "resolved",
|
||||
resolved_path: expected,
|
||||
limitations: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("resolves dirname-derived bare paths but keeps bare module specifiers external", () => {
|
||||
const files = fileMap([
|
||||
file("app/main.js", "root"),
|
||||
file("app/preload.js", "root"),
|
||||
]);
|
||||
const base = {
|
||||
declaredPath: "preload.js",
|
||||
sourcePath: "app/main.js",
|
||||
files,
|
||||
} as const;
|
||||
|
||||
expect(
|
||||
resolve({ ...base, context: "filesystem-expression" }),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "app/preload.js",
|
||||
});
|
||||
expect(resolve({ ...base, context: "module-specifier" })).toMatchObject({
|
||||
resolution_status: "external",
|
||||
resolved_path: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("applies document and base-href semantics to HTML references", () => {
|
||||
const files = fileMap([
|
||||
file("renderer/index.html", "root"),
|
||||
file("assets/app.js", "root"),
|
||||
file("renderer/local.js", "root"),
|
||||
]);
|
||||
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "app.js?v=1",
|
||||
sourcePath: "renderer/index.html",
|
||||
context: "html-reference",
|
||||
htmlBaseHref: "/assets/",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "assets/app.js",
|
||||
});
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "./local.js",
|
||||
sourcePath: "renderer/index.html",
|
||||
context: "html-reference",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "renderer/local.js",
|
||||
});
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "file:///assets/app.js#entry",
|
||||
sourcePath: "main.js",
|
||||
context: "module-specifier",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "assets/app.js",
|
||||
});
|
||||
});
|
||||
|
||||
it.each(["node:fs", "electron", "../../escape.js", "%2e%2e/escape.js"])(
|
||||
"fails closed for unsafe or external module declaration %s",
|
||||
(declaredPath) => {
|
||||
const result = resolve({
|
||||
declaredPath,
|
||||
sourcePath: "app/main.js",
|
||||
context: "module-specifier",
|
||||
files: fileMap([file("app/main.js", "root")]),
|
||||
});
|
||||
expect(result.resolved_path).toBeNull();
|
||||
expect(["external", "rejected"]).toContain(result.resolution_status);
|
||||
expect(result.limitations.length).toBeGreaterThan(0);
|
||||
},
|
||||
);
|
||||
|
||||
it("does not cross nested ASAR container identities", () => {
|
||||
const files = fileMap([
|
||||
file("app.asar/main.js", "asar-a"),
|
||||
file("app.asar/preload.js", "asar-b"),
|
||||
]);
|
||||
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "preload.js",
|
||||
sourcePath: "app.asar/main.js",
|
||||
context: "filesystem-expression",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({ resolution_status: "not-found", resolved_path: null });
|
||||
});
|
||||
});
|
||||
|
||||
describe("contextual JavaScript package path resolution", () => {
|
||||
it("keeps an inventoried but unreadable directory package unavailable", () => {
|
||||
const files = fileMap([
|
||||
file("app/package.json", "root"),
|
||||
file("app/entry/package.json", "root", null),
|
||||
]);
|
||||
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "entry",
|
||||
sourcePath: "app/package.json",
|
||||
context: "package-entrypoint",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "unavailable",
|
||||
resolved_path: null,
|
||||
limitations: [expect.stringContaining("text is unavailable")],
|
||||
});
|
||||
});
|
||||
|
||||
it("resolves nearest inventoried bare packages with import/require conditions", () => {
|
||||
const files = fileMap([
|
||||
file("app/src/consumer.js", "root"),
|
||||
file(
|
||||
"app/node_modules/fixture/package.json",
|
||||
"root",
|
||||
JSON.stringify({
|
||||
exports: {
|
||||
".": {
|
||||
import: "./esm.mjs",
|
||||
require: "./cjs.cjs",
|
||||
default: "./fallback.js",
|
||||
},
|
||||
},
|
||||
}),
|
||||
),
|
||||
file("app/node_modules/fixture/esm.mjs", "root"),
|
||||
file("app/node_modules/fixture/cjs.cjs", "root"),
|
||||
file("app/node_modules/fixture/fallback.js", "root"),
|
||||
file("app/node_modules/fixture/hidden.js", "root"),
|
||||
file("app/node_modules/fs/index.js", "root"),
|
||||
]);
|
||||
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "fixture",
|
||||
sourcePath: "app/src/consumer.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "import",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "app/node_modules/fixture/esm.mjs",
|
||||
});
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "fixture",
|
||||
sourcePath: "app/src/consumer.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "require",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "app/node_modules/fixture/cjs.cjs",
|
||||
});
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "fs",
|
||||
sourcePath: "app/src/consumer.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "require",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({ resolution_status: "external", resolved_path: null });
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "fixture/hidden.js",
|
||||
sourcePath: "app/src/consumer.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "import",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolution_status: "external",
|
||||
resolved_path: null,
|
||||
limitations: [expect.stringContaining("subpaths remain unresolved")],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("contextual JavaScript module identity", () => {
|
||||
it("retains CommonJS and ESM file-base identity during inert extraction", () => {
|
||||
const analysis = analyzeJavaScriptStaticSource(
|
||||
`
|
||||
new BrowserWindow({ webPreferences: {
|
||||
preload: path.resolve(__dirname, "preload.cjs")
|
||||
}});
|
||||
new BrowserWindow({ webPreferences: {
|
||||
preload: fileURLToPath(new URL("./preload.mjs", import.meta.url))
|
||||
}});
|
||||
new BrowserWindow({ webPreferences: {
|
||||
preload: path.join(path.dirname(__filename), "legacy-preload.js")
|
||||
}});
|
||||
new BrowserWindow({ webPreferences: {
|
||||
preload: new URL("./remote-base.js", location.href)
|
||||
}});
|
||||
window.loadURL("file:///renderer/index.html");
|
||||
`,
|
||||
{
|
||||
maxAstNodes: 10_000,
|
||||
maxFindings: 100,
|
||||
maxModules: 100,
|
||||
deadline: Number.POSITIVE_INFINITY,
|
||||
now: () => 0,
|
||||
},
|
||||
);
|
||||
|
||||
expect(analysis.role_paths).toEqual(
|
||||
expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
path: "preload.cjs",
|
||||
resolution_context: "filesystem-expression",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
path: "./preload.mjs",
|
||||
resolution_context: "filesystem-expression",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
path: "legacy-preload.js",
|
||||
resolution_context: "filesystem-expression",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
path: "file:///renderer/index.html",
|
||||
resolution_context: "module-specifier",
|
||||
}),
|
||||
]),
|
||||
);
|
||||
expect(analysis.electron.browser_windows).toEqual(
|
||||
expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
preload_path: "preload.cjs",
|
||||
preload_resolution_context: "filesystem-expression",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
preload_path: "./preload.mjs",
|
||||
preload_resolution_context: "filesystem-expression",
|
||||
}),
|
||||
]),
|
||||
);
|
||||
expect(analysis.role_paths).not.toEqual(
|
||||
expect.arrayContaining([
|
||||
expect.objectContaining({ path: "./remote-base.js" }),
|
||||
]),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
const resolve = (input: ResolveArtifactPathInput) =>
|
||||
resolveArtifactPathByContext(input);
|
||||
|
||||
const fileMap = (files: readonly JavaScriptArtifactFile[]) =>
|
||||
new Map(files.map((value) => [value.path, value]));
|
||||
|
||||
const file = (
|
||||
path: string,
|
||||
container: string,
|
||||
text: string | null = "",
|
||||
): JavaScriptArtifactFile => ({
|
||||
path,
|
||||
container_sha256: container.padEnd(64, "0").slice(0, 64),
|
||||
sha256: path.padEnd(64, "0").slice(0, 64),
|
||||
bytes: text?.length ?? 0,
|
||||
inventory_artifact_id: `artifact-${path}`,
|
||||
kind: path.endsWith("package.json") ? "package-json" : "javascript",
|
||||
unpacked: false,
|
||||
text:
|
||||
text === null
|
||||
? { included: false, reason: "file-limit" }
|
||||
: { included: true, value: text },
|
||||
});
|
||||
@@ -3,33 +3,42 @@ import { posix } from "node:path";
|
||||
|
||||
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
|
||||
|
||||
/** Explicit outcome of bounded, artifact-confined path resolution. */
|
||||
export interface ArtifactPathResolution {
|
||||
type ArtifactPathResolutionContext =
|
||||
| "package-entrypoint"
|
||||
| "filesystem-expression"
|
||||
| "module-specifier"
|
||||
| "html-reference";
|
||||
|
||||
type UnresolvedArtifactPathStatus =
|
||||
| "not-found"
|
||||
| "unavailable"
|
||||
| "external"
|
||||
| "rejected";
|
||||
|
||||
interface ArtifactPathResolutionBase {
|
||||
readonly declared_path: string;
|
||||
readonly resolution_context:
|
||||
| "package-entrypoint"
|
||||
| "filesystem-expression"
|
||||
| "module-specifier"
|
||||
| "html-reference";
|
||||
readonly resolved_path: string | null;
|
||||
readonly resolution_status:
|
||||
| "resolved"
|
||||
| "not-found"
|
||||
| "unavailable"
|
||||
| "external"
|
||||
| "rejected";
|
||||
readonly resolution_context: ArtifactPathResolutionContext;
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
|
||||
/** Explicit outcome of bounded, artifact-confined path resolution. */
|
||||
export type ArtifactPathResolution = ArtifactPathResolutionBase &
|
||||
(
|
||||
| {
|
||||
readonly resolved_path: string;
|
||||
readonly resolution_status: "resolved";
|
||||
}
|
||||
| {
|
||||
readonly resolved_path: null;
|
||||
readonly resolution_status: UnresolvedArtifactPathStatus;
|
||||
}
|
||||
);
|
||||
|
||||
/** Values needed to resolve a declaration without filesystem access. */
|
||||
export interface ResolveArtifactPathInput {
|
||||
readonly declaredPath: string;
|
||||
readonly sourcePath: string;
|
||||
readonly context:
|
||||
| "package-entrypoint"
|
||||
| "filesystem-expression"
|
||||
| "module-specifier"
|
||||
| "html-reference";
|
||||
readonly context: ArtifactPathResolutionContext;
|
||||
readonly files: ReadonlyMap<string, JavaScriptArtifactFile>;
|
||||
readonly htmlBaseHref?: string | null;
|
||||
readonly moduleKind?: "import" | "require";
|
||||
@@ -50,11 +59,17 @@ const NODE_BUILTINS = new Set(
|
||||
builtinModules.map((name) => name.replace(/^node:/u, "")),
|
||||
);
|
||||
|
||||
interface CandidateResolution {
|
||||
readonly resolvedPath: string | null;
|
||||
readonly status: ArtifactPathResolution["resolution_status"];
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
type CandidateResolution =
|
||||
| {
|
||||
readonly resolvedPath: string;
|
||||
readonly status: "resolved";
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
| {
|
||||
readonly resolvedPath: null;
|
||||
readonly status: UnresolvedArtifactPathStatus;
|
||||
readonly limitations: readonly string[];
|
||||
};
|
||||
|
||||
/** Resolve one declaration under its exact syntax/metadata context. */
|
||||
export const resolveArtifactPathByContext = (
|
||||
@@ -72,12 +87,7 @@ const resolveAtDepth = (
|
||||
const confined = confineCandidate(input, candidate);
|
||||
if (typeof confined !== "string") return confined;
|
||||
const resolved = resolveCandidate(input, confined, packageDepth);
|
||||
return outcome(
|
||||
input,
|
||||
resolved.status,
|
||||
resolved.resolvedPath,
|
||||
resolved.limitations,
|
||||
);
|
||||
return outcome(input, resolved);
|
||||
};
|
||||
|
||||
const rejectDeclaration = (
|
||||
@@ -85,17 +95,19 @@ const rejectDeclaration = (
|
||||
): ArtifactPathResolution | null => {
|
||||
const declared = input.declaredPath;
|
||||
if (declared.length === 0)
|
||||
return outcome(input, "rejected", null, ["The declared path is empty."]);
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"The declared path is empty.",
|
||||
]);
|
||||
if (declared.length > 4_096)
|
||||
return outcome(input, "rejected", null, [
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"The declared path exceeds the 4096-character resolution bound.",
|
||||
]);
|
||||
if (declared.includes("\0") || declared.includes("\\"))
|
||||
return outcome(input, "rejected", null, [
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"NUL and backslash path syntax are not admitted for canonical artifact paths.",
|
||||
]);
|
||||
if (/%(?:2e|2f|5c)/iu.test(declared))
|
||||
return outcome(input, "rejected", null, [
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"Encoded dot or separator bytes are rejected before artifact path resolution.",
|
||||
]);
|
||||
return null;
|
||||
@@ -114,13 +126,13 @@ const contextualCandidate = (
|
||||
const fileUrl = fileUrlPath(declared);
|
||||
if (fileUrl !== undefined) return fileUrl;
|
||||
if (hasScheme(declared))
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"URL and Node builtin schemes are outside static artifact module resolution.",
|
||||
]);
|
||||
if (!declared.startsWith(".") && !declared.startsWith("/"))
|
||||
return bareModuleCandidate(input, declared);
|
||||
} else if (hasScheme(declared))
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"URL schemes are outside this local artifact path context.",
|
||||
]);
|
||||
const relative = declared.startsWith("/") ? declared.slice(1) : declared;
|
||||
@@ -139,11 +151,11 @@ const bareModuleCandidate = (
|
||||
NODE_BUILTINS.has(packageName) ||
|
||||
declared.startsWith("#")
|
||||
)
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"The bare specifier is a Node builtin, package import map, or invalid package name.",
|
||||
]);
|
||||
if (declared !== packageName)
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"Bare package subpaths remain unresolved unless an exact package-exports subpath model is available.",
|
||||
]);
|
||||
const source = input.files.get(input.sourcePath);
|
||||
@@ -155,7 +167,7 @@ const bareModuleCandidate = (
|
||||
if (directory === "." || directory === "") break;
|
||||
directory = posix.dirname(directory);
|
||||
}
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"No matching bare package was inventoried in an enclosing node_modules directory.",
|
||||
]);
|
||||
};
|
||||
@@ -190,7 +202,7 @@ const htmlCandidate = (
|
||||
): string | ArtifactPathResolution => {
|
||||
const declared = stripQueryAndFragment(input.declaredPath);
|
||||
if (hasScheme(declared))
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"External HTML references are not mapped to local artifact assets.",
|
||||
]);
|
||||
if (declared.startsWith("/")) return declared.slice(1);
|
||||
@@ -198,7 +210,7 @@ const htmlCandidate = (
|
||||
if (base === undefined || base === null || base === "")
|
||||
return posix.join(posix.dirname(input.sourcePath), declared);
|
||||
if (hasScheme(base))
|
||||
return outcome(input, "external", null, [
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"The document base href is external, so its script reference is not a local artifact path.",
|
||||
]);
|
||||
const basePath = base.startsWith("/")
|
||||
@@ -218,7 +230,7 @@ const confineCandidate = (
|
||||
normalized.startsWith("../") ||
|
||||
normalized.startsWith("/")
|
||||
)
|
||||
return outcome(input, "rejected", null, [
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"The resolved candidate escapes the canonical artifact root.",
|
||||
]);
|
||||
return normalized === "." ? "" : normalized;
|
||||
@@ -282,11 +294,17 @@ const resolveCandidate = (
|
||||
},
|
||||
packageDepth + 1,
|
||||
);
|
||||
return {
|
||||
resolvedPath: nested.resolved_path,
|
||||
status: nested.resolution_status,
|
||||
limitations: nested.limitations,
|
||||
};
|
||||
return nested.resolution_status === "resolved"
|
||||
? {
|
||||
resolvedPath: nested.resolved_path,
|
||||
status: nested.resolution_status,
|
||||
limitations: nested.limitations,
|
||||
}
|
||||
: {
|
||||
resolvedPath: null,
|
||||
status: nested.resolution_status,
|
||||
limitations: nested.limitations,
|
||||
};
|
||||
};
|
||||
|
||||
const directCandidates = (candidate: string): readonly string[] => [
|
||||
@@ -374,13 +392,27 @@ const stripQueryAndFragment = (value: string): string =>
|
||||
|
||||
const outcome = (
|
||||
input: ResolveArtifactPathInput,
|
||||
status: ArtifactPathResolution["resolution_status"],
|
||||
resolvedPath: string | null,
|
||||
resolution: CandidateResolution,
|
||||
): ArtifactPathResolution =>
|
||||
resolution.status === "resolved"
|
||||
? {
|
||||
declared_path: input.declaredPath,
|
||||
resolution_context: input.context,
|
||||
resolved_path: resolution.resolvedPath,
|
||||
resolution_status: resolution.status,
|
||||
limitations: resolution.limitations,
|
||||
}
|
||||
: {
|
||||
declared_path: input.declaredPath,
|
||||
resolution_context: input.context,
|
||||
resolved_path: null,
|
||||
resolution_status: resolution.status,
|
||||
limitations: resolution.limitations,
|
||||
};
|
||||
|
||||
const unresolvedOutcome = (
|
||||
input: ResolveArtifactPathInput,
|
||||
status: UnresolvedArtifactPathStatus,
|
||||
limitations: readonly string[],
|
||||
): ArtifactPathResolution => ({
|
||||
declared_path: input.declaredPath,
|
||||
resolution_context: input.context,
|
||||
resolved_path: resolvedPath,
|
||||
resolution_status: status,
|
||||
limitations,
|
||||
});
|
||||
): ArtifactPathResolution =>
|
||||
outcome(input, { resolvedPath: null, status, limitations });
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
import { posix } from "node:path";
|
||||
|
||||
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
|
||||
import {
|
||||
completeApplicationCoverage,
|
||||
partialApplicationCoverage,
|
||||
truncatedApplicationCoverage,
|
||||
} from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import type {
|
||||
JavaScriptModuleOrigin,
|
||||
JavaScriptSemanticIr,
|
||||
@@ -16,11 +21,12 @@ import {
|
||||
} from "./JavaScriptArtifactGraphContext.js";
|
||||
import {
|
||||
astObservationEvidence,
|
||||
completeReconstructionCoverage,
|
||||
partialReconstructionCoverage,
|
||||
staticInferenceEvidence,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
|
||||
import {
|
||||
resolveArtifactPathByContext,
|
||||
type ArtifactPathResolution,
|
||||
} from "./JavaScriptArtifactPathResolution.js";
|
||||
import { projectJavaScriptExportReturnShapes } from "./JavaScriptReturnShapeProjection.js";
|
||||
|
||||
interface SemanticAnalysis {
|
||||
@@ -36,18 +42,24 @@ interface RelationshipInput {
|
||||
readonly link: JavaScriptSemanticModuleLink;
|
||||
}
|
||||
|
||||
interface ResolvedModuleTarget {
|
||||
type ResolvedModuleTarget = {
|
||||
readonly node: ApplicationNode;
|
||||
readonly path: string | null;
|
||||
readonly file: JavaScriptArtifactFile | null;
|
||||
readonly status:
|
||||
| "resolved"
|
||||
| "not-found"
|
||||
| "unavailable"
|
||||
| "external"
|
||||
| "rejected";
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
} & (
|
||||
| {
|
||||
readonly path: string;
|
||||
readonly file: JavaScriptArtifactFile;
|
||||
readonly status: "resolved";
|
||||
}
|
||||
| {
|
||||
readonly path: null;
|
||||
readonly file: null;
|
||||
readonly status: Exclude<
|
||||
ArtifactPathResolution["resolution_status"],
|
||||
"resolved"
|
||||
>;
|
||||
}
|
||||
);
|
||||
|
||||
/** Create one path-scoped source-module identity for every analyzed source file. */
|
||||
export const addJavaScriptSourceModules = (
|
||||
@@ -239,26 +251,32 @@ const resolveModuleTarget = (
|
||||
? "require"
|
||||
: "import",
|
||||
});
|
||||
const path = resolution.resolved_path;
|
||||
const file = path === null ? undefined : input.context.filesByPath.get(path);
|
||||
const node =
|
||||
path === null
|
||||
? undefined
|
||||
: (input.context.sourceModuleNodes.get(path) ??
|
||||
input.context.fileNodes.get(path));
|
||||
if (path !== null && file !== undefined && node !== undefined)
|
||||
if (resolution.resolution_status !== "resolved")
|
||||
return {
|
||||
node,
|
||||
path,
|
||||
file,
|
||||
status: "resolved",
|
||||
node: unresolvedModuleNode(
|
||||
input,
|
||||
specifier,
|
||||
resolution.resolution_status,
|
||||
),
|
||||
path: null,
|
||||
file: null,
|
||||
status: resolution.resolution_status,
|
||||
limitations: resolution.limitations,
|
||||
};
|
||||
const path = resolution.resolved_path;
|
||||
const file = input.context.filesByPath.get(path);
|
||||
const node =
|
||||
input.context.sourceModuleNodes.get(path) ??
|
||||
input.context.fileNodes.get(path);
|
||||
if (file === undefined || node === undefined)
|
||||
throw new TypeError(
|
||||
`Resolved artifact path ${path} is absent from its graph context.`,
|
||||
);
|
||||
return {
|
||||
node: unresolvedModuleNode(input, specifier, resolution.resolution_status),
|
||||
path: null,
|
||||
file: null,
|
||||
status: resolution.resolution_status,
|
||||
node,
|
||||
path,
|
||||
file,
|
||||
status: "resolved",
|
||||
limitations: resolution.limitations,
|
||||
};
|
||||
};
|
||||
@@ -266,7 +284,7 @@ const resolveModuleTarget = (
|
||||
const unresolvedModuleNode = (
|
||||
input: RelationshipInput,
|
||||
specifier: string,
|
||||
status: ResolvedModuleTarget["status"],
|
||||
status: Exclude<ResolvedModuleTarget["status"], "resolved">,
|
||||
): ApplicationNode =>
|
||||
input.context.accumulator.addNode({
|
||||
kind: "javascript-module",
|
||||
@@ -360,12 +378,10 @@ const semanticCoverage = (
|
||||
unit: "items" as const,
|
||||
}));
|
||||
if (semantic.ir.coverage.status === "complete")
|
||||
return completeReconstructionCoverage(limits);
|
||||
return partialReconstructionCoverage(
|
||||
limits,
|
||||
semantic.ir.coverage.omittedCount,
|
||||
semantic.ir.coverage.status === "truncated",
|
||||
);
|
||||
return completeApplicationCoverage(limits);
|
||||
return semantic.ir.coverage.status === "truncated"
|
||||
? truncatedApplicationCoverage(limits, semantic.ir.coverage.omittedCount)
|
||||
: partialApplicationCoverage(limits, semantic.ir.coverage.omittedCount);
|
||||
};
|
||||
|
||||
const moduleFormat = (
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import {
|
||||
partialApplicationCoverage,
|
||||
truncatedApplicationCoverage,
|
||||
} from "../domain/javascriptApplicationEvidenceSchemas.js";
|
||||
import type {
|
||||
JavaScriptSemanticIr,
|
||||
JavaScriptSemanticCallable,
|
||||
@@ -7,7 +11,6 @@ import type {
|
||||
import { flattenSemanticReturnValue } from "../domain/javascriptSemanticReturns.js";
|
||||
import type { JavaScriptSourceRange } from "../domain/javascriptStaticAnalysisTypes.js";
|
||||
import type { JavaScriptArtifactGraphCoverage } from "./JavaScriptArtifactGraphContext.js";
|
||||
import { partialReconstructionCoverage } from "./JavaScriptArtifactGraphEvidence.js";
|
||||
|
||||
const MAX_PROJECTED_RETURN_SHAPES = 32;
|
||||
const MAX_PROJECTED_RETURN_FIELDS = 64;
|
||||
@@ -43,30 +46,31 @@ export const projectJavaScriptExportReturnShapes = (input: {
|
||||
input.baseCoverage.status === "complete" &&
|
||||
callable.returnCoverage.status === "complete" &&
|
||||
projectionOmitted === 0;
|
||||
const limits = [
|
||||
...input.baseCoverage.limits,
|
||||
{
|
||||
name: "return-shape-sites",
|
||||
value: MAX_PROJECTED_RETURN_SHAPES,
|
||||
unit: "items" as const,
|
||||
},
|
||||
{
|
||||
name: "return-shape-fields",
|
||||
value: MAX_PROJECTED_RETURN_FIELDS,
|
||||
unit: "items" as const,
|
||||
},
|
||||
{
|
||||
name: "return-shape-property-coverage",
|
||||
value: MAX_PROJECTED_PROPERTY_COVERAGE,
|
||||
unit: "items" as const,
|
||||
},
|
||||
];
|
||||
const omitted =
|
||||
semanticOmitted === null ? null : semanticOmitted + projectionOmitted;
|
||||
const coverage = complete
|
||||
? input.baseCoverage
|
||||
: partialReconstructionCoverage(
|
||||
[
|
||||
...input.baseCoverage.limits,
|
||||
{
|
||||
name: "return-shape-sites",
|
||||
value: MAX_PROJECTED_RETURN_SHAPES,
|
||||
unit: "items",
|
||||
},
|
||||
{
|
||||
name: "return-shape-fields",
|
||||
value: MAX_PROJECTED_RETURN_FIELDS,
|
||||
unit: "items",
|
||||
},
|
||||
{
|
||||
name: "return-shape-property-coverage",
|
||||
value: MAX_PROJECTED_PROPERTY_COVERAGE,
|
||||
unit: "items",
|
||||
},
|
||||
],
|
||||
semanticOmitted === null ? null : semanticOmitted + projectionOmitted,
|
||||
callable.returnCoverage.status === "truncated" || projectionOmitted > 0,
|
||||
);
|
||||
: callable.returnCoverage.status === "truncated" || projectionOmitted > 0
|
||||
? truncatedApplicationCoverage(limits, omitted)
|
||||
: partialApplicationCoverage(limits, omitted);
|
||||
const limitations = [
|
||||
...input.ir.limitations,
|
||||
"Return shapes are inferred from inert syntax and do not prove runtime behavior.",
|
||||
|
||||
@@ -0,0 +1,317 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { buildJavaScriptSemanticGraph } from "./JavaScriptSemanticGraphBuilder.js";
|
||||
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
|
||||
import { queryJavaScriptSemanticGraph } from "../domain/javascriptSemanticQuery.js";
|
||||
import { analyzeJavaScriptSemantics } from "../domain/javascriptSemanticAnalysis.js";
|
||||
import {
|
||||
DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS,
|
||||
type JavaScriptSemanticLimits,
|
||||
} from "../domain/javascriptSemanticIr.js";
|
||||
|
||||
const SHA256 = "a".repeat(64);
|
||||
const GRAPH_ID = `jag_${"b".repeat(64)}`;
|
||||
|
||||
it("projects closure and direct interprocedural flow without execution", () => {
|
||||
const graph = graphFor(`
|
||||
const outer = 2;
|
||||
function add(value) { return value + outer; }
|
||||
const input = 40;
|
||||
const answer = add(input);
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"argument-to-parameter",
|
||||
"calls",
|
||||
"captures",
|
||||
"defines",
|
||||
"reads",
|
||||
"returns-to-call",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(graph.coverage.families).toHaveLength(12);
|
||||
expect(graph.limitations).toContain(
|
||||
"The semantic graph contains static syntax observations and conservative relationship candidates; it does not claim runtime execution.",
|
||||
);
|
||||
const parameter = graph.nodes.find(
|
||||
({ kind, label }) => kind === "parameter" && label === "value",
|
||||
);
|
||||
if (parameter === undefined) throw new Error("Expected parameter node");
|
||||
const provenance = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: parameter.node_id },
|
||||
direction: "backward-provenance",
|
||||
include_ambiguous_dynamic_edges: true,
|
||||
});
|
||||
expect(provenance.relations.map(({ relation }) => relation)).toEqual(
|
||||
expect.arrayContaining([
|
||||
"aliases",
|
||||
"argument-to-parameter",
|
||||
"defines",
|
||||
"reads",
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps dynamic calls explicit and returns bounded deterministic pages", () => {
|
||||
const graph = graphFor(`
|
||||
const handlers = { ready() { return 1; } };
|
||||
const key = process.argv[2];
|
||||
handlers[key]();
|
||||
`);
|
||||
expect(graph.unknowns.some(({ reason }) => reason === "dynamic-call")).toBe(
|
||||
true,
|
||||
);
|
||||
const seedNodeId = graph.relations.find(
|
||||
({ relation }) => relation === "defines",
|
||||
)?.source_node_id;
|
||||
expect(seedNodeId).toBeDefined();
|
||||
if (seedNodeId === undefined) throw new Error("Expected a definition seed");
|
||||
|
||||
const first = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: seedNodeId },
|
||||
direction: "forward-influence",
|
||||
include_ambiguous_dynamic_edges: true,
|
||||
limits: {
|
||||
max_seed_matches: 25,
|
||||
max_nodes: 2_000,
|
||||
max_edges: 4_000,
|
||||
max_depth: 12,
|
||||
max_functions: 500,
|
||||
max_modules: 500,
|
||||
page_size: 1,
|
||||
},
|
||||
});
|
||||
const repeated = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: seedNodeId },
|
||||
direction: "forward-influence",
|
||||
include_ambiguous_dynamic_edges: true,
|
||||
limits: first.applied_limits,
|
||||
});
|
||||
expect(repeated).toEqual(first);
|
||||
});
|
||||
|
||||
it("keeps ambiguous interprocedural flow out of the default traversal", () => {
|
||||
const graph = graphFor(`
|
||||
function left(value) { return value; }
|
||||
function right(value) { return value; }
|
||||
const input = 1;
|
||||
const selected = Math.random() ? left : right;
|
||||
selected(input);
|
||||
`);
|
||||
const input = graph.nodes.find(
|
||||
({ kind, label }) => kind === "binding" && label === "input",
|
||||
);
|
||||
if (input === undefined) throw new Error("Expected input binding");
|
||||
const query = {
|
||||
seed: { kind: "semantic-node" as const, node_id: input.node_id },
|
||||
direction: "forward-influence" as const,
|
||||
allowed_relations: [
|
||||
"reads" as const,
|
||||
"aliases" as const,
|
||||
"argument-to-parameter" as const,
|
||||
],
|
||||
};
|
||||
const strict = queryJavaScriptSemanticGraph(graph, query);
|
||||
expect(
|
||||
strict.relations.some(
|
||||
({ relation }) => relation === "argument-to-parameter",
|
||||
),
|
||||
).toBe(false);
|
||||
expect(strict.status).toBe("ambiguous");
|
||||
const admitted = queryJavaScriptSemanticGraph(graph, {
|
||||
...query,
|
||||
include_ambiguous_dynamic_edges: true,
|
||||
});
|
||||
expect(
|
||||
admitted.relations.filter(
|
||||
({ relation }) => relation === "argument-to-parameter",
|
||||
),
|
||||
).toHaveLength(2);
|
||||
expect(admitted.status).toBe("ambiguous");
|
||||
});
|
||||
|
||||
it("connects caller results, direct returns, parameters, and captures", () => {
|
||||
const graph = graphFor(`
|
||||
const outer = 2;
|
||||
function identity(value) { return value; }
|
||||
function readOuter() { return outer; }
|
||||
const input = 40;
|
||||
const output = identity(input);
|
||||
`);
|
||||
const binding = (label: string) =>
|
||||
graph.nodes.find(
|
||||
({ kind, label: nodeLabel }) =>
|
||||
["binding", "parameter"].includes(kind) && nodeLabel === label,
|
||||
);
|
||||
const output = binding("output");
|
||||
const input = binding("input");
|
||||
const outer = binding("outer");
|
||||
const readOuter = graph.nodes.find(
|
||||
({ kind, label }) => kind === "function" && label === "readOuter",
|
||||
);
|
||||
if (
|
||||
output === undefined ||
|
||||
input === undefined ||
|
||||
outer === undefined ||
|
||||
readOuter === undefined
|
||||
)
|
||||
throw new Error("Expected semantic flow nodes");
|
||||
const provenance = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: output.node_id },
|
||||
direction: "backward-provenance",
|
||||
});
|
||||
expect(provenance.nodes.map(({ node_id }) => node_id)).toContain(
|
||||
input.node_id,
|
||||
);
|
||||
const influence = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: outer.node_id },
|
||||
direction: "forward-influence",
|
||||
allowed_relations: ["captures"],
|
||||
});
|
||||
expect(influence.nodes.map(({ node_id }) => node_id)).toContain(
|
||||
readOuter.node_id,
|
||||
);
|
||||
const capture = graph.relations.find(
|
||||
({ relation }) => relation === "captures",
|
||||
);
|
||||
expect(capture?.evidence.location).toMatchObject({
|
||||
available: true,
|
||||
value: { kind: "source-range", source: "app.js" },
|
||||
});
|
||||
expect(capture?.evidence.location).not.toEqual(readOuter.evidence.location);
|
||||
});
|
||||
|
||||
it("preserves semantic analyzer truncation in graph coverage", () => {
|
||||
const graph = graphFor(
|
||||
"const first = 1; const second = first; const third = second;",
|
||||
{ maxReferences: 1 },
|
||||
);
|
||||
expect(graph.coverage).toMatchObject({
|
||||
status: "partial",
|
||||
truncated: true,
|
||||
omitted_nodes: null,
|
||||
omitted_relations: null,
|
||||
limits: expect.arrayContaining([
|
||||
{ name: "semantic.maxReferences", value: 1, unit: "items" },
|
||||
]),
|
||||
});
|
||||
expect(
|
||||
graph.coverage.families.find(
|
||||
({ family }) => family === "promise-ownership",
|
||||
),
|
||||
).toMatchObject({ status: "unknown", retained_relations: 0 });
|
||||
});
|
||||
|
||||
it("projects bounded Promise ownership and unresolved sources", () => {
|
||||
const graph = graphFor(`
|
||||
async function run(value) {
|
||||
const owned = new Promise((resolve) => resolve(value));
|
||||
await Promise.resolve(owned);
|
||||
Promise.resolve(value).then(work).finally(cleanup);
|
||||
value.then(work);
|
||||
return Promise.all([owned, Promise.resolve(value)]);
|
||||
}
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"aggregates",
|
||||
"awaits",
|
||||
"chains",
|
||||
"creates-promise",
|
||||
"detaches-task",
|
||||
"owns",
|
||||
"returns-task",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(graph.nodes.filter(({ kind }) => kind === "promise")).not.toHaveLength(
|
||||
0,
|
||||
);
|
||||
expect(
|
||||
graph.nodes.find(
|
||||
({ kind, properties }) =>
|
||||
kind === "promise" &&
|
||||
properties.method === "all" &&
|
||||
properties.ownership === "returned",
|
||||
),
|
||||
).toBeDefined();
|
||||
expect(
|
||||
graph.unknowns.some(
|
||||
({ family, reason }) =>
|
||||
family === "promise-ownership" && reason === "ambiguous-target",
|
||||
),
|
||||
).toBe(true);
|
||||
expect(
|
||||
graph.coverage.families.find(
|
||||
({ family }) => family === "promise-ownership",
|
||||
),
|
||||
).toMatchObject({ status: "partial" });
|
||||
});
|
||||
|
||||
it("keeps duplicate function fingerprints ambiguous", () => {
|
||||
const graph = graphFor(`
|
||||
function first(value) { return value + 1; }
|
||||
function second(input) { return input + 1; }
|
||||
`);
|
||||
|
||||
expect(graph.fingerprints).toHaveLength(2);
|
||||
const digest = graph.fingerprints[0]?.fingerprint_sha256;
|
||||
expect(digest).toBeDefined();
|
||||
expect(graph.fingerprints[1]?.fingerprint_sha256).toBe(digest);
|
||||
if (digest === undefined) throw new Error("Expected fingerprint");
|
||||
const query = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "function", fingerprint_sha256: digest },
|
||||
direction: "forward-influence",
|
||||
});
|
||||
expect(query.status).toBe("ambiguous");
|
||||
expect(query.summary.total_seed_matches).toBe(2);
|
||||
});
|
||||
|
||||
const graphFor = (
|
||||
source: string,
|
||||
inputLimits: Partial<JavaScriptSemanticLimits> = {},
|
||||
) => {
|
||||
const file: JavaScriptArtifactFile = {
|
||||
path: "app.js",
|
||||
container_sha256: SHA256,
|
||||
sha256: SHA256,
|
||||
bytes: Buffer.byteLength(source),
|
||||
inventory_artifact_id: `art_${SHA256}`,
|
||||
kind: "javascript",
|
||||
unpacked: false,
|
||||
text: { included: true, value: source },
|
||||
};
|
||||
const semanticLimits = {
|
||||
...DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS,
|
||||
...inputLimits,
|
||||
};
|
||||
const analysis: JavaScriptArtifactAnalysis = {
|
||||
files: [
|
||||
{
|
||||
file,
|
||||
javascript: null,
|
||||
semantic: {
|
||||
ir: analyzeJavaScriptSemantics(source, inputLimits),
|
||||
limits: semanticLimits,
|
||||
},
|
||||
},
|
||||
],
|
||||
packages: [],
|
||||
json_modules: [],
|
||||
html_scripts: [],
|
||||
source_maps: [],
|
||||
visited_ast_nodes: 0,
|
||||
findings: 0,
|
||||
modules: 0,
|
||||
parse_failures: 0,
|
||||
truncated_scopes: 0,
|
||||
limitations: [],
|
||||
};
|
||||
return buildJavaScriptSemanticGraph({
|
||||
rootArtifactSha256: SHA256,
|
||||
applicationGraph: { graph_id: GRAPH_ID, nodes: [] },
|
||||
analysis,
|
||||
});
|
||||
};
|
||||
@@ -0,0 +1,318 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { buildJavaScriptSemanticGraph } from "./JavaScriptSemanticGraphBuilder.js";
|
||||
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
|
||||
import { queryJavaScriptSemanticGraph } from "../domain/javascriptSemanticQuery.js";
|
||||
import { analyzeJavaScriptSemantics } from "../domain/javascriptSemanticAnalysis.js";
|
||||
import {
|
||||
DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS,
|
||||
type JavaScriptSemanticLimits,
|
||||
} from "../domain/javascriptSemanticIr.js";
|
||||
|
||||
const SHA256 = "a".repeat(64);
|
||||
const GRAPH_ID = `jag_${"b".repeat(64)}`;
|
||||
|
||||
it("projects literal events and exact timer cancellation", () => {
|
||||
const graph = graphFor(`
|
||||
function run(bus, dynamicName) {
|
||||
const handle = setInterval(tick, 10);
|
||||
bus.on("ready", handler);
|
||||
bus.once(dynamicName, handler);
|
||||
bus.emit("ready");
|
||||
bus.removeListener("ready", handler);
|
||||
clearInterval(handle);
|
||||
}
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"cancels-timer",
|
||||
"dispatches-candidate",
|
||||
"registers-listener",
|
||||
"removes-listener",
|
||||
"schedules-timer",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(
|
||||
graph.nodes.find(
|
||||
({ kind, properties }) =>
|
||||
kind === "event" && properties.event_name === "ready",
|
||||
),
|
||||
).toBeDefined();
|
||||
expect(
|
||||
graph.unknowns.some(
|
||||
({ family, detail }) =>
|
||||
family === "event" && detail.includes("Dynamic once event name"),
|
||||
),
|
||||
).toBe(true);
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "event"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "timer"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
});
|
||||
|
||||
it("projects child-process creation, I/O, listeners, and signals", () => {
|
||||
const graph = graphFor(`
|
||||
import { spawn } from "node:child_process";
|
||||
function run(command) {
|
||||
const child = spawn(
|
||||
command,
|
||||
["--mode", "fast"],
|
||||
{ env: process.env, stdio: "pipe" },
|
||||
);
|
||||
child.on("exit", onExit);
|
||||
child.once("error", onError);
|
||||
child.kill("SIGTERM");
|
||||
}
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"connects-stdio",
|
||||
"forwards-signal",
|
||||
"listens-error",
|
||||
"listens-exit",
|
||||
"spawns",
|
||||
"supplies-argv",
|
||||
"supplies-env",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(
|
||||
graph.nodes.find(
|
||||
({ kind, properties }) =>
|
||||
kind === "child-process" &&
|
||||
properties.method === "spawn" &&
|
||||
properties.command === null,
|
||||
),
|
||||
).toBeDefined();
|
||||
expect(
|
||||
graph.unknowns.some(
|
||||
({ family, detail }) =>
|
||||
family === "child-process" &&
|
||||
detail.includes("command remains unresolved"),
|
||||
),
|
||||
).toBe(true);
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "child-process"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
});
|
||||
|
||||
it("projects config precedence, request fields, and boundaries", () => {
|
||||
const graph = graphFor(`
|
||||
import { readFileSync } from "node:fs";
|
||||
async function run(schema) {
|
||||
const endpoint = process.env.API_URL ?? "https://fallback.test";
|
||||
const raw = readFileSync("./config.json", "utf8");
|
||||
const parsed = JSON.parse(raw);
|
||||
const port = Number(process.argv[2]);
|
||||
const validated = schema.parse(parsed);
|
||||
const response = await fetch(endpoint, {
|
||||
method: "POST",
|
||||
body: validated,
|
||||
});
|
||||
return response.json();
|
||||
}
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"coerces",
|
||||
"constructs-request",
|
||||
"consumed-by",
|
||||
"defaults",
|
||||
"overrides",
|
||||
"parses",
|
||||
"reads-argv",
|
||||
"reads-config",
|
||||
"reads-environment",
|
||||
"supplies-request-field",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(
|
||||
graph.nodes.find(
|
||||
({ kind, properties }) =>
|
||||
kind === "request" && properties.method === "fetch",
|
||||
),
|
||||
).toBeDefined();
|
||||
expect(
|
||||
graph.nodes.filter(({ kind }) => kind === "boundary"),
|
||||
).not.toHaveLength(0);
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "configuration"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "request"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
expect(
|
||||
graph.coverage.families.find(({ family }) => family === "boundary"),
|
||||
).toMatchObject({ status: "partial" });
|
||||
});
|
||||
|
||||
it("projects built-in resource acquisition and release", () => {
|
||||
const graph = graphFor(`
|
||||
import { open } from "node:fs/promises";
|
||||
import { connect } from "node:net";
|
||||
async function run(path) {
|
||||
const file = await open(path);
|
||||
const socket = connect({ port: 9000 });
|
||||
await file.close();
|
||||
socket.end();
|
||||
}
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
expect(relations.has("acquires")).toBe(true);
|
||||
expect(relations.has("releases")).toBe(true);
|
||||
expect(graph.nodes.filter(({ kind }) => kind === "resource")).toHaveLength(2);
|
||||
expect(
|
||||
graph.coverage.families.find(
|
||||
({ family }) => family === "resource-lifecycle",
|
||||
),
|
||||
).toMatchObject({ status: "partial" });
|
||||
});
|
||||
|
||||
it("projects literal seeds and static object flow", () => {
|
||||
const graph = graphFor(`
|
||||
const source = { token: "TOKEN", count: 1 };
|
||||
const { token } = source;
|
||||
const copy = { ...source };
|
||||
source.count = 2;
|
||||
const read = source.token;
|
||||
`);
|
||||
|
||||
const relations = new Set(graph.relations.map(({ relation }) => relation));
|
||||
for (const expected of [
|
||||
"destructures",
|
||||
"reads-property",
|
||||
"spreads",
|
||||
"writes-property",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(
|
||||
graph.nodes.find(
|
||||
({ kind, properties }) =>
|
||||
kind === "property-slot" && properties.name === "token",
|
||||
),
|
||||
).toBeDefined();
|
||||
const literal = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "literal", value: "TOKEN" },
|
||||
direction: "forward-influence",
|
||||
});
|
||||
expect(literal.status).toBe("ambiguous");
|
||||
expect(literal.summary.total_seed_matches).toBe(3);
|
||||
const property = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "property", name: "token" },
|
||||
direction: "forward-influence",
|
||||
});
|
||||
expect(property.status).toBe("found");
|
||||
});
|
||||
|
||||
it("does not promote transformed return expressions to resolved aliases", () => {
|
||||
const graph = graphFor(`
|
||||
function increment(value) { return value + 1; }
|
||||
const input = 1;
|
||||
const output = increment(input);
|
||||
`);
|
||||
const returnNode = graph.nodes.find(({ kind }) => kind === "return-site");
|
||||
if (returnNode === undefined) throw new Error("Expected return site");
|
||||
expect(
|
||||
graph.relations.filter(
|
||||
({ relation, target_node_id }) =>
|
||||
relation === "aliases" && target_node_id === returnNode.node_id,
|
||||
),
|
||||
).toEqual([expect.objectContaining({ resolution: "candidate" })]);
|
||||
const output = graph.nodes.find(
|
||||
({ kind, label }) => kind === "binding" && label === "output",
|
||||
);
|
||||
const input = graph.nodes.find(
|
||||
({ kind, label }) => kind === "binding" && label === "input",
|
||||
);
|
||||
if (output === undefined || input === undefined)
|
||||
throw new Error("Expected caller bindings");
|
||||
const strict = queryJavaScriptSemanticGraph(graph, {
|
||||
seed: { kind: "semantic-node", node_id: output.node_id },
|
||||
direction: "backward-provenance",
|
||||
});
|
||||
expect(strict.nodes.map(({ node_id }) => node_id)).not.toContain(
|
||||
input.node_id,
|
||||
);
|
||||
expect(strict.status).toBe("ambiguous");
|
||||
});
|
||||
|
||||
it("uses unavailable evidence when no source produced semantic IR", () => {
|
||||
const graph = buildJavaScriptSemanticGraph({
|
||||
rootArtifactSha256: SHA256,
|
||||
applicationGraph: { graph_id: GRAPH_ID, nodes: [] },
|
||||
analysis: emptyAnalysis(),
|
||||
});
|
||||
expect(graph.nodes).toHaveLength(1);
|
||||
expect(graph.nodes[0]?.evidence).toMatchObject({
|
||||
authority: "unknown",
|
||||
state: "unavailable",
|
||||
location: { available: false, reason: "not-observed" },
|
||||
});
|
||||
});
|
||||
|
||||
const emptyAnalysis = (): JavaScriptArtifactAnalysis => ({
|
||||
files: [],
|
||||
packages: [],
|
||||
json_modules: [],
|
||||
html_scripts: [],
|
||||
source_maps: [],
|
||||
visited_ast_nodes: 0,
|
||||
findings: 0,
|
||||
modules: 0,
|
||||
parse_failures: 0,
|
||||
truncated_scopes: 0,
|
||||
limitations: [],
|
||||
});
|
||||
|
||||
const graphFor = (
|
||||
source: string,
|
||||
inputLimits: Partial<JavaScriptSemanticLimits> = {},
|
||||
) => {
|
||||
const file: JavaScriptArtifactFile = {
|
||||
path: "app.js",
|
||||
container_sha256: SHA256,
|
||||
sha256: SHA256,
|
||||
bytes: Buffer.byteLength(source),
|
||||
inventory_artifact_id: `art_${SHA256}`,
|
||||
kind: "javascript",
|
||||
unpacked: false,
|
||||
text: { included: true, value: source },
|
||||
};
|
||||
const semanticLimits = {
|
||||
...DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS,
|
||||
...inputLimits,
|
||||
};
|
||||
const analysis: JavaScriptArtifactAnalysis = {
|
||||
files: [
|
||||
{
|
||||
file,
|
||||
javascript: null,
|
||||
semantic: {
|
||||
ir: analyzeJavaScriptSemantics(source, inputLimits),
|
||||
limits: semanticLimits,
|
||||
},
|
||||
},
|
||||
],
|
||||
packages: [],
|
||||
json_modules: [],
|
||||
html_scripts: [],
|
||||
source_maps: [],
|
||||
visited_ast_nodes: 0,
|
||||
findings: 0,
|
||||
modules: 0,
|
||||
parse_failures: 0,
|
||||
truncated_scopes: 0,
|
||||
limitations: [],
|
||||
};
|
||||
return buildJavaScriptSemanticGraph({
|
||||
rootArtifactSha256: SHA256,
|
||||
applicationGraph: { graph_id: GRAPH_ID, nodes: [] },
|
||||
analysis,
|
||||
});
|
||||
};
|
||||
@@ -64,14 +64,24 @@ export const linuxHopperInstallDisclosure = (
|
||||
};
|
||||
};
|
||||
|
||||
/** Parsed Linux distribution information used for support and package selection. */
|
||||
export interface LinuxDistribution {
|
||||
interface LinuxDistributionIdentity {
|
||||
readonly id: string;
|
||||
readonly versionId?: string;
|
||||
readonly packageFamily: LinuxPackageFamily | undefined;
|
||||
readonly supported: boolean;
|
||||
}
|
||||
|
||||
/** Parsed Linux distribution information used for support and package selection. */
|
||||
export type LinuxDistribution = LinuxDistributionIdentity &
|
||||
(
|
||||
| {
|
||||
readonly packageFamily: LinuxPackageFamily;
|
||||
readonly supported: true;
|
||||
}
|
||||
| {
|
||||
readonly packageFamily: LinuxPackageFamily | undefined;
|
||||
readonly supported: false;
|
||||
}
|
||||
);
|
||||
|
||||
/** Download response kept independent of Node's global fetch implementation. */
|
||||
export interface LinuxHopperDownload {
|
||||
readonly ok: boolean;
|
||||
@@ -134,15 +144,17 @@ export const parseLinuxDistribution = (text: string): LinuxDistribution => {
|
||||
const versionId = fields.get("VERSION_ID");
|
||||
const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
|
||||
const supported =
|
||||
id === "arch" ||
|
||||
(id === "ubuntu" && versionAtLeast(versionId, 24)) ||
|
||||
(id === "fedora" && versionAtLeast(versionId, 41));
|
||||
return {
|
||||
packageFamily !== undefined &&
|
||||
(id === "arch" ||
|
||||
(id === "ubuntu" && versionAtLeast(versionId, 24)) ||
|
||||
(id === "fedora" && versionAtLeast(versionId, 41)));
|
||||
const identity = {
|
||||
id,
|
||||
...(versionId === undefined ? {} : { versionId }),
|
||||
packageFamily,
|
||||
supported,
|
||||
};
|
||||
return supported
|
||||
? { ...identity, packageFamily, supported: true }
|
||||
: { ...identity, packageFamily, supported: false };
|
||||
};
|
||||
|
||||
/** Read and classify the current Linux distribution. */
|
||||
@@ -169,10 +181,7 @@ export const installLinuxHopper = async (
|
||||
if (options.signal?.aborted === true)
|
||||
return { status: "failed", reason: "cancelled" };
|
||||
const distribution = await host.distribution();
|
||||
if (
|
||||
distribution?.supported !== true ||
|
||||
distribution.packageFamily === undefined
|
||||
)
|
||||
if (distribution?.supported !== true)
|
||||
return { status: "failed", reason: "unsupported_host" };
|
||||
let temporary: string | undefined;
|
||||
try {
|
||||
|
||||
@@ -97,7 +97,7 @@ export const planManagedRuntimeCorrelationEvidenceValidated = async (
|
||||
operation_identity: operationIdentity(input, staticEvidence),
|
||||
},
|
||||
"read",
|
||||
{ restartRequired: true },
|
||||
{ remediation: "restart" },
|
||||
);
|
||||
if (!authorized.ok)
|
||||
return err(
|
||||
|
||||
@@ -18,7 +18,10 @@ import {
|
||||
reloadPermissionCeilings,
|
||||
revokePermission,
|
||||
} from "../domain/permissionPolicy.js";
|
||||
import { PermissionRequiredError } from "../domain/errors.js";
|
||||
import {
|
||||
PermissionRequiredError,
|
||||
type PermissionRemediation,
|
||||
} from "../domain/errors.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
|
||||
/** Failure to establish a filesystem object's canonical authorization identity. */
|
||||
@@ -108,8 +111,7 @@ const errorReason = (error: unknown): PermissionPathError["reason"] =>
|
||||
isNotFound(error) ? "not_found" : "io";
|
||||
|
||||
interface PermissionEvaluationOptions {
|
||||
readonly elicitationSupported?: boolean;
|
||||
readonly restartRequired?: boolean;
|
||||
readonly remediation?: PermissionRemediation;
|
||||
}
|
||||
|
||||
interface CanonicalPermissionDecision {
|
||||
@@ -131,16 +133,22 @@ type PermissionAuthorizationResult = Promise<
|
||||
export class PermissionAuthority {
|
||||
private policy: PermissionPolicy;
|
||||
private readonly configuredAuthority: PermissionAuthority | undefined;
|
||||
private readonly outsideCeilingRestartRequired: boolean;
|
||||
private readonly outsideCeilingRemediation: Exclude<
|
||||
PermissionRemediation,
|
||||
"elicit"
|
||||
>;
|
||||
|
||||
constructor(
|
||||
policy: PermissionPolicy,
|
||||
configuredAuthority?: PermissionAuthority,
|
||||
outsideCeilingRestartRequired = false,
|
||||
outsideCeilingRemediation: Exclude<
|
||||
PermissionRemediation,
|
||||
"elicit"
|
||||
> = "configure",
|
||||
) {
|
||||
this.policy = policy;
|
||||
this.configuredAuthority = configuredAuthority;
|
||||
this.outsideCeilingRestartRequired = outsideCeilingRestartRequired;
|
||||
this.outsideCeilingRemediation = outsideCeilingRemediation;
|
||||
}
|
||||
|
||||
/** Create a connection-owned overlay for once and session grants. */
|
||||
@@ -148,7 +156,7 @@ export class PermissionAuthority {
|
||||
return new PermissionAuthority(
|
||||
createPermissionPolicy([]),
|
||||
this.configuredAuthority ?? this,
|
||||
true,
|
||||
"restart",
|
||||
);
|
||||
}
|
||||
|
||||
@@ -273,15 +281,18 @@ export class PermissionAuthority {
|
||||
if (denied.allowed) return ok({ decision: denied, owner: this });
|
||||
const outsideAdministratorCeiling =
|
||||
denied.reason === "outside_administrator_ceiling";
|
||||
const requestedRemediation = options.remediation ?? "configure";
|
||||
const remediation =
|
||||
outsideAdministratorCeiling && requestedRemediation !== "restart"
|
||||
? this.outsideCeilingRemediation
|
||||
: requestedRemediation;
|
||||
return err(
|
||||
new PermissionRequiredError(
|
||||
request,
|
||||
denied.missing,
|
||||
ceilingFor(effective, request.capability),
|
||||
!outsideAdministratorCeiling && (options.elicitationSupported ?? false),
|
||||
options.restartRequired ??
|
||||
(outsideAdministratorCeiling && this.outsideCeilingRestartRequired),
|
||||
),
|
||||
new PermissionRequiredError({
|
||||
requested: request,
|
||||
missing: denied.missing,
|
||||
ceiling: ceilingFor(effective, request.capability),
|
||||
remediation,
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -9,9 +9,11 @@ import type {
|
||||
FilesystemCheckpoint,
|
||||
InteractionEvent,
|
||||
ProcessCapture,
|
||||
UnverifiedProcessCapture,
|
||||
ProcessExecutionPolicy,
|
||||
ProcessPolicyDecision,
|
||||
ProcessSample,
|
||||
ProcessSettlement,
|
||||
ProcessScenario,
|
||||
ProcessCaptureEventJournalEntry,
|
||||
RecordProcessCaptureEvent,
|
||||
@@ -71,25 +73,43 @@ interface CaptureResultOptions {
|
||||
};
|
||||
readonly samples: readonly ProcessSample[];
|
||||
readonly replay: LoopbackReplay;
|
||||
readonly reactiveRun: ProcessCapture["reactive_run"];
|
||||
readonly before: SnapshotResult;
|
||||
readonly after: SnapshotResult;
|
||||
readonly truncated: boolean;
|
||||
readonly scenario: ProcessScenario;
|
||||
readonly rootPid: number;
|
||||
readonly samplingPartial: boolean;
|
||||
readonly renderedFrames: ProcessCapture["rendered_frames"];
|
||||
readonly renderedFrames: UnverifiedProcessCapture["rendered_frames"];
|
||||
readonly interactions: readonly InteractionEvent[];
|
||||
readonly checkpoints: readonly FilesystemCheckpoint[];
|
||||
readonly shimEvents: ProcessCapture["shim_events"];
|
||||
readonly settlement: ProcessCapture["settlement"];
|
||||
readonly manifest: ProcessCapture["manifest"];
|
||||
readonly shimEvents: UnverifiedProcessCapture["shim_events"];
|
||||
readonly settlement: ObservedProcessSettlement;
|
||||
readonly manifest: UnverifiedProcessCapture["manifest"];
|
||||
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
|
||||
}
|
||||
|
||||
/** Settlement observation before process-resource cleanup has completed. */
|
||||
export type ObservedProcessSettlement =
|
||||
| Pick<
|
||||
Extract<ProcessSettlement, { readonly state: "quiesced" }>,
|
||||
"state" | "elapsed_ms"
|
||||
>
|
||||
| Pick<
|
||||
Exclude<ProcessSettlement, { readonly state: "quiesced" }>,
|
||||
"state" | "elapsed_ms"
|
||||
>;
|
||||
|
||||
/** Capture observations that cannot yet claim final cleanup or reactive state. */
|
||||
export type PendingProcessCapture = Omit<
|
||||
UnverifiedProcessCapture,
|
||||
"cleanup" | "reactive_run" | "settlement"
|
||||
> & {
|
||||
readonly settlement: ObservedProcessSettlement;
|
||||
};
|
||||
|
||||
export const buildCaptureResult = (
|
||||
options: CaptureResultOptions,
|
||||
): ProcessCapture => ({
|
||||
): PendingProcessCapture => ({
|
||||
schema_version: 4,
|
||||
manifest: options.manifest,
|
||||
normalization: options.scenario.normalization,
|
||||
@@ -117,7 +137,6 @@ export const buildCaptureResult = (
|
||||
options.scenario,
|
||||
),
|
||||
replay_transitions: options.replay.transitions,
|
||||
reactive_run: options.reactiveRun,
|
||||
event_journal: options.eventJournal,
|
||||
files_before: options.before.files,
|
||||
files_after: options.after.files,
|
||||
@@ -144,10 +163,6 @@ export const buildCaptureResult = (
|
||||
reason: "External network isolation is not enforced by this adapter.",
|
||||
},
|
||||
],
|
||||
cleanup: {
|
||||
owned_process_group: "verified",
|
||||
temporary_root: "removed",
|
||||
},
|
||||
});
|
||||
|
||||
const hashFile = async (path: string): Promise<string> => {
|
||||
@@ -160,7 +175,7 @@ export const createRunManifest = async (
|
||||
scenario: ProcessScenario,
|
||||
startedAt: Date,
|
||||
completedAt: Date,
|
||||
): Promise<ProcessCapture["manifest"]> => {
|
||||
): Promise<UnverifiedProcessCapture["manifest"]> => {
|
||||
const executableSha256 = await hashFile(scenario.executable);
|
||||
const scenarioCommitment = processScenarioCommitment(
|
||||
scenario,
|
||||
@@ -193,7 +208,7 @@ export const observeSettlement = async (
|
||||
processGroupIds: readonly number[],
|
||||
settleMs: number,
|
||||
recordEvent: RecordProcessCaptureEvent = () => undefined,
|
||||
): Promise<Omit<ProcessCapture["settlement"], "cleanup_outcome">> => {
|
||||
): Promise<ObservedProcessSettlement> => {
|
||||
if (process.platform === "win32") {
|
||||
recordEvent("lifecycle", 1);
|
||||
return { state: "unverifiable", elapsed_ms: 0 };
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { processCapturePermissionRequest } from "./ProcessCapturePermission.js";
|
||||
import { parseProcessScenario } from "../domain/processCapture.js";
|
||||
|
||||
describe("process capture permission request", () => {
|
||||
it("projects the complete adapter-neutral authority scope", () => {
|
||||
const scenario = parseProcessScenario({
|
||||
approved: true,
|
||||
executable: "/bin/tool",
|
||||
arguments: ["--probe"],
|
||||
working_directory: "/workspace",
|
||||
environment: { FIXTURE_TOKEN: "secret" },
|
||||
inherit_environment: ["PATH"],
|
||||
filesystem_roots: ["/workspace/output"],
|
||||
network_access: "host",
|
||||
events: [],
|
||||
});
|
||||
|
||||
expect(processCapturePermissionRequest(scenario)).toEqual({
|
||||
capability: "process_capture",
|
||||
roots: ["/workspace", "/workspace/output"],
|
||||
executables: ["/bin/tool"],
|
||||
environment_names: ["FIXTURE_TOKEN", "PATH"],
|
||||
network: "external",
|
||||
mount: false,
|
||||
operation_identity: "capture_process_scenario:/bin/tool",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -18,15 +18,32 @@ export const classifyFilesystemEffects = (
|
||||
.map((path) => {
|
||||
const beforeFile = beforeByPath.get(path) ?? null;
|
||||
const afterFile = afterByPath.get(path) ?? null;
|
||||
const status =
|
||||
beforeFile === null
|
||||
? "created"
|
||||
: afterFile === null
|
||||
? "deleted"
|
||||
: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
|
||||
? "unchanged"
|
||||
: "modified";
|
||||
return { path, status, before: beforeFile, after: afterFile } as const;
|
||||
if (beforeFile === null) {
|
||||
if (afterFile === null)
|
||||
throw new TypeError(`Filesystem effect ${path} has no file state`);
|
||||
return {
|
||||
path,
|
||||
status: "created",
|
||||
before: null,
|
||||
after: afterFile,
|
||||
} as const;
|
||||
}
|
||||
if (afterFile === null)
|
||||
return {
|
||||
path,
|
||||
status: "deleted",
|
||||
before: beforeFile,
|
||||
after: null,
|
||||
} as const;
|
||||
return {
|
||||
path,
|
||||
status:
|
||||
JSON.stringify(beforeFile) === JSON.stringify(afterFile)
|
||||
? "unchanged"
|
||||
: "modified",
|
||||
before: beforeFile,
|
||||
after: afterFile,
|
||||
} as const;
|
||||
});
|
||||
};
|
||||
|
||||
|
||||
@@ -5,7 +5,6 @@ import type {
|
||||
ProcessCapture,
|
||||
ProcessScenario,
|
||||
} from "../domain/processCapture.js";
|
||||
import { parseProcessCapture } from "../domain/processCapture.js";
|
||||
|
||||
/** Provider identity for controlled Process Capture v4 evidence. */
|
||||
export const PROCESS_PROVIDER = {
|
||||
@@ -32,12 +31,11 @@ export const createProcessCaptureEvidence = (
|
||||
scenario: ProcessScenario,
|
||||
capture: ProcessCapture,
|
||||
) => {
|
||||
const validatedCapture = parseProcessCapture(capture);
|
||||
return createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture/v4",
|
||||
operation: "capture_process_scenario",
|
||||
parameters: processEvidenceParameters(scenario),
|
||||
result: jsonValueSchema.parse(validatedCapture),
|
||||
result: jsonValueSchema.parse(capture),
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
environment: {
|
||||
@@ -46,6 +44,6 @@ export const createProcessCaptureEvidence = (
|
||||
architecture: process.arch,
|
||||
isolation: "process",
|
||||
},
|
||||
limitations: validatedCapture.limitations,
|
||||
limitations: capture.limitations,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { IPty } from "@lydell/node-pty";
|
||||
import type {
|
||||
InteractionEvent,
|
||||
ProcessCapture,
|
||||
UnverifiedProcessCapture,
|
||||
ProcessCaptureEventJournalEntry,
|
||||
ProcessExecutionPolicy,
|
||||
ProcessSample,
|
||||
@@ -9,7 +10,7 @@ import type {
|
||||
RecordProcessCaptureEvent,
|
||||
TerminalFrame,
|
||||
} from "../domain/processCapture.js";
|
||||
import { validateProcessCapture } from "../domain/processCapture.js";
|
||||
import { parseProcessCapture } from "../domain/processCapture.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
ProcessCaptureError,
|
||||
@@ -39,6 +40,7 @@ import {
|
||||
prepareProcessCapture,
|
||||
releaseProcessResources,
|
||||
resolveProcessResult,
|
||||
type PendingProcessCapture,
|
||||
} from "./ProcessCaptureLifecycle.js";
|
||||
import { assertNotCancelled } from "./ProcessCaptureAuthority.js";
|
||||
import {
|
||||
@@ -240,7 +242,7 @@ const normalizedShimEvents = (
|
||||
runtime: StartedCaptureRuntime,
|
||||
scenario: ProcessScenario,
|
||||
temporaryRoot: string,
|
||||
): ProcessCapture["shim_events"] =>
|
||||
): UnverifiedProcessCapture["shim_events"] =>
|
||||
runtime.shimReplay.events.map((event) =>
|
||||
normalizeProcessShimEvent(
|
||||
event,
|
||||
@@ -257,7 +259,7 @@ const finishProcessRun = async (options: {
|
||||
readonly temporaryRoot: string;
|
||||
readonly samples: readonly ProcessSample[];
|
||||
readonly stopSampler: () => Promise<{ readonly partial: boolean }>;
|
||||
readonly capture: ProcessCapture | undefined;
|
||||
readonly capture: PendingProcessCapture | undefined;
|
||||
readonly executionFailure: unknown;
|
||||
}): Promise<ProcessCapture> => {
|
||||
options.runtime?.reactive?.unsubscribe();
|
||||
@@ -285,27 +287,35 @@ const finishProcessRun = async (options: {
|
||||
});
|
||||
await options.runtime?.reactive?.coordinator.close();
|
||||
let { capture, executionFailure } = options;
|
||||
if (capture !== undefined) {
|
||||
capture = {
|
||||
let verifiedCapture: ProcessCapture | undefined;
|
||||
if (capture !== undefined && cleanupFailure === undefined) {
|
||||
const settlement: UnverifiedProcessCapture["settlement"] =
|
||||
capture.settlement.state === "quiesced"
|
||||
? { ...capture.settlement, cleanup_outcome: "not_required" }
|
||||
: { ...capture.settlement, cleanup_outcome: "cleaned" };
|
||||
const completedCapture: UnverifiedProcessCapture = {
|
||||
...capture,
|
||||
reactive_run: projectProcessReactiveRun(options.runtime?.reactive),
|
||||
settlement: {
|
||||
...capture.settlement,
|
||||
cleanup_outcome:
|
||||
capture.settlement.state === "quiesced"
|
||||
? "not_required"
|
||||
: cleanupFailure === undefined
|
||||
? "cleaned"
|
||||
: "failed",
|
||||
settlement,
|
||||
cleanup: {
|
||||
owned_process_group: "verified",
|
||||
temporary_root: "removed",
|
||||
},
|
||||
};
|
||||
const issue = validateProcessCapture(capture)[0];
|
||||
if (issue !== undefined)
|
||||
try {
|
||||
verifiedCapture = parseProcessCapture(completedCapture);
|
||||
} catch (cause: unknown) {
|
||||
executionFailure = new ProcessCaptureError(
|
||||
`process capture validation failed: ${issue.path}: ${issue.message}`,
|
||||
`process capture validation failed${cause instanceof Error ? `: ${cause.message}` : ""}`,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
}
|
||||
return resolveProcessResult(capture, executionFailure, cleanupFailure);
|
||||
return resolveProcessResult(
|
||||
verifiedCapture,
|
||||
executionFailure,
|
||||
cleanupFailure,
|
||||
);
|
||||
};
|
||||
|
||||
const completeCapture = async (options: {
|
||||
@@ -322,7 +332,7 @@ const completeCapture = async (options: {
|
||||
readonly initiallyTruncated: boolean;
|
||||
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
|
||||
readonly recordEvent: RecordProcessCaptureEvent;
|
||||
}): Promise<ProcessCapture> => {
|
||||
}): Promise<PendingProcessCapture> => {
|
||||
const { runtime, scenario } = options;
|
||||
runtime.checkpoints.trigger("root_exit");
|
||||
const { reason } = options.exit;
|
||||
@@ -374,7 +384,6 @@ const completeCapture = async (options: {
|
||||
exit: { ...options.exit, reason },
|
||||
samples: options.samples,
|
||||
replay: runtime.replay,
|
||||
reactiveRun: projectProcessReactiveRun(runtime.reactive),
|
||||
before: options.before,
|
||||
after,
|
||||
truncated,
|
||||
@@ -385,7 +394,7 @@ const completeCapture = async (options: {
|
||||
interactions: options.interactions,
|
||||
checkpoints,
|
||||
shimEvents: normalizedShimEvents(runtime, scenario, options.temporaryRoot),
|
||||
settlement: { ...settlement, cleanup_outcome: "not_required" },
|
||||
settlement,
|
||||
manifest,
|
||||
eventJournal: options.eventJournal,
|
||||
});
|
||||
@@ -409,7 +418,7 @@ const runProcessScenario = async (
|
||||
const { entries: eventJournal, recordEvent } = journal;
|
||||
let runtime: StartedCaptureRuntime | undefined;
|
||||
const timers = new Set<NodeJS.Timeout>();
|
||||
let capture: ProcessCapture | undefined;
|
||||
let capture: PendingProcessCapture | undefined;
|
||||
let executionFailure: unknown;
|
||||
let stopSampler = async () => ({ partial: false });
|
||||
const interactions: InteractionEvent[] = [];
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
runPairedProcessExperiment,
|
||||
type ProcessCapturePort,
|
||||
} from "./ProcessPairedExperiment.js";
|
||||
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../contracts/processCaptureExample.js";
|
||||
import {
|
||||
parseProcessCapture,
|
||||
type EnabledProcessExecutionPolicy,
|
||||
} from "../domain/processCapture.js";
|
||||
import {
|
||||
analyzeProcessRepeatability,
|
||||
bindProcessScenario,
|
||||
processPairedExperimentSchema,
|
||||
} from "../domain/processPairedExperiment.js";
|
||||
import { ok } from "../domain/result.js";
|
||||
|
||||
const experiment = () =>
|
||||
processPairedExperimentSchema.parse({
|
||||
approved: true,
|
||||
shared_scenario: {
|
||||
approved: true,
|
||||
executable: "/bin/template",
|
||||
arguments: ["shared"],
|
||||
working_directory: "/tmp",
|
||||
environment: { SHARED: "yes" },
|
||||
},
|
||||
authority: {
|
||||
id: "authority",
|
||||
executable: "/bin/authority",
|
||||
environment: { SIDE: "authority" },
|
||||
},
|
||||
candidate: {
|
||||
id: "candidate",
|
||||
executable: "/bin/candidate",
|
||||
arguments: ["candidate"],
|
||||
environment: { SIDE: "candidate" },
|
||||
},
|
||||
repeat_count: 3,
|
||||
freshness_policy: { max_capture_age_ms: 60_000 },
|
||||
required_dimensions: [
|
||||
"terminal",
|
||||
"interaction",
|
||||
"exit",
|
||||
"filesystem",
|
||||
"protocol",
|
||||
"process",
|
||||
"shim",
|
||||
],
|
||||
});
|
||||
|
||||
const policy: EnabledProcessExecutionPolicy = {
|
||||
status: "enabled",
|
||||
executableRoots: ["/bin"],
|
||||
workingRoots: ["/tmp"],
|
||||
allowedEnvironment: ["SHARED", "SIDE"],
|
||||
networkAccess: "none",
|
||||
};
|
||||
|
||||
const cloneCapture = (
|
||||
capture: ReturnType<typeof parseProcessCapture>,
|
||||
): ReturnType<typeof parseProcessCapture> =>
|
||||
parseProcessCapture(structuredClone(capture));
|
||||
|
||||
describe("paired process experiments", () => {
|
||||
it("binds only declared side inputs onto the shared observation contract", () => {
|
||||
const parsed = experiment();
|
||||
const authority = bindProcessScenario(
|
||||
parsed.shared_scenario,
|
||||
parsed.authority,
|
||||
);
|
||||
const candidate = bindProcessScenario(
|
||||
parsed.shared_scenario,
|
||||
parsed.candidate,
|
||||
);
|
||||
expect(authority).toMatchObject({
|
||||
executable: "/bin/authority",
|
||||
arguments: ["shared"],
|
||||
environment: { SHARED: "yes", SIDE: "authority" },
|
||||
});
|
||||
expect(candidate).toMatchObject({
|
||||
executable: "/bin/candidate",
|
||||
arguments: ["candidate"],
|
||||
environment: { SHARED: "yes", SIDE: "candidate" },
|
||||
});
|
||||
});
|
||||
|
||||
it("runs same-side comparisons first and compares stable sides", async () => {
|
||||
const observedExecutables: string[] = [];
|
||||
const capture = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
|
||||
const capturePort: ProcessCapturePort = {
|
||||
capture: (scenario) => {
|
||||
observedExecutables.push(scenario.executable);
|
||||
return Promise.resolve(ok(cloneCapture(capture)));
|
||||
},
|
||||
};
|
||||
const result = await runPairedProcessExperiment(experiment(), policy, {
|
||||
capturePort,
|
||||
now: () => Date.parse("2026-01-01T00:00:01.000Z"),
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) return;
|
||||
expect(observedExecutables).toEqual([
|
||||
"/bin/authority",
|
||||
"/bin/authority",
|
||||
"/bin/authority",
|
||||
"/bin/candidate",
|
||||
"/bin/candidate",
|
||||
"/bin/candidate",
|
||||
]);
|
||||
expect(result.value.authority_repeatability.stable).toBe(true);
|
||||
expect(result.value.candidate_repeatability.stable).toBe(true);
|
||||
expect(result.value.cross_side?.status).toBe("unchanged");
|
||||
expect(result.value.cross_side_blocked_reason).toBeNull();
|
||||
});
|
||||
|
||||
it("blocks cross-side claims when a candidate has a flaky exit", async () => {
|
||||
const base = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
|
||||
let candidateRun = 0;
|
||||
const capturePort: ProcessCapturePort = {
|
||||
capture: (scenario) => {
|
||||
let capture = cloneCapture(base);
|
||||
if (scenario.executable === "/bin/candidate") {
|
||||
candidateRun += 1;
|
||||
if (candidateRun === 2)
|
||||
capture = parseProcessCapture({
|
||||
...capture,
|
||||
exit: { code: 1, signal: null, reason: "exited" },
|
||||
});
|
||||
}
|
||||
return Promise.resolve(ok(capture));
|
||||
},
|
||||
};
|
||||
const result = await runPairedProcessExperiment(experiment(), policy, {
|
||||
capturePort,
|
||||
now: () => Date.parse("2026-01-01T00:00:01.000Z"),
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) return;
|
||||
expect(result.value.candidate_repeatability).toMatchObject({
|
||||
stable: false,
|
||||
classification: "flaky_exit",
|
||||
unstable_dimensions: ["exit"],
|
||||
});
|
||||
expect(result.value.cross_side).toBeNull();
|
||||
expect(result.value.cross_side_blocked_reason).toMatch(/unstable/u);
|
||||
});
|
||||
});
|
||||
|
||||
describe("paired process experiment comparisons", () => {
|
||||
it("distinguishes normalized timing variance from semantic output drift", () => {
|
||||
const base = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
|
||||
const early = parseProcessCapture({
|
||||
...base,
|
||||
frames: [{ sequence: 0, at_ms: 10, data: "ready" }],
|
||||
});
|
||||
const late = parseProcessCapture({
|
||||
...base,
|
||||
frames: [{ sequence: 0, at_ms: 20, data: "ready" }],
|
||||
});
|
||||
expect(
|
||||
analyzeProcessRepeatability([early, late], ["terminal"]),
|
||||
).toMatchObject({
|
||||
stable: false,
|
||||
classification: "timing_variance",
|
||||
unstable_dimensions: ["terminal"],
|
||||
});
|
||||
const changed = parseProcessCapture({
|
||||
...base,
|
||||
frames: [{ sequence: 0, at_ms: 20, data: "failed" }],
|
||||
});
|
||||
expect(
|
||||
analyzeProcessRepeatability([early, changed], ["terminal"]),
|
||||
).toMatchObject({ classification: "nondeterministic_output" });
|
||||
});
|
||||
|
||||
it("stops before capture when the experiment is cancelled", async () => {
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
const capturePort: ProcessCapturePort = {
|
||||
capture: () => {
|
||||
throw new Error("capture must not start after cancellation");
|
||||
},
|
||||
};
|
||||
|
||||
const result = await runPairedProcessExperiment(experiment(), policy, {
|
||||
capturePort,
|
||||
signal: controller.signal,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "ProcessCaptureError", reason: "cancelled" },
|
||||
});
|
||||
});
|
||||
|
||||
it("blocks full cross-side output when only a subset was repeatable", async () => {
|
||||
const capture = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
|
||||
const capturePort: ProcessCapturePort = {
|
||||
capture: () => Promise.resolve(ok(cloneCapture(capture))),
|
||||
};
|
||||
const subset = processPairedExperimentSchema.parse({
|
||||
...experiment(),
|
||||
required_dimensions: ["exit"],
|
||||
});
|
||||
|
||||
const result = await runPairedProcessExperiment(subset, policy, {
|
||||
capturePort,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
cross_side: null,
|
||||
cross_side_blocked_reason: expect.stringMatching(/every returned/u),
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("paired process experiment freshness", () => {
|
||||
it("compares the newest stable captures under the freshness policy", async () => {
|
||||
const base = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
|
||||
let captureIndex = 0;
|
||||
const capturePort: ProcessCapturePort = {
|
||||
capture: () => {
|
||||
const completedAt =
|
||||
captureIndex === 0
|
||||
? "2026-01-01T00:00:00.000Z"
|
||||
: "2026-01-01T00:00:09.500Z";
|
||||
captureIndex += 1;
|
||||
return Promise.resolve(
|
||||
ok(
|
||||
parseProcessCapture({
|
||||
...structuredClone(base),
|
||||
manifest: {
|
||||
...base.manifest,
|
||||
started_at: completedAt,
|
||||
completed_at: completedAt,
|
||||
},
|
||||
}),
|
||||
),
|
||||
);
|
||||
},
|
||||
};
|
||||
const shortFreshness = processPairedExperimentSchema.parse({
|
||||
...experiment(),
|
||||
freshness_policy: { max_capture_age_ms: 1_000 },
|
||||
});
|
||||
|
||||
const result = await runPairedProcessExperiment(shortFreshness, policy, {
|
||||
capturePort,
|
||||
now: () => Date.parse("2026-01-01T00:00:10.000Z"),
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: { cross_side: { status: "unchanged" } },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -26,8 +26,7 @@ export interface ProcessCapturePort {
|
||||
): Promise<Result<ProcessCapture, ProcessCaptureError>>;
|
||||
}
|
||||
|
||||
/** Repeatability evidence and an optional stable cross-side comparison. */
|
||||
export interface PairedProcessExperimentResult {
|
||||
interface PairedProcessExperimentEvidence {
|
||||
readonly authority_runs: readonly ProcessCapture[];
|
||||
readonly candidate_runs: readonly ProcessCapture[];
|
||||
readonly authority_repeatability: ReturnType<
|
||||
@@ -36,10 +35,21 @@ export interface PairedProcessExperimentResult {
|
||||
readonly candidate_repeatability: ReturnType<
|
||||
typeof analyzeProcessRepeatability
|
||||
>;
|
||||
readonly cross_side: ReturnType<typeof compareProcessCaptures> | null;
|
||||
readonly cross_side_blocked_reason: string | null;
|
||||
}
|
||||
|
||||
/** Repeatability evidence and either a stable comparison or its blocking reason. */
|
||||
export type PairedProcessExperimentResult = PairedProcessExperimentEvidence &
|
||||
(
|
||||
| {
|
||||
readonly cross_side: ReturnType<typeof compareProcessCaptures>;
|
||||
readonly cross_side_blocked_reason: null;
|
||||
}
|
||||
| {
|
||||
readonly cross_side: null;
|
||||
readonly cross_side_blocked_reason: string;
|
||||
}
|
||||
);
|
||||
|
||||
const productionCapturePort: ProcessCapturePort = {
|
||||
capture: captureProcessScenario,
|
||||
};
|
||||
@@ -114,27 +124,29 @@ export const runPairedProcessExperiment = async (
|
||||
);
|
||||
const authorityLatest = authorityRuns.value.at(-1);
|
||||
const candidateLatest = candidateRuns.value.at(-1);
|
||||
const crossSide =
|
||||
const crossSideOutcome =
|
||||
stable &&
|
||||
allDimensionsRequired &&
|
||||
authorityLatest !== undefined &&
|
||||
candidateLatest !== undefined
|
||||
? compareProcessCaptures(authorityLatest, candidateLatest, {
|
||||
maxCaptureAgeMs: experiment.freshness_policy.max_capture_age_ms,
|
||||
...(options.now === undefined ? {} : { now: options.now }),
|
||||
})
|
||||
: null;
|
||||
? {
|
||||
cross_side: compareProcessCaptures(authorityLatest, candidateLatest, {
|
||||
maxCaptureAgeMs: experiment.freshness_policy.max_capture_age_ms,
|
||||
...(options.now === undefined ? {} : { now: options.now }),
|
||||
}),
|
||||
cross_side_blocked_reason: null,
|
||||
}
|
||||
: {
|
||||
cross_side: null,
|
||||
cross_side_blocked_reason: !allDimensionsRequired
|
||||
? "Cross-side comparison is blocked until every returned dimension is required and repeatable."
|
||||
: "Cross-side comparison is blocked because a required same-side dimension is unstable.",
|
||||
};
|
||||
return ok({
|
||||
authority_runs: authorityRuns.value,
|
||||
candidate_runs: candidateRuns.value,
|
||||
authority_repeatability: authorityRepeatability,
|
||||
candidate_repeatability: candidateRepeatability,
|
||||
cross_side: crossSide,
|
||||
cross_side_blocked_reason:
|
||||
crossSide !== null
|
||||
? null
|
||||
: !allDimensionsRequired
|
||||
? "Cross-side comparison is blocked until every returned dimension is required and repeatable."
|
||||
: "Cross-side comparison is blocked because a required same-side dimension is unstable.",
|
||||
...crossSideOutcome,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -0,0 +1,302 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
ProcessReactiveCoordinator,
|
||||
type ProcessReactiveTimerHost,
|
||||
} from "./ProcessReactiveCoordinator.js";
|
||||
import { executeProcessReactiveEffects } from "./ProcessReactiveEffects.js";
|
||||
import { createProcessCaptureJournal } from "./ProcessCaptureJournal.js";
|
||||
import { subscribeProcessReactiveObservations } from "./ProcessReactiveObservations.js";
|
||||
import type {
|
||||
FilesystemCheckpoint,
|
||||
InteractionEvent,
|
||||
TerminalFrame,
|
||||
} from "../domain/processCapture.js";
|
||||
import {
|
||||
processReactiveScenarioSchema,
|
||||
type ProcessReactiveScenario,
|
||||
} from "../domain/processReactiveScenario.js";
|
||||
const terminalTrigger = () => ({
|
||||
kind: "terminal_text" as const,
|
||||
view: "decoded" as const,
|
||||
encoding: "utf8" as const,
|
||||
literal: "Ready",
|
||||
case_sensitive: true,
|
||||
control_sequences: "include" as const,
|
||||
occurrence: 1,
|
||||
since: { kind: "scenario_start" as const },
|
||||
consume: true,
|
||||
});
|
||||
const timerHost = () => {
|
||||
const scheduled: Array<{
|
||||
readonly callback: () => void;
|
||||
readonly delayMs: number;
|
||||
cancelled: boolean;
|
||||
}> = [];
|
||||
const host: ProcessReactiveTimerHost = {
|
||||
schedule: (callback, delayMs) => {
|
||||
const timer = { callback, delayMs, cancelled: false };
|
||||
scheduled.push(timer);
|
||||
return { cancel: () => (timer.cancelled = true) };
|
||||
},
|
||||
};
|
||||
return { host, scheduled };
|
||||
};
|
||||
const twoStateScenario = (): ProcessReactiveScenario =>
|
||||
processReactiveScenarioSchema.parse({
|
||||
version: 1,
|
||||
initial_state: "starting",
|
||||
deadline_ms: 30000,
|
||||
states: [
|
||||
{
|
||||
id: "starting",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "send",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: terminalTrigger(),
|
||||
actions: [{ type: "send_input", data: "go", sensitive: false }],
|
||||
target: { kind: "goto", state: "sent" },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "sent",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "confirm",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: {
|
||||
kind: "event",
|
||||
source: "interaction",
|
||||
exact: { type: "input", data: "go", outcome: "dispatched" },
|
||||
ignore_fields: [
|
||||
"sequence",
|
||||
"scheduled_at_ms",
|
||||
"dispatched_at_ms",
|
||||
],
|
||||
since: { kind: "scenario_start" },
|
||||
consume: true,
|
||||
cardinality: { min: 1, max: 1 },
|
||||
},
|
||||
actions: [],
|
||||
target: { kind: "finish", outcome: "passed" },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
const createHarness = (scenario: ProcessReactiveScenario) => {
|
||||
const journal = createProcessCaptureJournal();
|
||||
const frames: TerminalFrame[] = [];
|
||||
const interactions: InteractionEvent[] = [];
|
||||
const checkpoints: FilesystemCheckpoint[] = [];
|
||||
const terminalCalls: string[] = [];
|
||||
const timers = timerHost();
|
||||
let now = 100;
|
||||
const effectHost = {
|
||||
terminal: () => ({
|
||||
write: (data: string) => terminalCalls.push(`write:${data}`),
|
||||
resize: (columns: number, rows: number) =>
|
||||
terminalCalls.push(`resize:${String(columns)}x${String(rows)}`),
|
||||
closeInput: () => terminalCalls.push("close-input"),
|
||||
kill: (signal: "SIGINT" | "SIGTERM" | "SIGKILL") =>
|
||||
terminalCalls.push(`kill:${signal}`),
|
||||
}),
|
||||
renderer: {
|
||||
resize: (columns: number, rows: number) =>
|
||||
terminalCalls.push(`render:${String(columns)}x${String(rows)}`),
|
||||
},
|
||||
checkpoints: {
|
||||
captureAndRead: async (name: string) => {
|
||||
const index = checkpoints.length;
|
||||
const checkpoint: FilesystemCheckpoint = {
|
||||
name,
|
||||
at_ms: now - 100,
|
||||
files: [],
|
||||
effects: [],
|
||||
truncated: false,
|
||||
};
|
||||
checkpoints.push(checkpoint);
|
||||
journal.record("filesystem_checkpoints", index);
|
||||
return { index, checkpoint };
|
||||
},
|
||||
},
|
||||
interactions,
|
||||
journal,
|
||||
startedAtMs: 100,
|
||||
now: () => now,
|
||||
};
|
||||
const coordinator = new ProcessReactiveCoordinator({
|
||||
scenario,
|
||||
executor: {
|
||||
execute: (actions, signal) =>
|
||||
executeProcessReactiveEffects(effectHost, actions, signal),
|
||||
},
|
||||
timerHost: timers.host,
|
||||
});
|
||||
const unsubscribe = subscribeProcessReactiveObservations({
|
||||
journal,
|
||||
frames,
|
||||
interactions,
|
||||
checkpointAt: (index) => checkpoints[index],
|
||||
processSampleAt: () => undefined,
|
||||
protocolEventAt: () => undefined,
|
||||
shimEventAt: () => undefined,
|
||||
sink: coordinator,
|
||||
});
|
||||
return {
|
||||
coordinator,
|
||||
frames,
|
||||
interactions,
|
||||
checkpoints,
|
||||
journal,
|
||||
terminalCalls,
|
||||
timers: timers.scheduled,
|
||||
setNow: (value: number) => (now = value),
|
||||
unsubscribe,
|
||||
};
|
||||
};
|
||||
describe("process reactive coordinator ordering", () => {
|
||||
it("commits terminal effects before evaluating their journal observations", async () => {
|
||||
const harness = createHarness(twoStateScenario());
|
||||
harness.frames.push({ sequence: 0, at_ms: 0, data: "Ready" });
|
||||
harness.journal.record("frames", 0);
|
||||
await harness.coordinator.drain();
|
||||
expect(harness.coordinator.snapshot).toMatchObject({
|
||||
status: "finished",
|
||||
outcome: "passed",
|
||||
active_state: "sent",
|
||||
});
|
||||
expect(
|
||||
harness.coordinator.snapshot.transitions.map(
|
||||
({ transition_id }) => transition_id,
|
||||
),
|
||||
).toEqual(["send", "confirm"]);
|
||||
expect(harness.terminalCalls).toEqual(["write:go"]);
|
||||
expect(harness.journal.entries).toEqual([
|
||||
{ collection: "frames", index: 0, capture_order: 0 },
|
||||
{ collection: "interaction_events", index: 0, capture_order: 1 },
|
||||
]);
|
||||
expect(harness.interactions[0]).toMatchObject({
|
||||
type: "input",
|
||||
data: "go",
|
||||
outcome: "dispatched",
|
||||
});
|
||||
harness.unsubscribe();
|
||||
await harness.coordinator.close();
|
||||
});
|
||||
it("executes input, resize, root signal, and checkpoint in journal order", async () => {
|
||||
const scenario = processReactiveScenarioSchema.parse({
|
||||
version: 1,
|
||||
initial_state: "ready",
|
||||
deadline_ms: 30000,
|
||||
states: [
|
||||
{
|
||||
id: "ready",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "act",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: terminalTrigger(),
|
||||
actions: [
|
||||
{ type: "send_input", data: "secret", sensitive: true },
|
||||
{ type: "resize", columns: 100, rows: 40 },
|
||||
{ type: "close_stdin" },
|
||||
{
|
||||
type: "send_signal",
|
||||
target: { kind: "root" },
|
||||
signal: "SIGINT",
|
||||
},
|
||||
{ type: "checkpoint", name: "stopped" },
|
||||
],
|
||||
target: { kind: "finish", outcome: "passed" },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
const harness = createHarness(scenario);
|
||||
harness.setNow(125);
|
||||
harness.frames.push({ sequence: 0, at_ms: 20, data: "Ready" });
|
||||
harness.journal.record("frames", 0);
|
||||
await harness.coordinator.drain();
|
||||
expect(harness.terminalCalls).toEqual([
|
||||
"write:secret",
|
||||
"resize:100x40",
|
||||
"render:100x40",
|
||||
"close-input",
|
||||
"kill:SIGINT",
|
||||
]);
|
||||
expect(harness.interactions.map(({ data }) => data)).toEqual([
|
||||
"<redacted-input:6-bytes>",
|
||||
"100x40",
|
||||
"",
|
||||
"SIGINT",
|
||||
]);
|
||||
expect(harness.checkpoints).toHaveLength(1);
|
||||
expect(
|
||||
harness.coordinator.snapshot.transitions[0]?.action_event_ids,
|
||||
).toEqual([
|
||||
"obs.interaction_events.0",
|
||||
"obs.interaction_events.1",
|
||||
"obs.interaction_events.2",
|
||||
"obs.interaction_events.3",
|
||||
"obs.filesystem_checkpoints.0",
|
||||
]);
|
||||
await harness.coordinator.close();
|
||||
});
|
||||
it("ignores a stale state timer after a transition", async () => {
|
||||
const base = twoStateScenario();
|
||||
const first = base.states[0];
|
||||
const second = base.states[1];
|
||||
if (first === undefined || second === undefined)
|
||||
throw new Error("two-state fixture is incomplete");
|
||||
const scenario = processReactiveScenarioSchema.parse({
|
||||
...base,
|
||||
states: [
|
||||
{
|
||||
...first,
|
||||
on: first.on.map((transition) => ({
|
||||
...transition,
|
||||
actions: [],
|
||||
})),
|
||||
},
|
||||
{
|
||||
...second,
|
||||
on: second.on.map((transition) => ({
|
||||
...transition,
|
||||
when: { ...terminalTrigger(), literal: "Later" },
|
||||
})),
|
||||
},
|
||||
],
|
||||
});
|
||||
const harness = createHarness(scenario);
|
||||
const oldStateTimer = harness.timers[1];
|
||||
expect(oldStateTimer?.delayMs).toBe(5000);
|
||||
harness.frames.push({ sequence: 0, at_ms: 0, data: "Ready" });
|
||||
harness.journal.record("frames", 0);
|
||||
await harness.coordinator.drain();
|
||||
expect(oldStateTimer?.cancelled).toBe(true);
|
||||
oldStateTimer?.callback();
|
||||
await harness.coordinator.drain();
|
||||
expect(harness.coordinator.snapshot).toMatchObject({
|
||||
status: "running",
|
||||
active_state: "sent",
|
||||
outcome: null,
|
||||
});
|
||||
const currentStateTimer = harness.timers[2];
|
||||
currentStateTimer?.callback();
|
||||
await harness.coordinator.drain();
|
||||
expect(harness.coordinator.snapshot.outcome).toBe("predicate_timeout");
|
||||
await harness.coordinator.close();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,229 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
ProcessReactiveCoordinator,
|
||||
type ProcessReactiveTimerHost,
|
||||
} from "./ProcessReactiveCoordinator.js";
|
||||
import { unsupportedProcessReactiveFeatures } from "./ProcessReactiveEffects.js";
|
||||
import { createProcessObservation } from "../domain/processObservation.js";
|
||||
import type { ProcessReactiveEffectResult } from "../domain/processReactiveRuntime.js";
|
||||
import {
|
||||
processReactiveScenarioSchema,
|
||||
type ProcessReactiveScenario,
|
||||
} from "../domain/processReactiveScenario.js";
|
||||
const terminalTrigger = () => ({
|
||||
kind: "terminal_text" as const,
|
||||
view: "decoded" as const,
|
||||
encoding: "utf8" as const,
|
||||
literal: "Ready",
|
||||
case_sensitive: true,
|
||||
control_sequences: "include" as const,
|
||||
occurrence: 1,
|
||||
since: { kind: "scenario_start" as const },
|
||||
consume: true,
|
||||
});
|
||||
const timerHost = () => {
|
||||
const scheduled: Array<{
|
||||
readonly callback: () => void;
|
||||
readonly delayMs: number;
|
||||
cancelled: boolean;
|
||||
}> = [];
|
||||
const host: ProcessReactiveTimerHost = {
|
||||
schedule: (callback, delayMs) => {
|
||||
const timer = { callback, delayMs, cancelled: false };
|
||||
scheduled.push(timer);
|
||||
return { cancel: () => (timer.cancelled = true) };
|
||||
},
|
||||
};
|
||||
return { host, scheduled };
|
||||
};
|
||||
const twoStateScenario = (): ProcessReactiveScenario =>
|
||||
processReactiveScenarioSchema.parse({
|
||||
version: 1,
|
||||
initial_state: "starting",
|
||||
deadline_ms: 30000,
|
||||
states: [
|
||||
{
|
||||
id: "starting",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "send",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: terminalTrigger(),
|
||||
actions: [{ type: "send_input", data: "go", sensitive: false }],
|
||||
target: { kind: "goto", state: "sent" },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "sent",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "confirm",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: {
|
||||
kind: "event",
|
||||
source: "interaction",
|
||||
exact: { type: "input", data: "go", outcome: "dispatched" },
|
||||
ignore_fields: [
|
||||
"sequence",
|
||||
"scheduled_at_ms",
|
||||
"dispatched_at_ms",
|
||||
],
|
||||
since: { kind: "scenario_start" },
|
||||
consume: true,
|
||||
cardinality: { min: 1, max: 1 },
|
||||
},
|
||||
actions: [],
|
||||
target: { kind: "finish", outcome: "passed" },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
describe("process reactive coordinator failures", () => {
|
||||
it("preflights signal selectors the host cannot execute", () => {
|
||||
const input = twoStateScenario();
|
||||
const first = input.states[0];
|
||||
const second = input.states[1];
|
||||
const transition = first?.on[0];
|
||||
if (first === undefined || second === undefined || transition === undefined)
|
||||
throw new Error("two-state fixture is incomplete");
|
||||
const scenario = processReactiveScenarioSchema.parse({
|
||||
...input,
|
||||
states: [
|
||||
{
|
||||
...first,
|
||||
on: [
|
||||
{
|
||||
...transition,
|
||||
actions: [
|
||||
{
|
||||
type: "send_signal",
|
||||
target: { kind: "process_group" },
|
||||
signal: "SIGTERM",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
second,
|
||||
],
|
||||
});
|
||||
expect(unsupportedProcessReactiveFeatures(scenario)).toEqual([
|
||||
"send:target:process_group",
|
||||
]);
|
||||
});
|
||||
it("orders delayed effect observations before later producer records", async () => {
|
||||
const timers = timerHost();
|
||||
let executions = 0;
|
||||
let resolveEffects:
|
||||
| ((results: readonly ProcessReactiveEffectResult[]) => void)
|
||||
| undefined;
|
||||
const effects = new Promise<readonly ProcessReactiveEffectResult[]>(
|
||||
(resolve) => (resolveEffects = resolve),
|
||||
);
|
||||
const coordinator = new ProcessReactiveCoordinator({
|
||||
scenario: twoStateScenario(),
|
||||
executor: {
|
||||
execute: () => {
|
||||
executions += 1;
|
||||
return executions === 1 ? effects : Promise.resolve([]);
|
||||
},
|
||||
},
|
||||
timerHost: timers.host,
|
||||
});
|
||||
coordinator.enqueue({
|
||||
kind: "observation",
|
||||
observation: createProcessObservation({
|
||||
source: "terminal_raw",
|
||||
source_sequence: 0,
|
||||
captured_at_ms: 0,
|
||||
subject_id: null,
|
||||
location: { collection: "frames", index: 0, capture_order: 0 },
|
||||
payload: { sequence: 0, at_ms: 0, data: "Ready" },
|
||||
}),
|
||||
});
|
||||
await Promise.resolve();
|
||||
coordinator.enqueue({
|
||||
kind: "observation",
|
||||
observation: createProcessObservation({
|
||||
source: "terminal_raw",
|
||||
source_sequence: 1,
|
||||
captured_at_ms: 2,
|
||||
subject_id: null,
|
||||
location: { collection: "frames", index: 1, capture_order: 2 },
|
||||
payload: { sequence: 1, at_ms: 2, data: "later" },
|
||||
}),
|
||||
});
|
||||
if (resolveEffects === undefined)
|
||||
throw new Error("effect executor did not start");
|
||||
resolveEffects([
|
||||
{
|
||||
status: "succeeded",
|
||||
observation: createProcessObservation({
|
||||
source: "interaction",
|
||||
source_sequence: 0,
|
||||
captured_at_ms: 1,
|
||||
subject_id: null,
|
||||
location: {
|
||||
collection: "interaction_events",
|
||||
index: 0,
|
||||
capture_order: 1,
|
||||
},
|
||||
payload: {
|
||||
sequence: 0,
|
||||
scheduled_at_ms: 1,
|
||||
dispatched_at_ms: 1,
|
||||
type: "input",
|
||||
data: "go",
|
||||
outcome: "dispatched",
|
||||
},
|
||||
}),
|
||||
},
|
||||
]);
|
||||
await coordinator.drain();
|
||||
expect(coordinator.snapshot).toMatchObject({
|
||||
status: "finished",
|
||||
outcome: "passed",
|
||||
});
|
||||
expect(
|
||||
coordinator.snapshot.transitions.map(
|
||||
({ transition_id }) => transition_id,
|
||||
),
|
||||
).toEqual(["send", "confirm"]);
|
||||
await coordinator.close();
|
||||
});
|
||||
it("cancels timers and rejects later work after an executor failure", async () => {
|
||||
const timers = timerHost();
|
||||
let calls = 0;
|
||||
const coordinator = new ProcessReactiveCoordinator({
|
||||
scenario: twoStateScenario(),
|
||||
executor: {
|
||||
execute: () => {
|
||||
calls += 1;
|
||||
throw new Error("executor failed");
|
||||
},
|
||||
},
|
||||
timerHost: timers.host,
|
||||
});
|
||||
const ready = createProcessObservation({
|
||||
source: "terminal_raw",
|
||||
source_sequence: 0,
|
||||
captured_at_ms: 0,
|
||||
subject_id: null,
|
||||
location: { collection: "frames", index: 0, capture_order: 0 },
|
||||
payload: { sequence: 0, at_ms: 0, data: "Ready" },
|
||||
});
|
||||
coordinator.enqueue({ kind: "observation", observation: ready });
|
||||
await expect(coordinator.drain()).rejects.toThrow("executor failed");
|
||||
coordinator.enqueue({ kind: "observation", observation: ready });
|
||||
expect(calls).toBe(1);
|
||||
expect(timers.scheduled.every(({ cancelled }) => cancelled)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,131 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
ProcessReactiveCoordinator,
|
||||
type ProcessReactiveTimerHost,
|
||||
} from "./ProcessReactiveCoordinator.js";
|
||||
import { createProcessObservation } from "../domain/processObservation.js";
|
||||
import {
|
||||
processReactiveScenarioSchema,
|
||||
type ProcessReactiveScenario,
|
||||
} from "../domain/processReactiveScenario.js";
|
||||
const terminalTrigger = () => ({
|
||||
kind: "terminal_text" as const,
|
||||
view: "decoded" as const,
|
||||
encoding: "utf8" as const,
|
||||
literal: "Ready",
|
||||
case_sensitive: true,
|
||||
control_sequences: "include" as const,
|
||||
occurrence: 1,
|
||||
since: { kind: "scenario_start" as const },
|
||||
consume: true,
|
||||
});
|
||||
const timerHost = () => {
|
||||
const scheduled: Array<{
|
||||
readonly callback: () => void;
|
||||
readonly delayMs: number;
|
||||
cancelled: boolean;
|
||||
}> = [];
|
||||
const host: ProcessReactiveTimerHost = {
|
||||
schedule: (callback, delayMs) => {
|
||||
const timer = { callback, delayMs, cancelled: false };
|
||||
scheduled.push(timer);
|
||||
return { cancel: () => (timer.cancelled = true) };
|
||||
},
|
||||
};
|
||||
return { host, scheduled };
|
||||
};
|
||||
const twoStateScenario = (): ProcessReactiveScenario =>
|
||||
processReactiveScenarioSchema.parse({
|
||||
version: 1,
|
||||
initial_state: "starting",
|
||||
deadline_ms: 30000,
|
||||
states: [
|
||||
{
|
||||
id: "starting",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "send",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: terminalTrigger(),
|
||||
actions: [{ type: "send_input", data: "go", sensitive: false }],
|
||||
target: { kind: "goto", state: "sent" },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "sent",
|
||||
max_visits: 1,
|
||||
deadline_ms: 5000,
|
||||
on: [
|
||||
{
|
||||
id: "confirm",
|
||||
priority: 1,
|
||||
max_uses: 1,
|
||||
when: {
|
||||
kind: "event",
|
||||
source: "interaction",
|
||||
exact: { type: "input", data: "go", outcome: "dispatched" },
|
||||
ignore_fields: [
|
||||
"sequence",
|
||||
"scheduled_at_ms",
|
||||
"dispatched_at_ms",
|
||||
],
|
||||
since: { kind: "scenario_start" },
|
||||
consume: true,
|
||||
cardinality: { min: 1, max: 1 },
|
||||
},
|
||||
actions: [],
|
||||
target: { kind: "finish", outcome: "passed" },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
describe("process reactive coordinator failures", () => {
|
||||
it("aborts an in-flight effect before committing a state deadline", async () => {
|
||||
const timers = timerHost();
|
||||
let effectAborted = false;
|
||||
const coordinator = new ProcessReactiveCoordinator({
|
||||
scenario: twoStateScenario(),
|
||||
executor: {
|
||||
execute: (_actions, signal) =>
|
||||
new Promise((resolve) => {
|
||||
signal.addEventListener(
|
||||
"abort",
|
||||
() => {
|
||||
effectAborted = true;
|
||||
resolve([]);
|
||||
},
|
||||
{ once: true },
|
||||
);
|
||||
}),
|
||||
},
|
||||
timerHost: timers.host,
|
||||
});
|
||||
coordinator.enqueue({
|
||||
kind: "observation",
|
||||
observation: createProcessObservation({
|
||||
source: "terminal_raw",
|
||||
source_sequence: 0,
|
||||
captured_at_ms: 0,
|
||||
subject_id: null,
|
||||
location: { collection: "frames", index: 0, capture_order: 0 },
|
||||
payload: { sequence: 0, at_ms: 0, data: "Ready" },
|
||||
}),
|
||||
});
|
||||
await Promise.resolve();
|
||||
timers.scheduled[1]?.callback();
|
||||
await coordinator.drain();
|
||||
expect(effectAborted).toBe(true);
|
||||
expect(coordinator.snapshot).toMatchObject({
|
||||
status: "finished",
|
||||
outcome: "predicate_timeout",
|
||||
active_state: "starting",
|
||||
transitions: [],
|
||||
});
|
||||
await coordinator.close();
|
||||
});
|
||||
});
|
||||
@@ -167,13 +167,17 @@ export const startProcessReactiveHarness = (options: {
|
||||
/** Project internal reducer state into the stable Process Capture shape. */
|
||||
export const projectProcessReactiveRun = (
|
||||
harness: ProcessReactiveHarness | undefined,
|
||||
): ProcessCapture["reactive_run"] =>
|
||||
harness === undefined
|
||||
? null
|
||||
: {
|
||||
status: harness.coordinator.snapshot.status,
|
||||
outcome: harness.coordinator.snapshot.outcome,
|
||||
active_state: harness.coordinator.snapshot.active_state,
|
||||
transitions: harness.coordinator.snapshot.transitions,
|
||||
controls: harness.controls,
|
||||
};
|
||||
): ProcessCapture["reactive_run"] => {
|
||||
if (harness === undefined) return null;
|
||||
const snapshot = harness.coordinator.snapshot;
|
||||
const completion =
|
||||
snapshot.status === "running"
|
||||
? { status: snapshot.status, outcome: null }
|
||||
: { status: snapshot.status, outcome: snapshot.outcome };
|
||||
return {
|
||||
...completion,
|
||||
active_state: snapshot.active_state,
|
||||
transitions: snapshot.transitions,
|
||||
controls: harness.controls,
|
||||
};
|
||||
};
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { createProgressReporter } from "./ProgressReporter.js";
|
||||
|
||||
describe("progress reporter", () => {
|
||||
it("preserves monotonic order, rate bounds intermediate updates, and always emits terminal state", async () => {
|
||||
let now = 0;
|
||||
const observed: unknown[] = [];
|
||||
const reporter = createProgressReporter(
|
||||
(update) => {
|
||||
observed.push(update);
|
||||
return Promise.resolve();
|
||||
},
|
||||
{ minimumIntervalMs: 100, now: () => now },
|
||||
);
|
||||
await reporter.report({
|
||||
phase: "scan",
|
||||
completed: 0,
|
||||
total: 3,
|
||||
message: "start",
|
||||
});
|
||||
now = 10;
|
||||
await reporter.report({
|
||||
phase: "scan",
|
||||
completed: 1,
|
||||
total: 3,
|
||||
message: "one",
|
||||
});
|
||||
now = 20;
|
||||
await reporter.report({
|
||||
phase: "scan",
|
||||
completed: 3,
|
||||
total: 3,
|
||||
message: "done",
|
||||
terminal: true,
|
||||
});
|
||||
|
||||
expect(observed).toEqual([
|
||||
expect.objectContaining({ sequence: 1, completed: 0 }),
|
||||
expect.objectContaining({ sequence: 2, completed: 3, terminal: true }),
|
||||
]);
|
||||
await expect(
|
||||
reporter.report({
|
||||
phase: "scan",
|
||||
completed: 2,
|
||||
total: 3,
|
||||
message: "back",
|
||||
}),
|
||||
).rejects.toThrow(/backwards/u);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,350 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
|
||||
import {
|
||||
buildReconstructionObligationLedgerEvidenceValidated,
|
||||
resolveReconstructionObligationLedgerRequest,
|
||||
} from "./ReconstructionObligationLedgerService.js";
|
||||
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../contracts/processCaptureExample.js";
|
||||
import { createEvidence, type Evidence } from "../domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { processCaptureSchema } from "../domain/processCapture.js";
|
||||
import {
|
||||
reconstructionObligationLedgerPageSchema,
|
||||
type ReconstructionObligationLedgerInput,
|
||||
type ReconstructionObligationLedgerPage,
|
||||
type ReviewedReconstructionObligation,
|
||||
} from "../domain/reconstructionObligationLedgerSchemas.js";
|
||||
|
||||
const proofEvidence = (id: string) =>
|
||||
createEvidence(
|
||||
undefined,
|
||||
{ id: `fixture-${id}`, name: "Fixture verifier", version: "1" },
|
||||
{
|
||||
predicateType: "rea.fixture-verification/v1",
|
||||
operation: "run_fixture_verifier",
|
||||
parameters: { id },
|
||||
result: { passed: true },
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
},
|
||||
);
|
||||
|
||||
const processEvidence = () =>
|
||||
createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture/v4",
|
||||
operation: "capture_process_scenario",
|
||||
parameters: {},
|
||||
result: jsonValueSchema.parse(
|
||||
processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE),
|
||||
),
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
});
|
||||
|
||||
const boundProofEvidence = (
|
||||
id: string,
|
||||
result: {
|
||||
readonly obligation_ids: readonly string[];
|
||||
readonly fixture_ids: readonly string[];
|
||||
readonly case_kinds: readonly string[];
|
||||
readonly verifier_ids: readonly string[];
|
||||
readonly claim_ids: readonly string[];
|
||||
},
|
||||
authority: "shipped-artifact" | "controlled-replay" = "controlled-replay",
|
||||
) =>
|
||||
createEvidence(
|
||||
undefined,
|
||||
{ id: `proof-${id}`, name: "Reconstruction proof", version: "1" },
|
||||
{
|
||||
predicateType: "rea.reconstruction-proof/v1",
|
||||
operation: "verify_reconstruction_obligations",
|
||||
parameters: {},
|
||||
result: {
|
||||
passed: true,
|
||||
obligation_ids: [...result.obligation_ids],
|
||||
fixture_ids: [...result.fixture_ids],
|
||||
case_kinds: [...result.case_kinds],
|
||||
verifier_ids: [...result.verifier_ids],
|
||||
claim_ids: [...result.claim_ids],
|
||||
},
|
||||
confidence: "observed",
|
||||
authority,
|
||||
},
|
||||
);
|
||||
|
||||
const request = (
|
||||
records: readonly Evidence[],
|
||||
overrides: Partial<ReconstructionObligationLedgerInput> = {},
|
||||
): ReconstructionObligationLedgerInput => ({
|
||||
evidence_bundle: createEvidenceBundle(records),
|
||||
reviewed_obligations: [],
|
||||
manifest: { schema_version: 1, bindings: [], contradictions: [] },
|
||||
limits: { max_obligations: 100 },
|
||||
page: { offset: 0, limit: 50 },
|
||||
...overrides,
|
||||
});
|
||||
|
||||
const build = (
|
||||
input: ReconstructionObligationLedgerInput,
|
||||
): ReconstructionObligationLedgerPage => {
|
||||
const parsed = resolveReconstructionObligationLedgerRequest(input);
|
||||
if (!parsed.ok) throw parsed.error;
|
||||
const result = buildReconstructionObligationLedgerEvidenceValidated(
|
||||
parsed.value,
|
||||
);
|
||||
if (!result.ok) throw result.error;
|
||||
return reconstructionObligationLedgerPageSchema.parse(
|
||||
result.value.normalized_result,
|
||||
);
|
||||
};
|
||||
|
||||
const originalCases = (
|
||||
obligation: ReconstructionObligationLedgerPage["obligations"][number],
|
||||
evidenceId: string,
|
||||
) =>
|
||||
obligation.required_case_kinds.map((caseKind) => ({
|
||||
kind: caseKind,
|
||||
evidence_id: evidenceId,
|
||||
location: `/normalized_result/cases/${caseKind}`,
|
||||
}));
|
||||
|
||||
describe("reconstruction obligation ledger", () => {
|
||||
it("does not authenticate packaged-process proof with generic replay evidence", () => {
|
||||
const capture = processEvidence();
|
||||
const proof = proofEvidence("generic-packaged");
|
||||
const initial = build(request([capture, proof]));
|
||||
const obligation = initial.obligations[0];
|
||||
if (obligation === undefined)
|
||||
throw new Error("Expected process obligation");
|
||||
const result = build(
|
||||
request([capture, proof], {
|
||||
manifest: {
|
||||
schema_version: 1,
|
||||
bindings: [
|
||||
{
|
||||
obligation_id: obligation.obligation_id,
|
||||
owner: {
|
||||
module_path: "src/processOwner.ts",
|
||||
symbol: "runProcess",
|
||||
owner_sha256: "5".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: originalCases(obligation, capture.evidence_id),
|
||||
fixtures: obligation.required_case_kinds.map((caseKind) => ({
|
||||
fixture_id: `packaged.${caseKind}`,
|
||||
case_kind: caseKind,
|
||||
authority: "packaged-process",
|
||||
evidence_ids: [proof.evidence_id],
|
||||
})),
|
||||
verifier: {
|
||||
verifier_id: "verifier.packaged",
|
||||
claim_id: "claim.process",
|
||||
command: "npm run verify:package -- process",
|
||||
authority: "packaged-process",
|
||||
status: "pass",
|
||||
result_evidence_id: proof.evidence_id,
|
||||
enumerated_obligation_ids: [obligation.obligation_id],
|
||||
nondeterminism: {
|
||||
mode: "partial-order",
|
||||
specification: "Fixture scheduling is partially ordered.",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
contradictions: [],
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
expect(result.obligations[0]?.diagnostics.map(({ code }) => code)).toEqual(
|
||||
expect.arrayContaining([
|
||||
"weak-fixture-authority",
|
||||
"weak-verifier-authority",
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
it("propagates an open dependency through the full obligation chain", () => {
|
||||
const ids = ["obl.chain.a", "obl.chain.b", "obl.chain.c"] as const;
|
||||
const evidence = boundProofEvidence(
|
||||
"fixture-chain",
|
||||
{
|
||||
obligation_ids: ids,
|
||||
fixture_ids: ids.map((id) => `fixture.${id}`),
|
||||
case_kinds: ["positive"],
|
||||
verifier_ids: ids.map((id) => `verifier.${id}`),
|
||||
claim_ids: ids.map((id) => `claim.${id}`),
|
||||
},
|
||||
"shipped-artifact",
|
||||
);
|
||||
const reviewed = ids.map((id, index) => ({
|
||||
...reviewedObligation(id, evidence.evidence_id),
|
||||
dependency_obligation_ids:
|
||||
index === 0 ? [ids[1]] : index === 1 ? [ids[2]] : ["obl.chain.missing"],
|
||||
}));
|
||||
const bindings = reviewed.map((obligation) => ({
|
||||
obligation_id: obligation.obligation_id,
|
||||
owner: {
|
||||
module_path: `src/${obligation.obligation_id}.ts`,
|
||||
symbol: "verify",
|
||||
owner_sha256: "6".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: [
|
||||
{
|
||||
kind: "positive" as const,
|
||||
evidence_id: evidence.evidence_id,
|
||||
location: "/fixture/positive",
|
||||
},
|
||||
],
|
||||
fixtures: [
|
||||
{
|
||||
fixture_id: `fixture.${obligation.obligation_id}`,
|
||||
case_kind: "positive" as const,
|
||||
authority: "unit" as const,
|
||||
evidence_ids: [evidence.evidence_id],
|
||||
},
|
||||
],
|
||||
verifier: {
|
||||
verifier_id: `verifier.${obligation.obligation_id}`,
|
||||
claim_id: `claim.${obligation.obligation_id}`,
|
||||
command: "npm test -- fixture-chain",
|
||||
authority: "unit" as const,
|
||||
status: "pass" as const,
|
||||
result_evidence_id: evidence.evidence_id,
|
||||
enumerated_obligation_ids: [obligation.obligation_id],
|
||||
nondeterminism: {
|
||||
mode: "total-order" as const,
|
||||
specification: "Fixture execution is ordered.",
|
||||
},
|
||||
},
|
||||
}));
|
||||
const result = build(
|
||||
request([evidence], {
|
||||
reviewed_obligations: reviewed,
|
||||
manifest: { schema_version: 1, bindings, contradictions: [] },
|
||||
}),
|
||||
);
|
||||
|
||||
expect(result.obligations.map(({ status }) => status)).toEqual([
|
||||
"blocked",
|
||||
"blocked",
|
||||
"blocked",
|
||||
]);
|
||||
expect(
|
||||
result.obligations.map(({ diagnostics }) =>
|
||||
diagnostics.map(({ code }) => code),
|
||||
),
|
||||
).toEqual([
|
||||
["dependency-open"],
|
||||
["dependency-open"],
|
||||
["dependency-missing"],
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("reconstruction obligation ledger fail-closed behavior", () => {
|
||||
it("fails closed on parser gaps, ambiguous ownership, and contradiction", () => {
|
||||
const original = createEvidence(
|
||||
undefined,
|
||||
{ id: "external", name: "External protocol observer", version: "1" },
|
||||
{
|
||||
predicateType: "rea.protocol-observation/v1",
|
||||
operation: "observe_protocol",
|
||||
parameters: {},
|
||||
result: { status: 200 },
|
||||
confidence: "observed",
|
||||
authority: "external-service",
|
||||
},
|
||||
);
|
||||
const proof = proofEvidence("protocol");
|
||||
const reviewed: ReviewedReconstructionObligation = {
|
||||
...reviewedObligation("obl.protocol", original.evidence_id),
|
||||
application_layer: "protocol" as const,
|
||||
family: "json-rpc",
|
||||
required_original_authority: "external" as const,
|
||||
required_fixture_authority: "protocol" as const,
|
||||
required_verifier_authority: "protocol" as const,
|
||||
requires_parser_type: true,
|
||||
required_case_kinds: ["positive", "negative", "malformed"],
|
||||
};
|
||||
const binding = {
|
||||
obligation_id: reviewed.obligation_id,
|
||||
owner: {
|
||||
module_path: "src/protocol.ts",
|
||||
symbol: "handleRequest",
|
||||
owner_sha256: "3".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: reviewed.required_case_kinds.map((caseKind) => ({
|
||||
kind: caseKind,
|
||||
evidence_id: original.evidence_id,
|
||||
location: `/protocol/${caseKind}`,
|
||||
})),
|
||||
fixtures: [
|
||||
{
|
||||
fixture_id: "fixture.positive",
|
||||
case_kind: "positive" as const,
|
||||
authority: "unit" as const,
|
||||
evidence_ids: [proof.evidence_id],
|
||||
},
|
||||
],
|
||||
verifier: null,
|
||||
};
|
||||
const result = build(
|
||||
request([original, proof], {
|
||||
reviewed_obligations: [reviewed],
|
||||
manifest: {
|
||||
schema_version: 1,
|
||||
bindings: [binding, binding],
|
||||
contradictions: [
|
||||
{
|
||||
obligation_id: reviewed.obligation_id,
|
||||
evidence_ids: [original.evidence_id, proof.evidence_id],
|
||||
},
|
||||
],
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
expect(result.status).toBe("failed");
|
||||
expect(result.obligations[0]?.status).toBe("contradicted");
|
||||
expect(result.obligations[0]?.diagnostics.map(({ code }) => code)).toEqual(
|
||||
expect.arrayContaining(["ambiguous-owner", "contradiction"]),
|
||||
);
|
||||
expect(result.reports.contradicted_obligation_ids).toEqual([
|
||||
reviewed.obligation_id,
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
const reviewedObligation = (
|
||||
obligationId: string,
|
||||
evidenceId: string,
|
||||
): ReviewedReconstructionObligation => ({
|
||||
obligation_id: obligationId,
|
||||
obligation_version: 1,
|
||||
title: `Reviewed obligation ${obligationId}`,
|
||||
application_layer: "other",
|
||||
family: "reviewed",
|
||||
target: {
|
||||
artifact_sha256: null,
|
||||
application_node_id: null,
|
||||
semantic_node_id: null,
|
||||
location: `/reviewed/${obligationId}`,
|
||||
},
|
||||
required: true,
|
||||
required_case_kinds: ["positive"],
|
||||
required_original_authority: "static",
|
||||
required_fixture_authority: "unit",
|
||||
required_verifier_authority: "unit",
|
||||
requires_parser_type: false,
|
||||
dependency_obligation_ids: [],
|
||||
residual_unknown_ids: [],
|
||||
unavailable_authority: [],
|
||||
required_next_evidence: ["Bind an owner and verifier."],
|
||||
disposition: "active",
|
||||
review_evidence_ids: [evidenceId],
|
||||
});
|
||||
@@ -0,0 +1,383 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
|
||||
import {
|
||||
buildReconstructionObligationLedgerEvidenceValidated,
|
||||
resolveReconstructionObligationLedgerRequest,
|
||||
} from "./ReconstructionObligationLedgerService.js";
|
||||
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../contracts/processCaptureExample.js";
|
||||
import { createEvidence, type Evidence } from "../domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { processCaptureSchema } from "../domain/processCapture.js";
|
||||
import {
|
||||
reconstructionObligationLedgerPageSchema,
|
||||
serializeReconstructionObligationLedger,
|
||||
type ReconstructionObligationLedgerInput,
|
||||
type ReconstructionObligationLedgerPage,
|
||||
type ReviewedReconstructionObligation,
|
||||
} from "../domain/reconstructionObligationLedgerSchemas.js";
|
||||
|
||||
const proofEvidence = (id: string) =>
|
||||
createEvidence(
|
||||
undefined,
|
||||
{ id: `fixture-${id}`, name: "Fixture verifier", version: "1" },
|
||||
{
|
||||
predicateType: "rea.fixture-verification/v1",
|
||||
operation: "run_fixture_verifier",
|
||||
parameters: { id },
|
||||
result: { passed: true },
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
},
|
||||
);
|
||||
|
||||
const processEvidence = () =>
|
||||
createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture/v4",
|
||||
operation: "capture_process_scenario",
|
||||
parameters: {},
|
||||
result: jsonValueSchema.parse(
|
||||
processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE),
|
||||
),
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
});
|
||||
|
||||
const boundProofEvidence = (
|
||||
id: string,
|
||||
result: {
|
||||
readonly obligation_ids: readonly string[];
|
||||
readonly fixture_ids: readonly string[];
|
||||
readonly case_kinds: readonly string[];
|
||||
readonly verifier_ids: readonly string[];
|
||||
readonly claim_ids: readonly string[];
|
||||
},
|
||||
authority: "shipped-artifact" | "controlled-replay" = "controlled-replay",
|
||||
) =>
|
||||
createEvidence(
|
||||
undefined,
|
||||
{ id: `proof-${id}`, name: "Reconstruction proof", version: "1" },
|
||||
{
|
||||
predicateType: "rea.reconstruction-proof/v1",
|
||||
operation: "verify_reconstruction_obligations",
|
||||
parameters: {},
|
||||
result: {
|
||||
passed: true,
|
||||
obligation_ids: [...result.obligation_ids],
|
||||
fixture_ids: [...result.fixture_ids],
|
||||
case_kinds: [...result.case_kinds],
|
||||
verifier_ids: [...result.verifier_ids],
|
||||
claim_ids: [...result.claim_ids],
|
||||
},
|
||||
confidence: "observed",
|
||||
authority,
|
||||
},
|
||||
);
|
||||
|
||||
const request = (
|
||||
records: readonly Evidence[],
|
||||
overrides: Partial<ReconstructionObligationLedgerInput> = {},
|
||||
): ReconstructionObligationLedgerInput => ({
|
||||
evidence_bundle: createEvidenceBundle(records),
|
||||
reviewed_obligations: [],
|
||||
manifest: { schema_version: 1, bindings: [], contradictions: [] },
|
||||
limits: { max_obligations: 100 },
|
||||
page: { offset: 0, limit: 50 },
|
||||
...overrides,
|
||||
});
|
||||
|
||||
const build = (
|
||||
input: ReconstructionObligationLedgerInput,
|
||||
): ReconstructionObligationLedgerPage => {
|
||||
const parsed = resolveReconstructionObligationLedgerRequest(input);
|
||||
if (!parsed.ok) throw parsed.error;
|
||||
const result = buildReconstructionObligationLedgerEvidenceValidated(
|
||||
parsed.value,
|
||||
);
|
||||
if (!result.ok) throw result.error;
|
||||
return reconstructionObligationLedgerPageSchema.parse(
|
||||
result.value.normalized_result,
|
||||
);
|
||||
};
|
||||
|
||||
const completeLedger = (
|
||||
page: ReconstructionObligationLedgerPage,
|
||||
obligations: ReconstructionObligationLedgerPage["obligations"],
|
||||
) => {
|
||||
const { page: pagination, ...ledger } = page;
|
||||
if (pagination.total !== obligations.length)
|
||||
throw new TypeError("Incomplete obligation page set");
|
||||
return { ...ledger, obligations };
|
||||
};
|
||||
|
||||
const originalCases = (
|
||||
obligation: ReconstructionObligationLedgerPage["obligations"][number],
|
||||
evidenceId: string,
|
||||
) =>
|
||||
obligation.required_case_kinds.map((caseKind) => ({
|
||||
kind: caseKind,
|
||||
evidence_id: evidenceId,
|
||||
location: `/normalized_result/cases/${caseKind}`,
|
||||
}));
|
||||
|
||||
const reviewedObligation = (
|
||||
obligationId: string,
|
||||
evidenceId: string,
|
||||
): ReviewedReconstructionObligation => ({
|
||||
obligation_id: obligationId,
|
||||
obligation_version: 1,
|
||||
title: `Reviewed obligation ${obligationId}`,
|
||||
application_layer: "other",
|
||||
family: "reviewed",
|
||||
target: {
|
||||
artifact_sha256: null,
|
||||
application_node_id: null,
|
||||
semantic_node_id: null,
|
||||
location: `/reviewed/${obligationId}`,
|
||||
},
|
||||
required: true,
|
||||
required_case_kinds: ["positive"],
|
||||
required_original_authority: "static",
|
||||
required_fixture_authority: "unit",
|
||||
required_verifier_authority: "unit",
|
||||
requires_parser_type: false,
|
||||
dependency_obligation_ids: [],
|
||||
residual_unknown_ids: [],
|
||||
unavailable_authority: [],
|
||||
required_next_evidence: ["Bind an owner and verifier."],
|
||||
disposition: "active",
|
||||
review_evidence_ids: [evidenceId],
|
||||
});
|
||||
|
||||
describe("reconstruction obligation ledger", () => {
|
||||
it("emits deterministic closure identity and paging", () => {
|
||||
const evidence = proofEvidence("review");
|
||||
const reviewed = [
|
||||
reviewedObligation("obl.review.one", evidence.evidence_id),
|
||||
reviewedObligation("obl.review.two", evidence.evidence_id),
|
||||
];
|
||||
const first = build(
|
||||
request([evidence], {
|
||||
reviewed_obligations: reviewed,
|
||||
page: { offset: 0, limit: 1 },
|
||||
}),
|
||||
);
|
||||
const second = build(
|
||||
request([evidence], {
|
||||
reviewed_obligations: reviewed,
|
||||
page: { offset: 1, limit: 1 },
|
||||
}),
|
||||
);
|
||||
|
||||
expect(first.page).toEqual({
|
||||
offset: 0,
|
||||
limit: 1,
|
||||
total: 2,
|
||||
returned: 1,
|
||||
next_offset: 1,
|
||||
});
|
||||
expect(second.page.next_offset).toBeNull();
|
||||
expect(second.ledger_id).toBe(first.ledger_id);
|
||||
expect(second.closure_digest).toBe(first.closure_digest);
|
||||
expect(first.obligations[0]?.source_state).toBe("reviewed");
|
||||
expect(first.status).toBe("open");
|
||||
expect(
|
||||
serializeReconstructionObligationLedger(
|
||||
completeLedger(first, [...first.obligations, ...second.obligations]),
|
||||
),
|
||||
).toBe(
|
||||
serializeReconstructionObligationLedger(
|
||||
completeLedger(second, [...first.obligations, ...second.obligations]),
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
it("does not let green unit evidence close a packaged-process obligation", () => {
|
||||
const capture = processEvidence();
|
||||
const proof = proofEvidence("green-unit");
|
||||
const initial = build(request([capture, proof]));
|
||||
const obligation = initial.obligations[0];
|
||||
if (obligation === undefined)
|
||||
throw new Error("Expected process obligation");
|
||||
const unitBinding = {
|
||||
obligation_id: obligation.obligation_id,
|
||||
owner: {
|
||||
module_path: "src/processOwner.ts",
|
||||
symbol: "runProcess",
|
||||
owner_sha256: "1".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: originalCases(obligation, capture.evidence_id),
|
||||
fixtures: obligation.required_case_kinds.map((caseKind) => ({
|
||||
fixture_id: `fixture.${caseKind}`,
|
||||
case_kind: caseKind,
|
||||
authority: "unit" as const,
|
||||
evidence_ids: [proof.evidence_id],
|
||||
})),
|
||||
verifier: {
|
||||
verifier_id: "verifier.unit",
|
||||
claim_id: "claim.process",
|
||||
command: "npm test -- processOwner",
|
||||
authority: "unit" as const,
|
||||
status: "pass" as const,
|
||||
result_evidence_id: proof.evidence_id,
|
||||
enumerated_obligation_ids: [obligation.obligation_id],
|
||||
nondeterminism: {
|
||||
mode: "total-order" as const,
|
||||
specification: "Exact unit-call order.",
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
const result = build(
|
||||
request([capture, proof], {
|
||||
manifest: {
|
||||
schema_version: 1,
|
||||
bindings: [unitBinding],
|
||||
contradictions: [],
|
||||
},
|
||||
}),
|
||||
);
|
||||
const evaluated = result.obligations[0];
|
||||
expect(evaluated?.status).toBe("implemented");
|
||||
expect(evaluated?.diagnostics.map(({ code }) => code)).toEqual(
|
||||
expect.arrayContaining([
|
||||
"weak-fixture-authority",
|
||||
"weak-verifier-authority",
|
||||
]),
|
||||
);
|
||||
expect(result.status).toBe("open");
|
||||
});
|
||||
});
|
||||
|
||||
describe("reconstruction obligation ledger case closure", () => {
|
||||
it("keeps unobserved original cases open", () => {
|
||||
const capture = processEvidence();
|
||||
const proof = proofEvidence("packaged-original-gap");
|
||||
const initial = build(request([capture, proof]));
|
||||
const obligation = initial.obligations[0];
|
||||
if (obligation === undefined)
|
||||
throw new Error("Expected process obligation");
|
||||
const result = build(
|
||||
request([capture, proof], {
|
||||
manifest: {
|
||||
schema_version: 1,
|
||||
bindings: [
|
||||
{
|
||||
obligation_id: obligation.obligation_id,
|
||||
owner: {
|
||||
module_path: "src/processOwner.ts",
|
||||
symbol: "runProcess",
|
||||
owner_sha256: "4".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: obligation.observed_cases,
|
||||
fixtures: obligation.required_case_kinds.map((caseKind) => ({
|
||||
fixture_id: `packaged.${caseKind}`,
|
||||
case_kind: caseKind,
|
||||
authority: "packaged-process",
|
||||
evidence_ids: [proof.evidence_id],
|
||||
})),
|
||||
verifier: {
|
||||
verifier_id: "verifier.packaged",
|
||||
claim_id: "claim.process",
|
||||
command: "npm run verify:package -- process",
|
||||
authority: "packaged-process",
|
||||
status: "pass",
|
||||
result_evidence_id: proof.evidence_id,
|
||||
enumerated_obligation_ids: [obligation.obligation_id],
|
||||
nondeterminism: {
|
||||
mode: "partial-order",
|
||||
specification:
|
||||
"Startup precedes teardown; worker completion is unordered.",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
contradictions: [],
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
expect(result.obligations[0]?.status).toBe("implemented");
|
||||
expect(result.obligations[0]?.diagnostics).toEqual(
|
||||
expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
code: "missing-original-case",
|
||||
detail: expect.stringContaining("negative"),
|
||||
}),
|
||||
expect.objectContaining({
|
||||
code: "missing-original-case",
|
||||
detail: expect.stringContaining("cancellation"),
|
||||
}),
|
||||
]),
|
||||
);
|
||||
expect(result.status).toBe("open");
|
||||
});
|
||||
|
||||
it("closes only when every required case and verifier has comparable authority", () => {
|
||||
const capture = processEvidence();
|
||||
const initial = build(request([capture]));
|
||||
const obligation = initial.obligations[0];
|
||||
if (obligation === undefined)
|
||||
throw new Error("Expected process obligation");
|
||||
const fixtureIds = obligation.required_case_kinds.map(
|
||||
(caseKind) => `packaged.${caseKind}`,
|
||||
);
|
||||
const proof = boundProofEvidence("packaged", {
|
||||
obligation_ids: [obligation.obligation_id],
|
||||
fixture_ids: fixtureIds,
|
||||
case_kinds: obligation.required_case_kinds,
|
||||
verifier_ids: ["verifier.packaged"],
|
||||
claim_ids: ["claim.process"],
|
||||
});
|
||||
const result = build(
|
||||
request([capture, proof], {
|
||||
manifest: {
|
||||
schema_version: 1,
|
||||
bindings: [
|
||||
{
|
||||
obligation_id: obligation.obligation_id,
|
||||
owner: {
|
||||
module_path: "src/processOwner.ts",
|
||||
symbol: "runProcess",
|
||||
owner_sha256: "2".repeat(64),
|
||||
},
|
||||
parser_type: null,
|
||||
original_cases: originalCases(obligation, capture.evidence_id),
|
||||
fixtures: obligation.required_case_kinds.map((caseKind) => ({
|
||||
fixture_id: `packaged.${caseKind}`,
|
||||
case_kind: caseKind,
|
||||
authority: "packaged-process",
|
||||
evidence_ids: [proof.evidence_id],
|
||||
})),
|
||||
verifier: {
|
||||
verifier_id: "verifier.packaged",
|
||||
claim_id: "claim.process",
|
||||
command: "npm run verify:package -- process",
|
||||
authority: "packaged-process",
|
||||
status: "pass",
|
||||
result_evidence_id: proof.evidence_id,
|
||||
enumerated_obligation_ids: [obligation.obligation_id],
|
||||
nondeterminism: {
|
||||
mode: "partial-order",
|
||||
specification:
|
||||
"Startup precedes teardown; worker completion is unordered.",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
contradictions: [],
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
expect(result.obligations[0]).toMatchObject({
|
||||
status: "verified",
|
||||
diagnostics: [],
|
||||
});
|
||||
expect(result.status).toBe("ready");
|
||||
expect(result.summary.required_open).toBe(0);
|
||||
});
|
||||
});
|
||||
@@ -27,18 +27,29 @@ interface RuntimeProbeFailure {
|
||||
readonly stderr: string;
|
||||
}
|
||||
|
||||
/** One lexical PATH candidate and its canonical executable probe result. */
|
||||
interface RuntimeExecutableDiagnostic {
|
||||
interface RuntimeExecutableIdentity {
|
||||
readonly tool: RuntimeToolName;
|
||||
readonly lexical_path: string;
|
||||
readonly canonical_path: string;
|
||||
readonly path_index: number | null;
|
||||
readonly selection: "rea-launcher" | "path-primary" | "path-shadowed";
|
||||
readonly version: string | null;
|
||||
readonly healthy: boolean;
|
||||
readonly failure: RuntimeProbeFailure | null;
|
||||
}
|
||||
|
||||
/** One lexical PATH candidate and its canonical executable probe result. */
|
||||
type RuntimeExecutableDiagnostic = RuntimeExecutableIdentity &
|
||||
(
|
||||
| {
|
||||
readonly version: string;
|
||||
readonly healthy: true;
|
||||
readonly failure: null;
|
||||
}
|
||||
| {
|
||||
readonly version: null;
|
||||
readonly healthy: false;
|
||||
readonly failure: RuntimeProbeFailure;
|
||||
}
|
||||
);
|
||||
|
||||
/** Runtime identities observed under one exact effective environment. */
|
||||
export interface RuntimeExecutableInventory {
|
||||
readonly launcher_node: string;
|
||||
@@ -148,16 +159,21 @@ const probeCandidate = async (
|
||||
): Promise<RuntimeExecutableDiagnostic> => {
|
||||
const canonical = await canonicalPath(candidate.path);
|
||||
const result = await executeVersion(candidate.path, timeoutMs, effectivePath);
|
||||
return {
|
||||
const identity = {
|
||||
tool: candidate.tool,
|
||||
lexical_path: candidate.path,
|
||||
canonical_path: canonical,
|
||||
path_index: candidate.pathIndex,
|
||||
selection: candidate.selection,
|
||||
version: result.ok ? result.version : null,
|
||||
healthy: result.ok,
|
||||
failure: result.ok ? null : result.failure,
|
||||
};
|
||||
return result.ok
|
||||
? { ...identity, version: result.version, healthy: true, failure: null }
|
||||
: {
|
||||
...identity,
|
||||
version: null,
|
||||
healthy: false,
|
||||
failure: result.failure,
|
||||
};
|
||||
};
|
||||
|
||||
type VersionResult =
|
||||
|
||||
@@ -74,8 +74,8 @@ export class SessionProviderRouter {
|
||||
private readonly runtime: SingleProviderRuntime | SelectableProviderRuntime,
|
||||
) {}
|
||||
|
||||
/** Preserve the existing provider/factory seam used by focused embedders. */
|
||||
static legacy(
|
||||
/** Create routing for an embedding backed by one fixed provider or factory. */
|
||||
static single(
|
||||
provider: AnalysisProvider | AnalysisClientFactory,
|
||||
options: {
|
||||
readonly resolveAnalysisProfile?: (
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { runCapabilityStatus, runProviderStatus } from "./DirectAnalysis.js";
|
||||
import { projectDoctorReport } from "./DoctorProjection.js";
|
||||
import { runDoctor, type DoctorHost } from "./Doctor.js";
|
||||
import { CATALOG_IDENTITY } from "../catalogIdentity.js";
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
|
||||
const doctorHost = (): DoctorHost => ({
|
||||
platform: "darwin",
|
||||
architecture: "x64",
|
||||
nodeVersion: "24.18.0",
|
||||
macosVersion: () => Promise.resolve("14.0"),
|
||||
linuxDistribution: () => Promise.resolve(undefined),
|
||||
validTarget: () => Promise.resolve(true),
|
||||
executable: (path) => Promise.resolve(path.includes("Hopper")),
|
||||
supportedLinuxHopper: () => Promise.resolve(true),
|
||||
linuxDemoRuntimeCheck: () =>
|
||||
Promise.resolve({
|
||||
name: "hopper-demo-runtime",
|
||||
ok: true,
|
||||
classification: "healthy",
|
||||
}),
|
||||
brewHopperPath: () => Promise.resolve(undefined),
|
||||
manualHopperPaths: () => Promise.resolve([]),
|
||||
installedSkillIdentity: () =>
|
||||
Promise.resolve({
|
||||
version: PRODUCT_IDENTITY.skillVersion,
|
||||
toolCount: CATALOG_IDENTITY.counts.mcp_tools,
|
||||
catalogDigest: CATALOG_IDENTITY.digests.combined_sha256,
|
||||
}),
|
||||
});
|
||||
|
||||
describe("purpose-specific CLI projections", () => {
|
||||
it("keeps provider and capability summaries concise with explicit full detail", async () => {
|
||||
const providers = await runProviderStatus();
|
||||
const capabilities = await runCapabilityStatus();
|
||||
const full = await runCapabilityStatus(undefined, "full");
|
||||
|
||||
expect(providers).toMatchObject({
|
||||
open: false,
|
||||
analysis_provider_candidates: expect.any(Array),
|
||||
server_identity: { catalog: { counts: expect.any(Object) } },
|
||||
});
|
||||
expect(JSON.stringify(providers)).not.toContain('"capabilities"');
|
||||
expect(JSON.stringify(providers)).not.toContain('"tools"');
|
||||
expect(capabilities).toMatchObject({
|
||||
summary: {
|
||||
total: expect.any(Number),
|
||||
available: expect.any(Number),
|
||||
unavailable: expect.any(Number),
|
||||
},
|
||||
capabilities: expect.any(Array),
|
||||
});
|
||||
expect(JSON.stringify(capabilities)).not.toContain('"effects"');
|
||||
expect(JSON.stringify(capabilities)).not.toContain('"limits"');
|
||||
expect(JSON.stringify(full)).toContain('"effects"');
|
||||
expect(JSON.stringify(full)).toContain('"catalog"');
|
||||
});
|
||||
|
||||
it("omits the catalog tool array only from the default doctor projection", async () => {
|
||||
const report = await runDoctor(undefined, doctorHost());
|
||||
const summary = projectDoctorReport(report, "summary");
|
||||
const full = projectDoctorReport(report, "full");
|
||||
|
||||
expect(summary).toMatchObject({
|
||||
healthy: true,
|
||||
environment_healthy: true,
|
||||
failed_scope_checks: [],
|
||||
informational_drift_count: 0,
|
||||
});
|
||||
expect(JSON.stringify(summary)).not.toContain('"tools"');
|
||||
expect(JSON.stringify(full)).toContain('"tools"');
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user