Files
reverse-engineering-anything/src/domain/analysisView/featureTraceView.ts
T
Kaoru0822andClaude Opus 5.5 423059a4de feat(javascript): page retained feature traces through analysis views (#8522)
* feat(javascript): page retained feature traces through analysis views

A bidirectional trace_application_feature result can exceed one MCP
response, and inspect_analysis_view refused trace parents as unsupported,
so the only recovery was exporting the whole session.

- Add a shared feature-trace view owner: a summary with the trace's
  identity, producer counts and coverage, and pages of paths, nodes,
  edges, seed_matches and native_handoffs in retained order with exact
  filters. Node rows are compact unless observations are requested.
  Page coverage never upgrades trace coverage.
- Accept an optional MCP view on trace_application_feature that retains
  the complete trace before returning the selected facts; the CLI keeps
  complete JSON and reads saved traces with inspect-analysis-view.
- Offer a ready-to-call first paths page when a retained complete trace
  exceeds the MCP response budget.
- Share the distinct authority/state/confidence basis helper with
  module references.

Fixes #8296

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(javascript): name the retained parent when a selected view overflows

Review follow-up for the feature-trace views.

- Share one delivery owner between trace_application_feature and
  compare_source_to_bundle: stage the selected view against the
  completed parent, keep the established contract that a cancelled
  request commits no session facts, then commit sources and the parent.
- A selected view that exceeds the response budget now references the
  retained parent and offers the same selection at half its limit,
  instead of naming the view record, which cannot be a view parent.
- Cover two native handoffs paged one at a time, the oversized selected
  page, and cancellation after the trace completes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(javascript): bind feature-trace pages to their collection rows

Advertise each feature-trace page with exactly its own row schema, so a
paths page cannot validate with node, edge, seed-match or handoff rows.
The native-trace view in #8533 received the same review finding; the two
sibling views now share one strict page contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(javascript): mix valid rows from another collection into a trace page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 08:56:05 -08:00

350 lines
11 KiB
TypeScript

import { z } from "zod";
import { prefixedDigestSchema } from "../digests.js";
import { applicationCoverageSchema } from "../javascript/javascriptApplicationEvidenceSchemas.js";
import {
applicationEdgeSchema,
applicationNodeSchema,
type ApplicationEdge,
type ApplicationNode,
} from "../javascript/javascriptApplicationGraphSchemas.js";
import {
applicationFeatureTraceResultSchema,
type ApplicationFeatureTraceResult,
} from "../javascript/javascriptFeatureTraceSchemas.js";
import { err, ok } from "../result.js";
import {
boundedViewMessages,
completeWithinViewCoverage,
pageViewCoverage,
} from "./analysisViewCoverage.js";
import { analysisViewInputError } from "./analysisViewErrors.js";
import {
createAnalysisViewResultReader,
type AnalysisViewParent,
} from "./analysisViewParent.js";
import {
ownedView,
type AdmittedView,
type SummaryAnalysisView,
} from "./analysisViewShape.js";
import {
javascriptFactBasis,
javascriptFactBasisSchema,
} from "./javascriptModuleReferences.js";
import { selectViewRows } from "./selectViewRows.js";
const OPERATION = "trace_application_feature" as const;
const trace = applicationFeatureTraceResultSchema.shape;
const nodeIdsFilter = z
.array(prefixedDigestSchema("jag_node"))
.optional()
.describe(
"Exact trace node identities. Omitted selects all; [] selects none.",
);
const page = {
kind: z.literal("feature-trace"),
offset: z.int().nonnegative().default(0),
limit: z.int().positive().default(64),
};
const pathsRequestSchema = z.strictObject({
...page,
collection: z.literal("paths"),
where: z
.strictObject({
node_ids: nodeIdsFilter.describe(
"Select terminal paths that visit any of these exact node identities. Omitted selects all; [] selects none.",
),
end_kinds: z.array(applicationNodeSchema.shape.kind).optional(),
})
.default({}),
});
const nodesRequestSchema = z.strictObject({
...page,
collection: z.literal("nodes"),
where: z
.strictObject({
node_ids: nodeIdsFilter,
kinds: z.array(applicationNodeSchema.shape.kind).optional(),
})
.default({}),
include_observations: z
.boolean()
.default(false)
.describe(
"Opt into each selected node's complete retained observations, including properties and provenance.",
),
});
const edgesRequestSchema = z.strictObject({
...page,
collection: z.literal("edges"),
where: z
.strictObject({
node_ids: nodeIdsFilter.describe(
"Select edges whose source or target is one of these exact node identities. Omitted selects all; [] selects none.",
),
relations: z.array(applicationEdgeSchema.shape.relation).optional(),
})
.default({}),
});
const seedMatchesRequestSchema = z.strictObject({
...page,
collection: z.literal("seed_matches"),
});
const handoffsRequestSchema = z.strictObject({
...page,
collection: z.literal("native_handoffs"),
});
/** Page one collection of a completed feature trace in its retained order. */
export const featureTraceViewRequestSchema = z.discriminatedUnion(
"collection",
[
pathsRequestSchema,
nodesRequestSchema,
edgesRequestSchema,
seedMatchesRequestSchema,
handoffsRequestSchema,
],
);
type FeatureTraceViewRequest = z.output<typeof featureTraceViewRequestSchema>;
/** Compact node identity and support; full observations are opt-in. */
const featureTraceNodeRowSchema = applicationNodeSchema
.pick({ node_id: true, kind: true, identity: true })
.extend({
seed: z
.boolean()
.describe("Whether this node matched the trace seed (a trace root)."),
observation_count: z.int().positive(),
basis: z.array(javascriptFactBasisSchema).min(1),
observations: applicationNodeSchema.shape.observations.exactOptional(),
});
/**
* Each collection's request bound to its own rows, so a reply cannot pair one
* collection with another's rows. Rows are the producer's exact records or the
* compact node projection.
*/
export const featureTraceViewCollections = {
paths: { request: pathsRequestSchema, rows: z.array(trace.paths.element) },
nodes: {
request: nodesRequestSchema,
rows: z.array(featureTraceNodeRowSchema),
},
edges: { request: edgesRequestSchema, rows: z.array(applicationEdgeSchema) },
seed_matches: {
request: seedMatchesRequestSchema,
rows: z.array(trace.seed_matches.element),
},
native_handoffs: {
request: handoffsRequestSchema,
rows: z.array(trace.native_handoffs.element),
},
} as const;
/** Trace identity and coverage repeated with every view so selected rows stay traceable. */
export const featureTraceViewContextSchema = z.strictObject({
trace_id: trace.trace_id,
source_evidence_id: trace.source_evidence_id,
source_graph_id: trace.source_graph_id,
seed: trace.seed,
direction: trace.direction,
summary: trace.summary,
trace_coverage: trace.coverage,
graph_coverage: applicationCoverageSchema
.nullable()
.describe("The traced subgraph's coverage, or null when no seed matched."),
evidence_links: trace.evidence_links,
});
/** Summary context adds the producer's already paged no-match discovery. */
export const featureTraceSummarySchema = featureTraceViewContextSchema.extend({
semantic_discovery: trace.semantic_discovery,
limitation_count: z.int().nonnegative(),
});
const checkedTrace = createAnalysisViewResultReader(
applicationFeatureTraceResultSchema,
);
const selected = <Value>(values: readonly Value[] | undefined) =>
values === undefined ? undefined : new Set(values);
const traceContext = (result: ApplicationFeatureTraceResult) => ({
trace_id: result.trace_id,
source_evidence_id: result.source_evidence_id,
source_graph_id: result.source_graph_id,
seed: result.seed,
direction: result.direction,
summary: result.summary,
trace_coverage: result.coverage,
graph_coverage: result.graph?.coverage ?? null,
evidence_links: result.evidence_links,
});
const traceUnknowns = (result: ApplicationFeatureTraceResult): string[] => [
...(result.coverage.status === "partial"
? [
`trace_coverage.status is partial because the source application graph is ${result.coverage.source_graph_status}; unmatched seeds and frontiers remain unknown.`,
]
: []),
"Trace connectivity does not prove runtime execution or reachability. Exhausting a page establishes nothing outside this trace.",
];
const nodeRow = (
node: ApplicationNode,
seeds: ReadonlySet<string>,
includeObservations: boolean,
): z.output<typeof featureTraceNodeRowSchema> => ({
node_id: node.node_id,
kind: node.kind,
identity: node.identity,
seed: seeds.has(node.node_id),
observation_count: node.observations.length,
basis: javascriptFactBasis(node.observations.map(({ evidence }) => evidence)),
...(includeObservations ? { observations: node.observations } : {}),
});
/** One page per collection, built in its own branch so view and rows stay correlated. */
const tracePage = <Shared extends object>(
result: ApplicationFeatureTraceResult,
view: FeatureTraceViewRequest,
shared: Shared,
) => {
const pageOf = <View extends FeatureTraceViewRequest, Row>(
selection: View,
{ rows, total }: { readonly rows: Row[]; readonly total: number },
) => ({
kind: "feature-trace" as const,
view: selection,
...shared,
items: rows,
coverage: pageViewCoverage(selection.offset, rows.length, total),
});
const all = () => true;
if (view.collection === "seed_matches")
return pageOf(
view,
selectViewRows(result.seed_matches, view, all, (row) => row),
);
if (view.collection === "native_handoffs")
return pageOf(
view,
selectViewRows(result.native_handoffs, view, all, (row) => row),
);
if (view.collection === "paths") {
const nodes = selected(view.where.node_ids);
const ends = selected<string>(view.where.end_kinds);
return pageOf(
view,
selectViewRows(
result.paths,
view,
(path) =>
(ends === undefined || ends.has(path.end_kind)) &&
(nodes === undefined || path.node_ids.some((id) => nodes.has(id))),
(path) => path,
),
);
}
const graph = result.graph;
if (view.collection === "edges") {
const nodes = selected(view.where.node_ids);
const relations = selected(view.where.relations);
return pageOf(
view,
selectViewRows<ApplicationEdge, ApplicationEdge>(
graph?.edges ?? [],
view,
(edge) =>
(relations === undefined || relations.has(edge.relation)) &&
(nodes === undefined ||
nodes.has(edge.source_node_id) ||
nodes.has(edge.target_node_id)),
(edge) => edge,
),
);
}
const ids = selected(view.where.node_ids);
const kinds = selected(view.where.kinds);
const seeds = new Set(result.seed_matches.map(({ node_id: id }) => id));
return pageOf(
view,
selectViewRows(
graph?.nodes ?? [],
view,
(node) =>
(ids === undefined || ids.has(node.node_id)) &&
(kinds === undefined || kinds.has(node.kind)),
(node) => nodeRow(node, seeds, view.include_observations),
),
);
};
/** Select retained trace facts without re-running traversal or changing its coverage. */
export const projectFeatureTraceView = (
parent: AnalysisViewParent,
admitted: AdmittedView,
) => {
const view = ownedView<SummaryAnalysisView | FeatureTraceViewRequest>(
admitted,
"summary",
"feature-trace",
);
if (view === undefined)
return err(
analysisViewInputError([
{
path: ["view"],
reason: "invalid_value",
message:
"Application feature traces support summary and feature-trace pages of paths, nodes, edges, seed_matches or native_handoffs.",
},
]),
);
const parsed = checkedTrace(parent);
if (!parsed.ok) return parsed;
const result = parsed.value;
const limitations = [
...parent.limitations,
...result.limitations,
...(result.graph?.limitations ?? []),
];
const shared = {
parent_evidence_id: parent.evidenceId,
parent_operation: OPERATION,
parent_digest: parent.evidenceId.slice(3),
artifact: null,
limitations: boundedViewMessages(
limitations,
parent.evidenceId,
"limitations",
),
unknowns: boundedViewMessages(
[],
parent.evidenceId,
"unknowns",
traceUnknowns(result),
),
};
const context = traceContext(result);
if (view.kind === "summary")
return ok({
kind: "summary" as const,
view,
...shared,
summary: {
...context,
...(result.semantic_discovery === undefined
? {}
: { semantic_discovery: result.semantic_discovery }),
limitation_count: new Set(limitations).size,
},
coverage: completeWithinViewCoverage(1, 1),
});
return ok(tracePage(result, view, { ...shared, ...context }));
};