spec: dependency intelligence export contract

[matiasdaloia]

Problem Statement

Consumers of crypto-finder's JSON exports need stable, machine-readable
relationships between cryptographic findings and dependency call graphs.
Several concepts are currently easy to confuse: a metadata anchor is not
necessarily an execution method, a supporting call is not a forward call, and a
crypto entry point is a reachability lookup rather than a lifecycle role.

Without one explicit export contract, consumers can misjoin overloaded methods,
misinterpret client call order as a dependency call edge, or fail to locate the
method where cryptographic computation occurs.

Solution

Define and validate a language-agnostic dependency-intelligence export contract
for crypto-finder.

The contract provides complete canonical signatures, normalized parameter
conditions, parameter-derivation roles, categorized supporting calls, real
forward calls, call chains, and a signature-indexed crypto-entry-point lookup.
Execution methods such as block-processing and finalization calls are operation
supporting calls referenced by applicable findings.

User Stories

1. As an export consumer, I want complete canonical signatures, so that same-arity overloads remain distinguishable.
2. As an export consumer, I want declaring type, parameter types, and return type in callable identities, so that joins are deterministic.
3. As an export consumer, I want structured parameter conditions, so that I can evaluate finding applicability without parsing free text.
4. As an export consumer, I want normalized condition operands, so that equivalent literals have one representation.
5. As an export consumer, I want parameter roles and derivation strategies, so that I can derive metadata such as key size from known arguments.
6. As an export consumer, I want crypto entry points defined as reachability lookups, so that I do not interpret them as lifecycle roles.
7. As an export consumer, I want supporting calls categorized as factory, configuration, operation, or output, so that their purpose is explicit.
8. As an export consumer, I want execution methods categorized as operation supporting calls, so that I can locate the cryptographic computation.
9. As an export consumer, I want findings to reference applicable supporting calls, so that I can navigate from evidence to related methods.
10. As an export consumer, I want supporting-call identifiers to remain opaque references, so that joins do not depend on their format.
11. As an export consumer, I want canonical signatures on supporting calls, so that observed call targets can be matched precisely.
12. As an export consumer, I want forward calls to represent only real implementation edges, so that client invocation order is never fabricated as a call graph.
13. As an export consumer, I want forward-call arguments aligned by parameter index, so that declared types are recoverable without duplicated fields.
14. As an export consumer, I want expressions, resolved values when available, inferred types, and provenance, so that ambiguous targets can be refined safely.
15. As an export consumer, I want truncation and unresolved states represented explicitly, so that incomplete output is never mistaken for a complete graph.
16. As an export consumer, I want the current finding identifier preserved, so that findings and graph records remain cross-referenceable.
17. As an export consumer, I want conditioned records distinguished by their conditions, so that a second finding-identity namespace is unnecessary.
18. As an export consumer, I want explicit provider metadata preserved when it is present in analyzed source, so that proven facts are not lost.
19. As an export consumer, I want runtime-selected providers left unresolved, so that an API framework is not mislabeled as a concrete provider.
20. As a language maintainer, I want the same external semantics across languages, so that language-specific parsers remain interoperable.

Implementation Decisions

• The complete canonical signature is the external callable join key. It includes declaring type, method, parameter types, and return type.
• Structured parameter conditions remain producer-normalized and machine-readable.
• The initial condition grammar supports positional, named, and combined selectors; equality, regular-expression, type-equality, and type-regular-expression predicates; and logical conjunction.
• Parameter roles classify operation selection, metadata contribution, non-metadata parameters, and unresolved parameters.
• crypto_entry_points remains a signature-indexed reachability lookup containing references to reachable findings and supporting calls.
• Lifecycle semantics are represented in supporting_calls with the categories factory, configuration, operation, and output.
• Execution methods are represented as operation supporting calls. They are not duplicated as operation-only entry-point records.
• Findings use the existing supporting-call references to identify applicable execution methods. No reverse finding list is added to supporting-call records.
• Supporting-call identifiers are opaque references; canonical signatures are the consumer join key.
• Forward calls contain only real dependency implementation edges.
• Sequential calls made by external code on the same receiver are not represented as forward-call edges.
• Forward-hop arguments align with the callee parameter-type array through their parameter indexes.
• Ambiguous targets remain candidates with supporting evidence rather than being guessed.
• The existing finding identifier format and generation remain unchanged. No asset-variant identifier is introduced.
• Static provider evidence is preserved when available. Runtime provider selection remains unresolved.
• The contract is language-agnostic. Language implementations may differ in resolution maturity but not in field meaning.
• User-visible schema changes include an Unreleased changelog entry and explicit schema-version handling.

Testing Decisions

• The highest public test seam is a black-box crypto-finder execution that analyzes version-pinned source fixtures and validates the emitted findings and call-graph JSON.
• Tests assert exported behavior rather than private helpers.
• Canonical-signature fixtures include overload and interface/override scenarios.
• Condition fixtures cover normalized values, types, regular expressions, and conjunction.
• Supporting-call fixtures assert all lifecycle categories and per-finding references.
• Operation fixtures assert that execution methods appear as operation supporting calls without fabricated lifecycle edges.
• Forward-call fixtures assert parameter indexes, declared-type alignment, source expressions, provenance, ambiguity, and truncation state.
• Equivalent Java and Python fixtures establish the first cross-language parity baseline.
• Existing graph-fragment export, stitch, supporting-call derivation, and real-parser tests are the preferred supporting seams.

Out of Scope

• Downstream storage, transport, or user-interface behavior.
• Client-source ordering, receiver correlation, or fluent-chain reconstruction.
• Runtime provider or certified-module resolution.
• Compliance, vulnerability, or organizational policy verdicts.
• Changing the current finding identifier or adding another identity namespace.
• Fabricating lifecycle relationships as dependency call-graph edges.
• Guaranteeing static resolution for inherently dynamic language constructs.
• Expanding the supported component catalog as part of this issue.

Further Notes

• Existing fields and references should be reused before adding new schema structures.
• Repository-specific implementation tickets should link back to this specification.