@saptools/service-flow 0.1.69 → 0.1.72

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.72
+
+- Published the completed event-surface provenance, constant-topic, candidate-subscriber, environment-declaration, and doctor-quality work as a package-only patch. SQLite remains schema `14`, analyzer compatibility remains `0.1.71-facts.1`, and compact remains `service-flow/compact-graph@1`; no additional reindex is required after applying the schema-14 fact release.
+
+## 0.1.71
+
+- Replaced event-receiver name gating with structural CAP-connect and lexical reaching-assignment proof for declarations, later assignments, destructuring, and formatter-split chains. Property and non-CAP receivers now persist bounded fail-closed facts instead of disappearing; compatibility names remain explicit `name_fallback` evidence.
+- Folded proven local, relative-module, and public package enum/const-object event topics without evaluating expressions. Mutable, non-string, unexposed, duplicate, computed, or incomplete containers retain typed unresolved reasons, and package constant facts are invalidated and re-resolved when their target surface changes.
+- Added schema 14 carriers for canonical event skeletons, allowlisted repository environment declarations, and generated string-constant provenance. Shape-equivalent subscriptions are opt-in dynamic candidates only when the identical hole layout has a literal span of at least eight characters; one canonical positional `--var` key can resolve both source-name variants.
+- Added per-repository `SHARD_CODE` declarations from bounded dev/deployment metadata, with explicit provenance, only `toUpperCase`/`toLowerCase` transforms, duplicate-value ambiguity, dependency-aware consumer expansion, fingerprint invalidation, and exclusion of every non-allowlisted neighbouring environment key.
+- Added strict doctor aggregates for unresolved names, dynamic candidates, unmatched publications/subscriptions, receiver proof outcomes, skeleton candidates, and environment ambiguities. Loop registrations retain enumerable multiplicity evidence, payload-routed sites remain non-authoritative candidates, and table/compact evidence exposes workspace-name-only delivery certainty.
+- Package/CLI was `0.1.71`, SQLite is schema `14`, analyzer compatibility is `0.1.71-facts.1`, and compact remains `service-flow/compact-graph@1`. The writer-only migration leaves legacy event skeleton/environment provenance null and marks old facts stale; existing workspaces require `index --force` followed by `link --force`.
+
+## 0.1.70
+
+- Removed numeric ordering prefixes from every tracked source and test filename and updated all package-local imports. This is a source-layout-only release: SQLite remains schema `13`, analyzer compatibility remains `0.1.69-facts.1`, and the compact schema remains `service-flow/compact-graph@1`.
+
 ## 0.1.69
 
 - Corrected one-hop derived import identity: conventional relative default-class instances use target-side default-export evidence, package-derived members cannot leak into same-file exact-name resolution, and package-backed proxy aliases fail closed with an honest unsupported reason. Unresolved and ambiguous local/package symbol-call facts now remain visible as non-traversable trace edges.

package/README.md

@@ -54,7 +54,7 @@ npm install @saptools/service-flow
 
 ### Correctness notes
 
-- Runtime `--var` values are considered only for dynamic, ambiguous, or unresolved **remote** graph edges whose alias, destination, service path, or operation path expressions contain supplied placeholders. Placeholder keys are the full trimmed expression inside a balanced `${...}` region, so keys such as `domainInfo.serviceName`, `tenantInfo.region?.toLowerCase()`, and `items?.[0].service` can be supplied literally without JavaScript evaluation. Quote complex keys in the shell, for example `--var 'tenantInfo.region?.toLowerCase()=lookup'`. Local database, external HTTP, event, and already resolved static edges keep their persisted status, target, reason, and confidence. Partial substitutions remain dynamic and report the missing placeholder names.
+- Runtime `--var` values are considered for dynamic remote targets and template event names. Placeholder keys are the full trimmed expression inside a balanced `${...}` region, so keys such as `domainInfo.serviceName`, `tenantInfo.region?.toLowerCase()`, and `items?.[0].service` can be supplied literally without JavaScript evaluation. Quote complex keys in the shell, for example `--var 'tenantInfo.region?.toLowerCase()=lookup'`. Local database, external HTTP, and already resolved static edges keep their persisted status, target, reason, and confidence. Partial substitutions remain dynamic and report the missing placeholder names.
 - `trace` and `graph` both accept repeatable `--var key=value` options. Effective substitutions are rendered in trace evidence without mutating the persisted graph. Confidence values are bounded to `[0, 1]`.
 - Contextual binding attempts retain a labelled `contextualPreSubstitutionState` for auditability. After compatible `--var` substitution, a dynamic edge, `effectiveResolution`, and `linker.reason` use the same sorted current missing-key message. Structural contextual blockers remain separately visible as `contextualBlocker`; they cannot be inferred away.
 - Dynamic target exploration is explicit. Default `--dynamic-mode strict` keeps every target with unresolved runtime variables fail-closed, but diagnostics can provide complete copyable `--var` sets. `--dynamic-mode candidates` renders only viable, capped, explicitly unselected branches while the route remains unresolved, never enters their handler bodies, and adds no exploratory branch once complete explicit values resolve the route. `--dynamic-mode infer` traverses only when the top viable, complete candidate scores at least `0.85` and exceeds the runner-up by more than `0.05`; exact ties, candidates exactly on the margin, conflicts, duplicate identities, incomplete leaders, and weaker scores stay unresolved.
@@ -80,7 +80,11 @@ npm install @saptools/service-flow
 - Persisted graph rows take precedence during `trace` and `graph`: resolved call edges keep their `graph_edges.id`, `outbound_calls.id`, call-site file/line, outbound parser evidence, linker status/reason, and selected target evidence. Contextual runtime resolution can enrich evidence but does not replace an already resolved persisted target. Terminal start diagnostics such as ambiguous operations or rejected implementations return zero nodes and zero edges by default; candidates remain in structured diagnostics for automation.
 - Every AST-backed call owner is selected from executable symbols by complete zero-based, half-open UTF-16 span containment. Event subscriptions and their handler references prefer the exact same-span synthetic `event_registration`; otherwise the narrowest containing scope and a fixed binary kind/name order apply. Physical line remains display evidence and is never an identity fallback.
 - Event-subscription handler facts have the durable role `event_subscribe_handler`, retain `factOrigin: event_subscribe_handler_reference`, and keep resolver-owned `candidateStrategy` separate. Every supported subscription records one closed `handlerReferenceStatus`; named/member/namespace and supported single-wrapper references require one same-span role row, while explicitly unsupported inline/wrapper/reference shapes and a missing argument require none.
-- Event names supplied as template literals are persisted as opaque, non-evaluated expressions instead of being dropped. Strict traces keep them dynamic until every exact emit- and subscribe-side placeholder key is supplied with `--var`; only equal, case-sensitive substituted names traverse the subscriber boundary.
+- Event-shaped calls are never discarded because a receiver proof is unavailable. The parser structurally proves CAP-connect declarations and reaching assignments, including later assignment, destructuring, try-wrapped assignment, and formatter-split chains. Property/parameter propagation and known non-CAP values remain typed, non-traversable facts; historical receiver names are retained only as explicit `name_fallback` evidence.
+- Stable string consts, enum members, and const-object properties can supply static event names from the same file, an exact relative module, or a uniquely proven package public entry. Computed access, mutable or non-string members, hidden/duplicate containers, incomplete public surfaces, and unsupported alias chains fail closed with constant-specific reasons.
+- Event names supplied as template literals are persisted as opaque, non-evaluated expressions instead of being dropped. Strict traces keep them dynamic until every exact emit- and subscribe-side placeholder key is supplied with `--var`; only equal, case-sensitive substituted names traverse the subscriber boundary. A canonical positional hole key may resolve different source-variable names on both sides.
+- Equal template skeletons can appear under `--dynamic-mode candidates` as `EVENT_SHAPE_CANDIDATE_SUBSCRIBER` edges only when their hole layout is identical and at least one literal span is eight characters or longer. These bounded edges are always dynamic and non-authoritative; all-hole and short-literal shapes are refused.
+- Repository environment declarations are allowlisted facts. The schema-14 analyzer reads only `SHARD_CODE` from `nodemon.json`, `.env`, `manifest.yml`, and `mta.yaml`, retains dev/deployment provenance, and supports only `toUpperCase()`/`toLowerCase()`. Duplicate consumer values, conflicting declarations, and unsupported transforms remain ambiguous or unresolved; adjacent non-allowlisted keys are never persisted.
 - A subscription and its handler reference associate only by workspace, repository, normalized source file, and the complete non-null outer `.on(...)` call span, with matching line/caller validation. Link never falls back to caller, line, start offset, label, or case-folded name heuristics. Resolved, ambiguous, unresolved, and explicitly unsupported associations remain distinguishable.
 - Service bindings carry their own declaration/assignment span and `owned_exact` or `ownerless_file_scope` status. Supported calls carry the exact visible binding site and a complete outer-to-inner lexical-scope proof capped at 16 scopes; persistence joins by repository, file, variable, and full site span. A deeper proof fails closed instead of being truncated. Shadowed, future, branch-dependent, hoisted, ambiguous, or otherwise unsupported flows remain unselected rather than using same-line/source-order proximity.
 - Package symbol calls preserve module origin, ESM/CommonJS binding shape, local and imported names, requested package, and requested public subpath. Resolution requires a unique package repository plus a complete public-entry/name exposure proof and an executable body. An explicit `exports` map is authoritative; unsupported conditional/wildcard maps, unsupported or ambiguous entrypoints/barrels, unexposed internals, wrong subpaths, declaration-only targets, duplicate repositories/targets, incomplete retained evidence, mutable/reassigned/escaped public values, and mutated CommonJS namespace objects fail closed rather than selecting a stale body. Incomplete exact-scope evidence uses `public_surface_evidence_incomplete`; this conservative compatibility cost is intentional for package shapes the static analyzer cannot prove.
@@ -90,7 +94,7 @@ npm install @saptools/service-flow
 - Repository public-surface evidence uses the versioned `service-flow/package-public-surface@1` carrier and retains at most 256 public exposure records with truthful total/shown/omitted metadata. A displayed prefix never proves uniqueness or absence; an omitted requested scope stays unresolved unless an authoritative exact-name count proves the decision.
 - OData entity paths are conservative terminal remote entity edges. Reads, mutations, deletes, navigation paths, media-stream paths such as `/Documents(ID)/content`, and uppercase unknown entity-set candidates do not inflate unresolved operation counts. Lowercase action/function-style paths remain eligible for indexed operation resolution.
 - External HTTP destinations are static only when a safe literal or local const literal proves the value. Identifier, property-read, function-call, and arbitrary destination expressions are dynamic with stable `destination:dynamic:<hash>` ids and neutral labels; conditional literal branches expose only safe candidate names.
-- Schema version 13 adds exact binding-site spans and ownership plus the repository public-surface carrier to the schema-12 call span/role facts. A writer-only v12→v13 migration leaves legacy binding spans/public surfaces null and ownership `legacy_unknown`; it never reconstructs provenance from line, names, or old relationships. Package `0.1.69` keeps schema 13 and uses analyzer `0.1.69-facts.1`; the new strategy remains JSON evidence rather than a SQL-enumerated column. Upgrading requires a forced index followed by a forced link. Read-only commands report bounded schema/reindex diagnostics and link preserves the last good graph until both passes succeed.
+- Schema version 14 adds canonical event-skeleton columns, a repository environment-declaration carrier, and generated string-constant facts/indexes. A writer-only migration leaves every legacy skeleton/environment value null, marks indexed repositories stale with `schema_v14_event_surface_requires_reindex`, and never fabricates provenance. Package `0.1.72` uses analyzer `0.1.71-facts.1`; read-only commands report bounded schema/reindex diagnostics and link preserves the last good graph until migration, force reindex, and force relink succeed.
 
 
 ## 🚀 Quick Start
@@ -118,7 +122,7 @@ service-flow doctor --workspace /path/to/workspace
 After `init`, the workspace configuration and SQLite database live below the selected workspace by default. Run `index` whenever source changes; unchanged repositories are skipped unless `--force` is supplied. Then run `link` to rebuild the graph edges used by `trace` and `graph`.
 
 > [!IMPORTANT]
-> Version 0.1.69 keeps database schema 13 and changes the fact analyzer to `0.1.69-facts.1`. Derived-import identity, dynamic event topics, structural CQL dispatch, and helper-return bindings therefore require fresh facts even though no SQL migration is needed. Refresh facts and graph edges before tracing:
+> The schema-14 fact release upgrades the database and uses analyzer `0.1.71-facts.1`. Event receiver, constant, skeleton, and environment semantics changed, so every existing workspace requires:
 >
 > ```bash
 > service-flow index --workspace /path/to/workspace --force
@@ -476,7 +480,7 @@ Step  Type                 From                                To
 `--format compact-json` projects the same traversal into the minified, newline-terminated `service-flow/compact-graph@1` contract. It is a lossy AI-oriented semantic topology and bounded decision summary; use the detailed JSON companion whenever exact evidence is required.
 
 ```json
-{"schema":"service-flow/compact-graph@1","start":{"repo":"facade-service","servicePath":"/FacadeService","operation":"doWork","operationPath":null,"handler":null},"query":{"depth":25,"includeAsync":true,"includeDb":true,"includeExternal":true,"dynamicMode":"strict","maxDynamicCandidates":5,"suppliedVariableNames":[],"runtimeValuesOmitted":true,"implementationRepo":null,"implementationHints":[]},"source":{"schemaVersion":13,"analyzerVersion":"0.1.69-facts.1","graphGeneration":7},"summary":{"completeness":"complete","fullTraceNodes":2,"fullTraceEdges":1,"fullTraceDiagnostics":0,"nodes":2,"edges":1,"collapsedEdges":0,"statusCounts":{"resolved":0,"terminal":1,"inferred":0,"dynamic":0,"ambiguous":0,"unresolved":0,"cycle":0},"projection":{"evidence":"summary-only","syntheticEndpoints":0,"omittedUnreferencedFullNodes":0}},"repos":["facade-service"],"files":["srv/EntryHandler.ts"],"nodeColumns":["id","kind","label","repo","file","line"],"nodes":[["n0","symbol","EntryHandler.doWork",0,0,8],["n1","database_entity","Template",null,null,null]],"edgeColumns":["id","traceOrdinals","step","type","from","to","status","confidence","count","details"],"edges":[["e0",[0],1,"local_db_query","n0","n1","terminal",0.95,1,null]],"diagnosticColumns":["fullDiagnosticIndex","severity","code","message","file","line","details"],"diagnostics":[]}
+{"schema":"service-flow/compact-graph@1","start":{"repo":"facade-service","servicePath":"/FacadeService","operation":"doWork","operationPath":null,"handler":null},"query":{"depth":25,"includeAsync":true,"includeDb":true,"includeExternal":true,"dynamicMode":"strict","maxDynamicCandidates":5,"suppliedVariableNames":[],"runtimeValuesOmitted":true,"implementationRepo":null,"implementationHints":[]},"source":{"schemaVersion":14,"analyzerVersion":"0.1.71-facts.1","graphGeneration":7},"summary":{"completeness":"complete","fullTraceNodes":2,"fullTraceEdges":1,"fullTraceDiagnostics":0,"nodes":2,"edges":1,"collapsedEdges":0,"statusCounts":{"resolved":0,"terminal":1,"inferred":0,"dynamic":0,"ambiguous":0,"unresolved":0,"cycle":0},"projection":{"evidence":"summary-only","syntheticEndpoints":0,"omittedUnreferencedFullNodes":0}},"repos":["facade-service"],"files":["srv/EntryHandler.ts"],"nodeColumns":["id","kind","label","repo","file","line"],"nodes":[["n0","symbol","EntryHandler.doWork",0,0,8],["n1","database_entity","Template",null,null,null]],"edgeColumns":["id","traceOrdinals","step","type","from","to","status","confidence","count","details"],"edges":[["e0",[0],1,"local_db_query","n0","n1","terminal",0.95,1,null]],"diagnosticColumns":["fullDiagnosticIndex","severity","code","message","file","line","details"],"diagnostics":[]}
 ```
 
 The `nodeColumns`, `edgeColumns`, and `diagnosticColumns` arrays define fixed-width tuples; absent cells are explicit `null`. Any breaking change to those columns or to the declared v1 top-level/query/source/summary/status/aggregation/diagnostic semantics requires a new `@N` schema. Repository and file dictionaries are sorted, and dense `n0...`/`e0...` IDs are assigned after canonical sorting. Those dense IDs are output-local and are not stable database identifiers.

package/TECHNICAL-NOTE.md

@@ -1,5 +1,22 @@
 # Service Flow Resolution Notes
 
+## 0.1.72 package publication notes
+
+- Package/CLI `0.1.72` publishes the schema-14 event-surface implementation without changing fact or compact compatibility. SQLite remains schema `14`, analyzer remains `0.1.71-facts.1`, and compact remains `service-flow/compact-graph@1`; repositories already force-indexed with analyzer `0.1.71-facts.1` do not churn solely for this package patch.
+
+## 0.1.71 event-surface proof and candidate notes
+
+- Package/CLI `0.1.71` introduced SQLite schema `14` and analyzer `0.1.71-facts.1`; compact remained `service-flow/compact-graph@1`. Schema 14 adds nullable legacy-safe event-skeleton columns, a nullable repository environment carrier, and the generated-constant table/indexes. Migration marks indexed repositories stale with `schema_v14_event_surface_requires_reindex`; it never reconstructs old event provenance.
+- Event receiver classification first proves a structurally imported `cds.connect.to(...)`/`messaging(...)` reaching assignment in lexical scope. Mixed, branch-dependent, parameter/property propagation, and known non-CAP bindings persist as bounded unproven facts; the historical receiver names are a lower-confidence, countable `name_fallback`, not CAP proof.
+- Event names fold only from stable string consts, enum members, and const-object properties in an exact local/relative module or uniquely proven package public entry. Generated constant facts retain declaration/value offsets, export/stability state, and refusal reasons. Computed access, mutable/non-string values, package duplicates, hidden exports, alias ambiguity, and incomplete surfaces remain non-traversable.
+- Template facts persist a name-independent literal/hole skeleton. Equal skeletons create `EVENT_SHAPE_CANDIDATE_SUBSCRIBER` only when at least one literal span is eight characters or longer; the edge is dynamic, capped, candidates-mode-only, and carries the proven subscriber handler. Canonical positional hole keys supplement the original source-expression keys without replacing them.
+- Repository environment facts currently admit only `SHARD_CODE` from `nodemon.json`, `.env`, `manifest.yml`, and `mta.yaml`. Values retain dev/deployment provenance and source offsets; only declarative case conversion is supported. Duplicate consumer values and within-repository conflicts fail closed, and non-allowlisted adjacent keys are never persisted.
+- Strict doctor now measures unresolved event names, dynamic/event-candidate edges, unmatched publications and subscriptions, receiver proof outcomes, skeleton candidates, and environment ambiguity. Static and runtime-exact bridges expose `workspace_event_name_only` plus their dispatch certainty in detailed/table and bounded compact evidence; this never claims broker, channel, tenant, or payload delivery.
+
+## 0.1.70 source-layout notes
+
+- Package/CLI `0.1.70` removes numeric ordering prefixes from tracked source and test filenames. Runtime behavior and fact compatibility are unchanged, so SQLite remains schema `13`, analyzer `0.1.69-facts.1`, and compact contract `service-flow/compact-graph@1`; no reindex or relink is required solely for this package update.
+
 ## 0.1.69 containment, dynamic event, and compact actionability notes
 
 - Package/CLI `0.1.69`, SQLite schema `13`, analyzer `0.1.69-facts.1`, and compact contract `service-flow/compact-graph@1` remain independent. No SQL migration is needed because `single_hop_helper_return` is carried in validated JSON evidence; all repositories still require `index --force` and `link --force` because generated facts changed.