Candidate Reports

Candidate Reports

Candidate reports are JSON-friendly analysis results for tools, browser apps, and agents. They wrap parsing, feature extraction, candidate ranking, diagnostics, ambiguities, and document hypotheses into one shape.

Create a Report

import { createCandidateReport } from '@pkistudio/asn1defsifter';

const report = await createCandidateReport('300d06092a864886f70d01010b0500', {
  parseOptions: { format: 'hex' },
  maxResults: 5,
  includeSubtrees: true
});

Use createCandidateReportFromNodes(nodes) when a host already has neutral TLV nodes.

For PKI-only work, prefer:

import { createPkiCandidateReport } from '@pkistudio/asn1defsifter';

const report = await createPkiCandidateReport(input, {
  profiles: ['x509', 'pkcs8'],
  minScore: 0.8
});

Root Reports

Each CandidateReportRoot includes:

• index: root node index.
• features: extracted TLV features.
• summary: candidate counts, best candidate, diagnostic counts, and ambiguity count.
• candidates: ranked candidates for the root node.
• hypotheses: document-level hypotheses from identifyAsn1Document().
• diagnostics: aggregate diagnostics from returned candidates.
• ambiguities: aggregate ambiguity notes.
• subtrees: optional child-node reports when enabled.

Pass includeNodes: true when the report should include the input TlvNode objects.

Candidate Summaries

Candidate objects include:

• typeName and optional moduleName.
• score from 0 to 1.
• confidence as low, medium, or high.
• evidence items explaining positive matches.
• diagnostics for mismatches or weak areas.
• ambiguities for plausible alternatives.
• matchedPaths connecting TLV node paths to schema paths.

Evidence and diagnostics are part of the API contract. They are meant to be surfaced in tools rather than hidden behind a score.

Subtree Reports

Pass includeSubtrees: true to add bounded candidate reports for child TLV nodes.

Useful limits:

• maxSubtreeDepth: default depth bound.
• maxSubtreeReports: default report count bound.
• includeEmptySubtrees: include child nodes with no candidates.

Subtree reports are useful for compound PKI objects where the root type is clear but individual fields, nested BIT STRING values, OCTET STRING values, or algorithm-specific structures need additional explanation.

Document Hypotheses

Document hypotheses are higher-level interpretations of a root node. A hypothesis can include:

• root type name,
• confidence and score,
• evidence and diagnostics,
• an annotatedTree,
• alternatives.

The annotated tree connects TLV nodes to schema paths and inferred field names when the candidate match provides enough structure.

Diagnostics and Ambiguity

Diagnostics explain why a candidate is weak or mismatched. Examples include:

• expected SEQUENCE, found another tag,
• required field missing,
• unexpected extra child,
• OID or algorithm context mismatch,
• nested data not decodable as an expected type.

Ambiguity notes explain what the resolver cannot know from DER alone. For example, two different ASN.1 definitions can share the same SEQUENCE { INTEGER, INTEGER } shape.

Agent Workflow

Agents and workbench layers can use reports as repeatable evidence:

1. Parse input with PkiStudioJS.
2. Generate a root report with subtree reports.
3. Inspect OIDs and high-scoring candidates.
4. Use matched paths to identify interesting fields.
5. Compare subtree candidates with root-level hypotheses.
6. Present a final explanation that keeps uncertainty visible.

ASN.1 Definition Sifter provides the deterministic candidate list; the higher-level agent owns orchestration and final narrative.