@saptools/service-flow 0.1.72 → 0.1.73

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.73
+
+- Repaired the schema-14 writer/validator contract: resolved empty string constants remain legal facts, empty event topics fail closed at use, and const-alias templates retain complete signed skeletons. Lifecycle failures now use the actual workspace path and expose bounded repository/file/line/predicate examples without replacing the last good graph.
+- Separated event-name resolution from receiver proof. Static names retain canonical event identity while receiver confidence remains disclosed; single proven CAP-connect assignments inside branches are accepted, affirmative non-CAP proof wins over name compatibility, and comments or string contents cannot seed receiver evidence. Known socket, stream, desktop, and CAP CRUD handler calls stay outside EventMesh aggregates.
+- Refused partial folding for spread/computed/getter/shorthand constant containers, accepted type-position references as immutable uses, materialized complete loop registrations, bounded link-time skeleton fan-out, deduplicated equal dispatch decisions, and completed bounded doctor reason-bucket counts.
+- Made event environment keys configurable through `eventEnvironmentKeys` in `.service-flow/config.json`, while preserving the default, grammar/cap, provenance, transform, ambiguity, fingerprint, and neighbouring-key exclusion guarantees. Repository inspection omits stored declaration values and environment-file fingerprints hash only allowlisted derived facts.
+- Package/CLI is `0.1.73`, SQLite remains schema `14`, analyzer compatibility is `0.1.73-facts.1`, and compact remains `service-flow/compact-graph@1`. Parser facts changed, so existing workspaces require `index --force` followed by `link --force`.
+
 ## 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.

package/README.md

@@ -80,11 +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-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.
+- Event receiver analysis structurally proves CAP-connect declarations and reaching assignments, including later assignment, destructuring, control-flow nesting, and formatter-split chains. Mixed assignments remain unproven, visible non-CAP declarations and known socket/stream/desktop receivers are excluded, and historical receiver names remain only as explicit lower-confidence `name_fallback` evidence. Static event-name identity and exact name-only subscriber traversal remain available across an unproven propagation receiver; the receiver uncertainty stays explicit in confidence and 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.
+- Repository environment declarations are allowlisted facts. The schema-14 analyzer reads the configured `eventEnvironmentKeys` (default `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, unsupported transforms, and package-indirect references remain explicitly ambiguous/refused; 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.
@@ -94,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 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.
+- 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.73` uses analyzer `0.1.73-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
@@ -121,8 +121,21 @@ 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`.
 
+To allow additional non-secret event prefix declarations, edit
+`.service-flow/config.json` and keep the shipped default or add keys:
+
+```json
+{
+  "eventEnvironmentKeys": ["REGION_CODE", "SHARD_CODE"]
+}
+```
+
+Keys must match `[A-Z_][A-Z0-9_]{0,63}` and the list is capped at 16.
+Only listed keys are read into facts; changing the list changes repository
+fingerprints. Run `index` and `link` after editing it.
+
 > [!IMPORTANT]
-> 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:
+> Package `0.1.73` keeps schema 14 and advances fact compatibility to analyzer `0.1.73-facts.1`. Event receiver, name-axis, constant, skeleton, loop, and environment configuration semantics changed, so every existing workspace requires:
 >
 > ```bash
 > service-flow index --workspace /path/to/workspace --force
@@ -439,7 +452,7 @@ service-flow init /path/to/workspace --db /custom/path/service-flow.db
 ## 🔐 Security & Redaction
 
 - The analyzer reads static source files and package metadata only.
-- It does **not** execute CAP services, load `.env` files, call SAP BTP, or connect to remote systems.
+- It does **not** execute CAP services, apply `.env` values to the analyzer process, call SAP BTP, or connect to remote systems. It reads only configured event-environment keys from supported static declaration files as bounded facts.
 - Persisted summaries and CLI output redact keys that look like credentials, including `authorization`, `cookie`, `token`, `secret`, `password`, `key`, and `credential`.
 - Payload bodies are summarized for traceability; runtime payload values are not required for indexing.
 - Compact JSON is projected through a field-by-field allowlist. It omits raw parser/outbound evidence, candidate and score bodies, payloads, call arguments, helper-chain bodies, supplied variable values, and arbitrary diagnostic/remediation text. Query metadata contains supplied variable names only; `runtimeValuesOmitted` is always `true`, so exact replay requires the original supplied values retained by the caller.
@@ -480,7 +493,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":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":[]}
+{"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.73-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,14 @@
 # Service Flow Resolution Notes
 
+## 0.1.73 event fact-contract repair notes
+
+- Package/CLI `0.1.73` keeps SQLite schema `14` and compact `service-flow/compact-graph@1`, while advancing analyzer compatibility to `0.1.73-facts.1`. Receiver/name facts, alias skeletons, constant safety, loop materialization, and environment-key configuration changed; existing workspaces require `index --force` and `link --force`.
+- Event receiver proof accepts a single structurally proven CAP-connect reaching assignment regardless of enclosing control-flow syntax. Mixed reaching values remain unproven, visible non-CAP declarations are never laundered through compatibility names, and the name fallback retains its refused-proof reason.
+- `outbound_calls.unresolved_reason` is event-name-only for event facts. Receiver proof remains bounded evidence that affects confidence and disclosure, so a static event name keeps canonical `event` identity even when receiver propagation is unproven.
+- Empty strings are valid generated constant values but invalid event topics. Alias-resolved templates derive their signed skeleton from the resolved opaque template text; no placeholder expression is evaluated.
+- Workspace configuration may add up to 16 event environment keys using `eventEnvironmentKeys`. Only keys matching `[A-Z_][A-Z0-9_]{0,63}` are admitted; adjacent keys remain excluded, and changing the configured set invalidates repository fingerprints.
+- Lifecycle diagnostics distinguish stale facts from invalid current facts, use the configured workspace path, and provide bounded repository/file/line/predicate examples. Event-shape fan-out and doctor reason groups have truthful shown/omitted counts.
+
 ## 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.
@@ -188,7 +197,7 @@ Schema version 6 adds queryable external target metadata columns to `outbound_ca
 
 ## 0.1.18 auditability notes
 
-- CAP async event parsing treats `.emit()`, `.publish()`, and `.on()` consistently: a row is indexed only when the direct or chained root receiver has explicit CAP service or messaging evidence such as `cds` or a variable initialized from `cds.connect.to(...)`. Generic realtime/socket/EventEmitter receivers are ignored for CAP graph purposes by default.
+- CAP async event parsing treats `.emit()`, `.publish()`, and `.on()` consistently. Current analysis first proves lexical CAP-connect assignments, retains explicitly labelled fallback/provenance evidence where supported, and excludes known realtime/socket/stream/desktop receivers and CAP CRUD handler registrations from EventMesh facts.
 - Local CAP service calls now carry TypeScript AST evidence with classifier, source offsets, service lookup/name, operation, and alias chain.
 - Call-derived graph evidence nests persisted outbound parser evidence as `outboundEvidence`, allowing JSON trace output to explain parser classification without colliding with linker fields.
 - `graph_edges.is_dynamic` means the edge itself requires runtime operation-target resolution. Terminal database, external HTTP, and async event edges keep `is_dynamic=0`; dynamic binding provenance remains in `evidence_json.bindingHasDynamicExpression`.
@@ -266,7 +275,7 @@ Schema version 6 adds queryable external target metadata columns to `outbound_ca
 
 ### 0.1.17 parser ownership policy
 
-Outbound call extraction is AST-based and ignores comments, block comments, and string literals. CAP/service `.on(...)` registrations are indexed only when the receiver has CAP/service evidence, and top-level registrations receive `module:<relative-file>#event:<event-name>:<line>` synthetic owners. Generic event emitters such as desktop or window events are ignored by default rather than guessed as CAP async edges. Unsupported source shapes are surfaced through diagnostics and strict doctor ownerless categories instead of guessed graph edges.
+Outbound call extraction is AST-based and ignores comments, block comments, and string literals. CAP/service `.on(...)` registrations use lexical receiver proof or explicit compatibility/provenance evidence, and top-level registrations receive `module:<relative-file>#event:<event-name>:<line>` synthetic owners. Generic event emitters such as desktop, window, socket, and stream events are ignored rather than guessed as CAP async edges. Unsupported propagation remains typed evidence instead of silently becoming CAP proof.
 
 
 ## 0.1.35 OData placeholder semantics