@nocobase/app-plugin-foundation 0.1.0-beta.5 → 0.1.0-beta.6

package/skills/nocobase-app-plugin-foundation/SKILL.md

@@ -35,12 +35,18 @@ The authentication and authorization plugins are registered, as in the default t
 - Collected read-only by the plugin; nothing reports to it, so there is nothing to register per capability.
 - In use means wired in: a persisted lifecycle, an enabled schedule, a connected mailbox, a configured notification channel, an API key that has been used. Zero uses still count as in use.
 - Needs setup names what is missing in its reason, such as `noChannel` or `noDrive`.
-- Undetermined means the evidence could not be read this time, never that it is unused; the details list what could not be read.
-- AI and agents are in use with an enabled model service or a registered Runner. Native OnlineAgent and model gateway calls do not require an `agAgents` record. Stored Agent definitions and historical usage alone do not prove current configuration. If neither execution path is confirmed and a required read failed, leave the status undetermined. Preserve another confirmed active path when optional statistics fail; never turn a failed read into zero or a missing-configuration claim.
+- Information pending update means the evidence could not be read this time, never that it is unused. Use the top Refresh button to collect again; capability details have no separate retry button. If the initial page request fails with no overview or top Refresh available, use the page's Try again button. Expand the read details for sanitized source notes. Permission denial still hides cached information and offers no retry.
+- AI and agents are in use with an enabled model service or a registered Runner. Native OnlineAgent and model gateway calls do not require an `agAgents` record. Stored Agent definitions and historical usage alone do not prove current configuration. Keep unreadable execution paths as pending subparts so reliable active evidence and metrics can retain their original dates. A successfully read zero invalidates that path's earlier active evidence through subsequent failures. If neither execution path has current or retained active evidence and a required read failed, leave the status undetermined. Preserve another confirmed active path when optional statistics fail; never turn a failed read into zero or a missing-configuration claim.
 - Business record ownership uses `server/catalog.ts`. If an unclassified runtime extension makes ownership uncertain, business counts are withheld; add a supported ownership adapter rather than interpreting them as zero.
 
 ## Verification
 
+The application service keeps reliable active statuses, subpart statuses and complete metrics in memory. Retained values expose their original `checkedAt` and display “Last confirmed”; the overview timestamp is the latest check. Current reliable values take precedence, including zero. Earlier unused or needs-setup states do not become current negative conclusions after a failure. File counts, bytes and table counts require complete candidate discovery as well as successful aggregation to be exact. Without complete history, partial values read “Counted …” and “Some data is pending update”; wholly unreadable values remain pending. A fully confirmed empty catalog still reports exact zero. File facts retained from complete discovery carry their original date as well.
+
+History is service-local, isolated by application and default connection identity, and invalidated conservatively on catalog, physical table, provider/ownership, relevant configuration or readable definition changes. It uses existing reads only. Restarting or replacing the application service clears it; separate server processes have independent histories. There is no persistent data, background collection or automatic retry. Authorization always runs before the service; a browser refresh receiving `401` or `403` hides internal cached values.
+
+The existing deadline preserves evidence completed before another read stalled, including confirmed configuration and partial file statistics. This does not issue a second query or extend the deadline. Late completions cannot replace the response, and queries already in flight retain their shared slots until they settle.
+
 - As the root administrator, `/foundation` shows the capabilities available in this runtime, and `GET /api/foundation/overview` answers `200`.
 - As any other user, the page is not in the menu, and the route answers `403 FOUNDATION_FORBIDDEN`.
 - After adding a Collection, a lifecycle or a notification channel and refreshing, the matching capability changes.
@@ -85,16 +91,30 @@ Literal JSX props, destructured defaults, loader aliases and finite literal arra
 
 Collection evidence uses at most five compact name tags and the total count on the overview. The full catalog opens in a temporary dialog with a bounded scrolling body and fixed pagination controls; opening it does not expand the capability card. Search is debounced by 250 ms and waits for IME composition to finish; Enter applies it immediately. Collection titles and logical names are listed without opening a schema inspector. Closing returns focus to its trigger. Loading, empty search, recoverable failure and denied-access states remain inside the dialog.
 
+## Static association reuse and waiting feedback
+
+Each application service retains at most one compiled association result for 60 seconds. Every new collection validates the files read and the directories used for resolution, including missing alternatives and inherited local alias declarations; changes to application identity, plugin registrations, versions, roots, files or build manifests discard the result. Unreadable evidence is retried on the next collection, without automatic retry requests. TypeScript/TSX source checkouts continue parsing on collection. Entries are bounded to 4,096 filesystem paths, one MB each of path text, registration identity and serialized result; no source text or AST is retained. Oversized or unstable snapshots are not cached. Files beyond the existing parser size limit stay unknown; their metadata remains validated so a smaller replacement is analyzed. Each cache hit costs one metadata check per tracked path; the normal 30-second overview cache needs no additional check. Restarting the service discards this independent in-memory entry.
+
+This reuse affects static dependencies only. Dynamic statistics, reliable history, observation dates, read limits, timeouts and unrestricted authorization keep their existing behavior. There are no additional business queries, writes, warm-up jobs or refresh requests. Cold analysis still takes time. The initial page shows an accessible collecting placeholder with no invented counts; Refresh keeps existing content and dates until the next result, and confirmed counts do not animate from zero again.
+
 ### Overlapping API routes
 
 API associations follow proven Hono registration order, including fluent calls, local registration helpers, ordered API exports and nested mount snapshots. Each matching handler contributes separately. A handler that does not use its `next` parameter ends the chain; a direct unconditional `next()` or `await next()` allows the next matching handler to contribute. Method-specific routes, `all` and `use` middleware retain their chain boundaries. Reached handlers still supply static integration references, including conditional work inside them; these references do not claim that every dependency executes on every request.
 
 Conditional forwarding, opaque middleware factories, uncertain registration paths or order, and request paths that cannot distinguish fixed siblings remain conservative. Keep the proven prefix and other page, access and request evidence, omit downstream contributions whose reachability is unproven, and mark the analysis incomplete. Blank matrix cells remain “not identified”. This is bounded package-local analysis, not a general control-flow interpreter; it never executes application business code.
 
-To apply a correction to an existing deployment, update the consuming application's Foundation dependency, rebuild the application to regenerate `dist/server/foundation-modules.json`, and deploy that build. The artifact format remains compatible and can be read without business source files. Refreshing an old artifact alone cannot apply the correction; do not hand-edit it.
+To apply a correction to an existing deployment, update the consuming application's Foundation dependency, rebuild the application to regenerate `dist/server/foundation-modules.json`, and deploy that build. The updated runtime reads earlier version-1 artifacts and can read the rebuilt evidence without business source files. Update the runtime and CLI together before rebuilding. Refreshing an old artifact alone cannot apply the correction; do not hand-edit it.
 
 Registration tracing stops at direct returns and loop exits. A possible exit in unsupported control flow makes later registrations uncertain, instead of treating the remaining statements or loop iterations as unconditional. Class definitions do not execute instance fields or methods; static initializers remain module initialization, and recognized instance construction stays conservative. Only terminal wildcards establish a certain wildcard match. A fixed suffix can disprove a nonterminal wildcard match; other suffix patterns remain incomplete and cannot contribute certain associations.
 
+### Proven normal-success API paths
+
+The matrix also includes dependencies proven on a normal successful request. This is a limited contract-based analysis: an inline `defineApiRoutes` callback may have one `!app.container.has(databaseManagerToken)` early return followed by a final return of the same router/child mount and literal prefix. Only the database-available side contributes this evidence, with its condition retained. Here availability means the database manager token is registered, not that a connectivity probe succeeded. Before the guard, only local router construction and the framework error adapter are supported. Arbitrary setup, conditions and additional exits remain uncertain. A service constructor alone never establishes a dependency; the matched handler must reference its database work.
+
+Named value imports identify the supported framework middleware only when the existing resolver confirms an external import. A resolved local override or a matching local alias declaration whose target cannot be confirmed never inherits the external framework contract; ordinary local analysis and unknown-path barriers still apply. This provenance check also covers router factories, constructors, error adapters and service tokens. The supported middleware are: authentication resolved from `authenticationToken` with `required()` and no custom options, `bodyLimit`, `describeRoute`, and two-argument `apiValidator` with a literal supported target. The normal-success conditions are database availability, accepted authentication, an accepted body size and successful input validation. Rejection callbacks do not supply downstream success dependencies. Unknown middleware, earlier terminating handlers, dead registrations and method/path mismatches remain barriers. `defineRootRoutes` contributions belong outside `/api`; unknown contribution factories are still barriers.
+
+`moduleSources.routes[].apiEvidence` records the request method and matched API route pattern, providers and symbolic condition sources. An empty condition list distinguishes a proven unconditional prefix; conditional references still appear in `apiProviders` and are explained as successful API requests in the matrix details. These are integration references, not execution counts or a promise that rejected requests access the database. The API schema and version-1 build artifact both carry this additive metadata; older artifacts without it remain readable. Rebuild the application with the updated plugin to preserve conditions in source-free deployments. Static cache validation, dynamic collection, timestamps and unrestricted access keep their existing behavior; no new queries, requests or background work are added.
+
 ### Declared local aliases and finite route constructors
 
 Static discovery reads package-local `tsconfig.json` JSONC `compilerOptions.paths`, including exact keys and single-wildcard keys with one target, relative to the declaring configuration when no explicit `baseUrl` is inherited or declared. A parent configuration without `baseUrl` does not change the directory for a child configuration’s own paths. Relative package-local configuration inheritance is limited to eight files; each configuration is limited to 512 KB. Explicit mappings in a configuration with an external preset are usable, but external presets are never loaded and their inherited mappings are unavailable. Package imports (`#...`) and relative imports retain their existing behavior. Each application and registered plugin uses its own configuration; `@/` is never implicitly mapped to `client`, and ordinary npm scopes remain external packages. Vite configurations and configuration plugins are never executed or inferred.