# Choose, refactor, and extend BLOGE capabilities ## When to use Use when choosing an expression, simplifying conditions, extracting reuse, or adding a function or Operator. Read the [practice reference](/agent/en/v/0.9.9-RC1/reference/coding-practices.md) and select applicable BP entries. ## Inspect first - Record the effective BLOGE version, deployed function registry/catalog, Operator registrations, conventions, and tests. - List facts, approved answers, output consumers, external actions, and failure boundaries. - Check null, types, ordering, numeric behavior, locale, time, and ID semantics. Matching names do not establish equivalence. - Instance functions support external reads. Independent control requirements, rather than a syntax restriction, usually justify an Operator. ## Required inputs Obtain intended behavior, input/output contract, effects, determinism, scale/cost limits, reuse consumers, maintainer, and authorized change scope. Policy changes require approved answers; report missing answers instead of generating them from the candidate. ## Implementation path 1. Prefer binding for field access, existing functions for lightweight general computation, and transforms for named projections (BP-01). 2. Extract a helper for bounded computation; register a typed function only when graph authors need it, with explicit arguments and contracts (BP-02). 3. Prefer an Operator for independent retry, timeout, replacement, observations, or capacity. Compose existing steps in graphs/subgraphs (BP-03, BP-12). 4. Evaluate a decision table for interacting facts; route on its result. Choose priority, exclusion, agreeing matches, or collection semantics explicitly (BP-06, BP-07). 5. Decide ownership separately: application, team library, optional module, core. Public proposals need cross-domain semantics, a composition gap, edge contracts, bounded cost, ownership, and compatibility (BP-04, BP-05). 6. Preserve outputs, dependencies, business identity, fallback, recovery, and resource boundaries. Coordinate retry layers rather than compounding them (BP-08 through BP-13). 7. Check fixed answers and full before/after outputs. Observe unselected paths and forbidden effects separately, then inject a revealing mutation (BP-14). 8. Deliver a proposal for public extensions. Application refactoring does not authorize changes to BLOGE core or connector publication. ## MUST / SHOULD / MAY - **MUST** inspect actual registrations; do not invent functions, Operators, or DSL fields. - **MUST** report expression form, execution responsibility, maintenance scope, and rejected alternatives. - **MUST** preserve policy priority, schemas, business identity, and unknown external outcomes; metadata does not prove behavior. - **MUST** use independent expected answers for routing and effects, not current candidate outputs. - **SHOULD** review decision tables for more than three independent conditions. This is not mandatory migration or lint. - **SHOULD** prefer an Operator for independently controlled I/O or expensive pure computation. - **MAY** retain a clear domain method or a documented external-read function whose evaluation and consistency boundaries fit. ## Failure patterns - A blacklisted high-score application is approved: inspect first-hit order. A unique-policy conflict is not equivalent rejection. - Collect always includes the normal explanation: current otherwise unconditionally appends. - Stable keys still produce repeated effects: inspect provider/application deduplication; EffectPort key declarations do not suppress calls. - A helper is promoted prematurely: first show independent consumers, shared semantics, and a concrete composition gap. - A universal Operator has unrelated modes: separate wiring, provider adaptation, and different business guarantees. ## Validation Run the [workshop Maven project](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/README.md). Twelve fixed examples compare seven risk fields, all eight review-form fields, routes, and simulated action counts; six tests cover rule order, Oracle replacement, unique, collect, typed functions, and EffectPort. Four funding tests cover explicit credit querying, response-loss retry, timeout reconciliation, key/amount conflict, and paired hidden-read/stacked-retry refactoring. Compare nine calls before with three after while retaining the same committed effect. One recovery test creates three successive managers: counts remain 1, 2, 3 until a new round commits, then reset to zero. Expect 23 workshop passes without skips; this does not prove production capacity or real-provider behavior. Run `run-runtime-seams.sh` from the same asset directory for recovery progress, lease permission, stale checkpoint rejection, and actual worker capacity; its report gate requires nonzero execution without skips or failures in all four suites. Validate target port contracts, recovery, and dependencies separately. Report changed files, rationale, actual commands and test counts, and unverified scope. Do not reuse workshop results as evidence that target tests ran. ## Evidence - [Coding handbook](/en/v/0.9.9-RC1/appendix-j-coding-practices). - [Integrated workshop](/en/v/0.9.9-RC1/34-labs). - [Typed function](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/java/com/leanowtech/bloge/book/practices/LoanTextFunctions.java). - [Refactored DSL](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/resources/loan-after.bloge). - [Fixed answers](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/resources/oracles.csv). - [Executable tests](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/test/java/com/leanowtech/bloge/book/practices/CodingPracticesTest.java). - [Execution refactor](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/test/java/com/leanowtech/bloge/book/practices/FundingBoundaryTest.java). - [Repeated takeover](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/test/java/com/leanowtech/bloge/book/practices/SessionRecoveryPracticeTest.java).