@saptools/service-flow 0.1.68 → 0.1.70

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- Contained invalid prepared-repository snapshots with typed, site-aware diagnostics and repository savepoints. Healthy repositories in the same index invocation publish normally; partial and total failures return bounded summaries and non-zero CLI status, while the final cross-repository invalidation/materialization phase remains atomic.
+- Persisted template-literal `.emit()`/`.on()` topics as runtime-dependent event facts. Missing exact keys produce dynamic candidates and compact-safe missing-variable diagnostics; supplying every emit/subscription key traverses only an exact case-sensitive substituted event-name match.
+- Recognized multi-line `cds.run(...)` structurally and recorded bounded `hasForUpdate: true` evidence on both wrapped and directly executed fluent CQL chains.
+- Added the fail-closed `single_hop_helper_return` binding strategy for a direct connect-derived helper return inside a try block whose catch has no value return or connect. Branching, value-returning/connect-producing catch/finally blocks, and second-hop helpers remain unresolved.
+- Kept `service-flow/compact-graph@1` while rejecting raw control characters before trimming, completing tuple-equivalent status/target elision for non-database-backed target kinds, exposing bounded tied implementation repositories and selector/lifecycle categories, and sourcing safe reason codes from parser warnings. Tuple columns, refs, redaction, and detailed JSON remain unchanged.
+- Package/CLI is `0.1.69`, SQLite remains schema `13`, analyzer compatibility is `0.1.69-facts.1`, and the compact schema remains `service-flow/compact-graph@1`. Existing workspaces require `index --force` followed by `link --force`; no schema migration is required.
+
 ## 0.1.68
 
 - Replaced line-based call and binding ownership with deterministic UTF-16 full-span containment, exact subscription-registration identity, durable handler-reference status, and parser-carried lexical binding-site provenance. Unsupported or ambiguous ownership and reaching assignments now fail closed instead of selecting a convenient same-line row.

package/README.md

@@ -71,7 +71,7 @@ npm install @saptools/service-flow
 - Repository fingerprints include source content, package name/version, dependencies and devDependencies, scripts, normalized `cds.requires` (including nested credentials), package file content, and the analyzer version. Metadata-only changes therefore trigger reindexing.
 - Index publication is designed around the last-good snapshot: failed parse or persistence attempts are recorded as diagnostics and must not be mixed with older graph facts. After indexing changes, relink before relying on graph/trace output; doctor reports stale or inconsistent stores where detectable.
 - Source discovery, file reads, hashing, parsing, and publication are all inside the repository-level protected indexing flow. A failed read keeps the previous fingerprint and facts, marks the repository failed, and records a `source_read_failed` diagnostic; a later successful index clears superseded read-failure diagnostics during fact publication.
-- Index preparation remains deterministic and sequential. Each source file and `package.json` is read once into a repository-scoped immutable snapshot, and all TypeScript parser entrypoints share one lazy AST for that file. Source snapshots are released after repository preparation; prepared facts still publish together in the existing workspace transaction.
+- Index preparation remains deterministic and sequential. Each source file and `package.json` is read once into a repository-scoped immutable snapshot, and all TypeScript parser entrypoints share one lazy AST for that file. Publication uses one savepoint per repository inside the workspace consistency transaction: an invalid prepared snapshot rolls back and diagnoses only that repository, while the final package-invalidation/materialization pass remains workspace-atomic.
 - Index writers are coordinated per SQLite database with a short atomic claim. A second writer fails with `index_writer_active`; a claim that remains SQLite-locked past the bounded wait reports `index_writer_coordination_failed`. A dead owner or sufficiently old legacy ownerless row is reconciled before a new claim. `clean`, including `--db-only`, uses the same claim and removes only exact SQLite sidecar files. Normal failures finalize their run row, while read-only list, trace, inspect, and doctor commands remain usable whenever the short publication transaction is not active.
 - Normal successful database commands on supported Node 24 runtimes suppress the known `node:sqlite` experimental warning so JSON stdout remains parseable and stderr-clean. Real service-flow errors still use stderr and non-zero exit codes.
 - Doctor treats a `running` index run as abandoned only after 60 minutes and includes the run id/start time. Active short-lived concurrent runs are not default warnings.
@@ -80,13 +80,17 @@ 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.
 - 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.
+- One-hop derived import calls retain the import and target-declaration identities separately. Relative default-class instances resolve only when the exact requested module contains the matching declared class method and marks that class as the default export; package-derived members never fall through to a coincidental same-file name. A relative object shorthand that points onward to a package stays visibly unsupported, and every unresolved or ambiguous symbol-call fact is rendered as a non-traversable trace edge.
+- Structural `cds.run` recognition is insensitive to source-line formatting. Query evidence records `hasForUpdate: true` when the proven fluent CQL chain contains `.forUpdate(...)`, without inspecting or retaining the lock argument.
+- A local deterministic helper may contribute a service binding through one direct return of `cds.connect.to(...)` or `cds.connect.messaging(...)`, including a try block whose catch only logs and swallows the error. The evidence strategy is `single_hop_helper_return`; branching, a returning/connect-producing catch or finally block, and second-hop helpers remain fail-closed.
 - 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.68` uses analyzer `0.1.68-facts.1`, so 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 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.70` keeps schema 13 and analyzer `0.1.69-facts.1`; the filename-only package update requires no new reindex or relink. Read-only commands report bounded schema/reindex diagnostics and link preserves the last good graph until both passes succeed.
 
 
 ## 🚀 Quick Start
@@ -114,7 +118,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.68 upgrades the database to schema 13 and changes the fact analyzer to `0.1.68-facts.1`. A migrated database deliberately leaves legacy binding spans/public surfaces null and binding ownership `legacy_unknown`; call ownership, package exposure, placeholder, and OData evidence are never fabricated. Refresh facts and graph edges before tracing:
+> Version 0.1.70 keeps database schema 13 and fact analyzer `0.1.69-facts.1`; removing filename ordering prefixes does not change persisted facts. Workspaces already refreshed for analyzer `0.1.69-facts.1` need no additional reindex or relink. Workspaces on an older analyzer still require:
 >
 > ```bash
 > service-flow index --workspace /path/to/workspace --force
@@ -472,7 +476,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.68-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":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":[]}
 ```
 
 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.
@@ -481,7 +485,9 @@ Each compact edge's `traceOrdinals` contains the zero-based detailed edge index
 
 The edge tuple's `status` and `to` cells are the canonical effective decision. Optional `details.decision.effectiveResolutionStatus` and `effectiveTarget` are omitted only when they were derived from those exact same canonical values; label equality is insufficient. Differing persisted status/target decisions, counts, reason codes, and references remain. Each reference group retains at most 5 values with `total`, `shown`, and `omitted`; missing-variable projection retains at most 8 safe names, each at most 160 UTF-16 code units.
 
-Detailed/runtime artifacts retain the arbitrary full trimmed placeholder key. Compact output accepts an ASCII identifier (`[A-Za-z_$][A-Za-z0-9_$]*`), followed by zero or more direct/optional ASCII identifier members or non-negative decimal numeric element accesses, and optionally one final zero-argument `toLowerCase`, `toUpperCase`, or `trim` transform. Unsafe or overlong keys remain counted in `missingVariableCount` and `omittedMissingVariableCount` and are available through the correlated detailed edge/diagnostic; compact never executes or partially evaluates them.
+An ambiguous implementation decision with more than one candidate may include `tiedCandidateRepos` only when more than one uniquely attributable repository exists. Compact start diagnostics may likewise include bounded `selectorSuggestions`, a short `selectorKind`, or bounded `invalidFactCategories`. Each of these optional reference groups uses the same 5-value cap and truthful `total`/`shown`/`omitted` counts. They contain only allowlisted codes or safe identifiers; detailed JSON remains authoritative for full candidate and lifecycle evidence. Implementation-hint remediation lists the accepted `service`, `operation`, `package`, `repository`, `family`, and required `repo` keys.
+
+Detailed/runtime artifacts retain the arbitrary full trimmed placeholder key. Compact output accepts an ASCII identifier (`[A-Za-z_$][A-Za-z0-9_$]*`), followed by zero or more direct/optional ASCII identifier members or non-negative decimal numeric element accesses, and optionally one final zero-argument `toLowerCase`, `toUpperCase`, or `trim` transform. Raw control characters are rejected before surrounding-space normalization, so a leading or trailing control cannot be trimmed into a displayable name. Unsafe or overlong keys remain counted in `missingVariableCount` and `omittedMissingVariableCount` and are available through the correlated detailed edge/diagnostic; compact never executes or partially evaluates them.
 
 `source.analyzerVersion` is the one persisted analyzer value for the selected scope. It is `none` when no repositories exist, `mixed` when multiple analyzer versions are present, and `legacy_unknown` when the persisted value is absent. Reindex before relying on topology whenever the source reports a sentinel rather than the current analyzer.
 

package/TECHNICAL-NOTE.md

@@ -1,5 +1,18 @@
 # Service Flow Resolution Notes
 
+## 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.
+- Prepared-snapshot failures use a closed typed error and repository site. Workspace indexing contains those failures with one repository savepoint, commits healthy siblings, writes one bounded diagnostic for each failed repository, and finishes the run as `success`, `partial_failure`, or `failed`. Unexpected cross-repository materialization/invalidation failures still roll back the outer workspace transaction.
+- Relative default-class method resolution compares the caller's default binding to target-side default-export evidence, while current-fact proof uses the caller's local identifier. Package-derived members have no same-file fallback, package-backed relative proxy aliases carry an explicit unsupported reason, and unresolved/ambiguous symbol calls remain visible but non-traversable in traces.
+- Event template expressions are persisted without evaluation. Missing exact keys create dynamic event candidates; a trace traverses only after emit and subscription templates are both fully substituted and their concrete names match with binary case sensitivity.
+- CQL dispatch recognizes `cds.run` structurally across whitespace and records only the bounded `hasForUpdate: true` fact for a proven lock modifier. One direct helper-return hop may preserve connect-derived service bindings through a non-value-producing catch, with explicit helper-chain provenance and lifecycle validation.
+- Compact v1 rejects controls before trimming missing names, uses intra-edge canonical identity to remove complete tuple-equivalent persisted/effective decisions for every safe target kind, and retains genuinely different decisions. Rare ambiguous/start/lifecycle diagnostics gain bounded repository, selector, and invalid-category reference groups. A parser warning contributes its allowlisted `code`; the generic `parser_warning` sentinel instead uses an allowlisted `message` code, while arbitrary free text remains omitted.
+
 ## 0.1.68 exact provenance and structural runtime notes
 
 ### Fact identity and schema lifecycle