canonical-schema: define shared entrypoint (and CRUD) vocabulary — TS, Java and Python have diverged

[sinha108]

Problem

canonical-schema.md (the keystone) has no vocabulary for entrypoints or CRUD/ORM enrichment — grep finds zero mentions. But analyzers already emit this data, and they have coined the term incompatibly:

Analyzer	Shape today
codeanalyzer-typescript	entrypoints: TSEntrypoint[] on callable and on class, plus TSApplication { symbol_table, call_graph, entrypoints } — its schema header describes this as "a field on the invariant spine"
codeanalyzer-java (v1)	is_entrypoint: boolean on callable, is_entrypoint_class: boolean on type; plus crud_operations[] / crud_queries[] on callable and JCrudOperation/JCrudQuery Neo4j families
codeanalyzer-python (v2)	nothing in the schema at all (its pass layer is documented as contributing entrypoints, but no schema field carries them)
Keystone	silent

This is exactly what the parity clause exists to prevent: a shared concept coined twice, differently, with no canonical definition to arbitrate. The SDK cannot model entrypoints once across languages while the shapes disagree, and each analyzer's Neo4j projection invents its own families (Java has an JEntrypoint marker label; TS does not).

Entrypoint detection is cross-language by nature (every analyzer needs to mark framework entrypoints), so it belongs in the keystone rather than in each analyzer's .claude/SCHEMA_DECISIONS.md. CRUD/ORM is cross-language in principle too — the analyzer-architecture guidance names "entrypoints, routes, ORM/CRUD" as the per-language framework axis — though only Java implements it today.

Discovered while implementing Java's L1 v2 emission (codellm-devkit/codeanalyzer-java#180, epic codellm-devkit/.github#42). Java is shipping the v1-equivalent booleans for now and will migrate once this is decided.

Scope boundary

This issue decides and documents the canonical vocabulary in skills/designing-cldk-changes/references/canonical-schema.md (and any consequent notes in neo4j-projection.md / schema-contract.md). It does not implement it in any analyzer or SDK — those are follow-ups in each repo. It also does not add new detection capability.

Goals

• Decide the canonical entrypoint shape: rich list (entrypoints: [{framework, kind, route?, http_method?}], TS's precedent — strictly more informative, booleans derivable) vs. a boolean/marker flag (Java's precedent, cheapest) — and where it hangs (callable, type, application, or all three)
• Decide whether entrypoints are a node field or a pass-layer enrichment overlay (the architecture guidance says domain concerns must not reshape the structural module/type/callable/call nodes)
• Decide the canonical CRUD/ORM shape (or explicitly declare it a per-language extension with a documented naming convention so analyzers don't diverge further)
• Define how entrypoints/CRUD project into Neo4j (marker label vs node families) so the graph schema is one contract across analyzers
• Record the migration path for each analyzer already emitting a divergent shape (TS list, Java booleans)
• Note the level/flag semantics: enrichment is the orthogonal precision axis, not an -a level

Caveats and known risks

• Whatever is chosen, at least one shipped analyzer must migrate — TS (list) and Java (booleans) cannot both be canonical. Sequence the migration so neither breaks its SDK consumers.
• Java's AbstractEntrypointFinder currently exposes only two boolean predicates (isEntrypointClass, isEntrypointMethod); a rich canonical shape requires extending all five Java finders (Spring, Jakarta, JAX-RS, Struts, Camel), which is real work in that repo.
• Route/HTTP-method metadata is not computed by any analyzer today; specifying it now risks a field nothing populates.

Definition of done

• canonical-schema.md defines the entrypoint (and CRUD-or-explicitly-deferred) vocabulary, with placement, field shapes, and the Neo4j projection.
• Migration notes exist for TS and Java's existing divergent shapes.
• Follow-up issues are filed on the affected analyzer/SDK repos.

[sinha108]

Sibling issue: #40 — same class of problem (keystone silent → analyzers diverge), but for the core L1 node vocabulary (comments/docstrings, local variables, enum constants, call-node richness, parameter modifiers, code_start_line, is_implicit, record components). This issue (#39) stays scoped to entrypoint/CRUD enrichment.

Both were found doing the Java schema-v2 migration: codellm-devkit/codeanalyzer-java#180 (epic codellm-devkit/.github#42).