docs(server): implementation plan for serving client-side knowledge rules (#582)

[halcwb]

Description

Implementation plan for #582: the emergency list, continuous medication list, growth references and localization sheets that the client fetches straight from Google Sheets today are served through the server, so ReloadResources, GetResourceInfo and the #580 scope gate cover them like every other knowledge rule. Calculations stay in the browser; only the data path moves.

Key points:

• A KnowledgeCmd command family (GetEmergencyList, GetContinuousMeds, GetNormalValues, GetLocalization) with matching responses; GetProducts is dropped because State.Products is never read.
• The server extends Resources.defaultRegistry with its own keys and ofResultOrDefault loaders, so a failed or wrong emergency-list workbook is a warning in resource info, never a formulary outage. GenFORM itself gets one function, getCachedProviderWithRegistry, because GenFORM.Lib is Core and may not reference Shared.
• GENPRES_EMERGENCY_URL_ID, defaulting to GENPRES_URL_ID when unset; verified against the public demo workbooks that the emergency tabs are not in the main workbook today while Localization is, and that Google returns the first tab for an unknown tab name, which the parsers' KeyNotFoundException turns into an error rather than wrong data.
• KnowledgePort on AppEnv, four processCmd arms behind requireLoaded; Feature.ofCommand classification with a new Feature.Patient for normal values and localization.
• Stated consequences for the reviewer: sheet edits now need a reload; a fatal formulary load failure also takes the emergency list down (a second provider is the named fallback); docs.google.com leaves the CSP once localization moves.

Six PRs, each under 200 lines. Depends on #580 (plan in #581) only for the scope classification; steps 1 to 3 change no behaviour until the client switches.

Author checklist

• The described changes have already been described in an issue: feat(server): serve the client-side knowledge rules through the server #582
• This PR documents the plan in a markdown file in docs/implementation-plans/.
• I have used the implementation plan template.
• The plan has enough detail: any suggestions that a reviewer adds to a PR that implements the plan are likely to be relatively quick to implement.

Reviewer checklist

• The chosen approach is a good choice.
• The sequence of steps is complete and sensible.
• I have documented resources that may help with implementation.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This documentation PR plans to move emergency medication, growth-reference, and localization data fetching from the browser to an independent, cached server provider.

• Introduces three scoped knowledge commands and a separate localization remoting method.
• Defines an independent KnowledgeProvider, startup loading, reload behavior, configuration, and client migration.
• Revises reload fan-out and feature classification based on prior review feedback.

Confidence Score: 4/5

The plan should not be approved until a throwing knowledge loader can no longer prevent the independent formulary reload.

The previous findings were manually resolved and their documented corrections remain present. One blocking gap remains in the revised reload fan-out: the knowledge callback executes first without specified exception containment, so an unexpected loader exception can stop the GenORDER formulary reload.

Files Needing Attention: docs/implementation-plans/582-server-knowledge-rules.md

Important Files Changed

Filename	Overview
docs/implementation-plans/582-server-knowledge-rules.md	Plans the server-side knowledge-resource migration, but the reload sequence lacks exception isolation between the knowledge and formulary providers.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    C[Client] -->|KnowledgeCmd| D[Command dispatcher and scope gate]
    C -->|getLocalization| A[Server API]
    D --> K[KnowledgeProvider]
    A --> K
    K --> E[Emergency workbook]
    K --> M[Main workbook localization]
    R[ReloadResources] --> O[OrderContextService]
    O --> K
    O --> F[GenFORM provider]

Loading

_{Reviews (3): Last reviewed commit: "docs(server): classify growth references..." | Re-trigger Greptile}

[greptile-apps]

Reloads Are Not Isolated

KnowledgeProvider calls LoadEngine.ForceAll directly, but ofResultOrDefault does not catch exceptions thrown by a loader. Because the plan calls knowledge.Reload() before handing the command to GenORDER, such an exception can stop the formulary reload from running. The reload path therefore does not preserve the intended independence between the knowledge and formulary providers. Add exception containment to KnowledgeProvider.Reload, or otherwise ensure that GenORDER's reload always executes.

[halcwb]

Agreed, fixed in db1fe79. ofResultOrDefault maps an Error from a loader, not an exception, and LoadEngine.ForceAll raises ResourceLoadError itself on a cycle or an unregistered key, so Reload() could have escaped and, running first, skipped the formulary reload.

Two nets now, both in the plan:

• KnowledgeProvider wraps its load in try/with, the way loadAllResourcesWithRegistry wraps its own ForceAll. On an exception it caches a snapshot in which every key holds its empty value and Warnings carries one ErrorMsg with the exception, the same "empty state on error, cached so it is not retried per request" rule that CachedResourceProvider.loadFresh applies. Get, Reload and Warnings never propagate; that is the type's contract, pinned by a step-2 test (a raising loader yields the empty value and the warning, and a Reload after the loader is fixed serves data again).
• The call site in OrderContextService.evaluate wraps knowledge.Reload() in a try/with of its own that logs and continues, so even a provider that broke the contract could not stop the GenORDER reload behind it. A step-3 service test with a stub reload that raises proves the command still reaches GenORDER.

Neither reload can prevent the other, in either direction.