Plan · Formulation - Formulas : use a pre-mix as an ingredient, with its price, its (+) detail and "Not included" (frontend + backend + db)

Selected

A1

Architecture

TARGET, LAYER BY LAYER. Everything below is on the existing ticket branch; the approved design document on the branch is the normative source for the DDL and must not be redesigned (E25). 1. SCHEMA (slice 1, db-engineer). One Flyway file, V035__Add_Premix_Reference_And_Not_Included_To_Formula_Phase_Line.sql, transcribed from the design document's ALTER on formula_phase_line: premix_formula_id UUID NULL with a foreign key to formula(id) and an explicit ON DELETE RESTRICT; not_included BOOLEAN NOT NULL DEFAULT FALSE (the DEFAULT is what lets the ALTER run on populated rows); not_included_level VARCHAR(20) NULL. Five named CHECKs, each with its IS NOT NULL guard: never both references, no direct self-reference (premix_formula_id <> formula_id), no picked batch on a pre-mix line, the level restricted to THIS_PREMIX and FINAL_FORMULA, and a level only when the flag is set. One index, idx_formula_phase_line_premix_formula_id, which the RESTRICT check, the tree walk and the usage reconciliation all need. Nothing else: no kind column (the work request and design decision D2), no new table, no reference-data entity. V034 is the highest version at the indexed base (E30); the builder confirms the number against main before authoring. 2. ENTITIES (slice 1). FormulaPhaseLine gains premixFormula (@ManyToOne LAZY on premix_formula_id, to Formula), notIncluded (@Builder.Default false, nullable=false) and notIncludedLevel (@Enumerated(STRING), length 20), plus a new enum NotIncludedLevel {THIS_PREMIX, FINAL_FORMULA} in domain/formula - the two codes the mock already exchanges (E22). ddl-auto is validate, so the fields and the migration land together (E6). findCompositionByFormulaId adds LEFT JOIN FETCH on the referenced formula so mapping never lazy-loads (E32). 3. READ CONTRACT (slice 2). FormulaLineResponse drops kind and gains premixFormulaId (UUID, null on a raw-material or empty line), premixCode and premixName (String, "" when absent, matching the record's existing "" convention for commercialName), notIncluded (Boolean) and notIncludedLevel (String code or null). FormulaCompositionMapper loses LINE_KIND_RAW_MATERIAL and fills the pre-mix trio from line.getPremixFormula() (E3, E4). FormulaCompositionServiceTest loses the one kind assertion (E5). This completes the human work request's backend half; no replacement discriminator of any name is introduced anywhere - the reference field is the answer. 4. WRITE CONTRACT (slices 2-3). UpdateFormulaLineRequest gains premixFormulaId, notIncluded and notIncludedLevel as plain nullable components, following the record's documented full-replacement carve-out (E20). AddFormulaLineRequest gains the same three so a line can be created already holding a pre-mix. applyValues is extended to apply the two references mutually exclusively - assigning a pre-mix clears the raw material and the picked batch, assigning a raw material clears the pre-mix - so a mixed edit returns the rule's message instead of hitting the CHECK (E13). 5. RULES (slice 3), all in FormulaCompositionService, each a BusinessRuleException with a new messageKey: (a) a line holds at most one reference, with the preview's wording; (b) the referenced formula exists and is_premix is true; (c) nesting depth at most 5, walking the referenced formula's lines; (d) no cycle - a depth-first walk from the edited formula over premix references that accepts a shared sub-pre-mix reached twice by different paths and refuses only a genuine loop, which is the behaviour the mock review demanded; (e) on a formula that is itself a pre-mix, a ticked line requires a level, and on any other formula the level must be null; (f) a pre-mix line carries a typed lot only, never a picked batch. The depth, cycle and both-references messages reproduce the preview's text verbatim (E21) so the message does not change between the optimistic refusal and the server's, in messages.properties and messages_fr.properties next to the existing exception.formula.line.* keys (E29). Errors propagate to GlobalExceptionHandler as ProblemDetail; nothing is caught broadly. 6. USAGE RECORD (slice 4). One writer: a private reconcile(formulaId) in FormulaCompositionService that makes the formula's formula_premix_use rows equal the distinct non-null premixFormulaId values of its lines, using findByFormula_Id (E9). Called after addLine, updateLine, deleteLine and after copyComposition. copyLines' explicit column list gains premix_formula_id, not_included and not_included_level, keeping lot and batch deliberately uncopied (E12), and copyComposition then reconciles the duplicate (E14). GET /v1/formulas/{id}/daughters and the flag-off guard are untouched and start reporting the truth (E10, E11), which is AC10 end to end and what makes the alert count move from 2 to 1. 7. THE isPremix FLIP (slice 5), in FormulaService#applyPremixChange (E11): turning the flag off clears notIncludedLevel on that formula's lines, since the level is meaningless there; turning it on is refused, with its own message key, while a ticked line has no level. This is the behaviour the approved design states for its open item on the flip; it is adopted, not invented here. 8. READ ENDPOINTS (slices 6-7). - GET /v1/formulas/premix-candidates?q=&siteId= on FormulaController, served by FormulaService over formula.is_premix (E19, E31): no status filter, so a pre-mix in Development is offered (AC1); each row carries code, name, status code, label and colour and the pre-mix's own total as entered, computed as the sum of its filled non-QSP line percentages plus a filled QSP line's derived share. It mirrors the raw-material candidate endpoint's parameters and ranking (E17) so the grid merges two ranked lists exactly where the mock merges them today (E24); the live raw-material search is not touched. - GET /v1/formulas/{formulaId}/premix-tree?premixFormulaId=&siteId= on FormulaCompositionController (E15), served by FormulaCompositionService: a depth-first walk of the referenced formula's lines capped at 5 levels, each node carrying its path, depth, share in its own pre-mix, the referenced name, whether the node is itself a pre-mix, its aggregated INCI, its pricePerUnit, currencyCode and unitCode at the requested site, and its own notIncluded pair. {formulaId} is the formula being edited and siteId is the site it is being read at, so the same pre-mix prices differently at another site (AC2, AC3); prices and INCI come from RawMaterialSiteDataService, which already resolves exactly these fields per site (E18). The percentage in the final formula is the line's percentage multiplied along the path, as the mock computes it. - The server serves figures, not verdicts: the dash with its reason and the excluded count stay in the one client-side cost calculation that already owns MP-690's exclusion reasons (E26), so AC4's foreign-currency, no-price and wrong-unit cases are the existing reasons applied to pre-mix nodes, and AC5's not-100% warning stays a client-side reading of the served total. 9. THE FLIP (slice 9, frontend-engineer). api/formula-premix.ts becomes apiClient calls against the endpoints its TODO(MP-691) markers name, keeping its refused-result shape by mapping a 400 ProblemDetail detail into { outcome: "refused", message } so the hook's toast-and-revert path and every component stay as they are (E24). lib/mock-premix-data.ts is deleted with its three preview devices, which is what removes the three mock-stage limits the ticket requires gone: a line can be added after a pre-mix line, no demo lines are seeded into every formula, and the daughters alert lists only real formulas (E23, E27). api/formula-composition.ts's line mirror gains the five new fields and loses nothing else; use-formula-description reads the live daughters endpoint instead of the fixture. The single pre-mix predicate over premixFormulaId stays the only derivation site (E28). 10. TESTS (slice 8). FormulaCompositionServiceTest for each rule and for the reconciliation; FormulaServiceTest for the flip; a repository H2 IT for the migration and its five CHECKs, following the existing H2 IT naming; a Keycloak and Postgres controller IT for the two new endpoints covering 401, validation and the i18n of each new message. The gate is ./gradlew --no-daemon spotlessCheck and ./gradlew --no-daemon test, then npm run build and npm run lint after the flip (AC13). DATA FLOW. Grid cell search -> formula-candidates plus premix-candidates, merged client-side -> PUT or POST on the line with premixFormulaId -> service rules -> line row plus reconciled usage rows -> composition response with the pre-mix trio -> (+) opens premix-tree at the current site -> client cost calculation renders the price, the dash with its reason, the footer count and the not-100% warning. ERROR HANDLING. Rule refusals are BusinessRuleException (400) with a messageKey present in both message files; a missing formula, line or referenced pre-mix is ResourceNotFoundException (404); every composition write stays behind the existing locked-status refusal (E14). Nothing new is caught or swallowed in the api layer: a refusal becomes the mock's refused result, any other failure keeps the existing error path.

Rationale

The code leaves little room for anything else and the two earlier stages fixed the rest. There is exactly one composition line table, one line entity, one mapper, one write service and one locked-formula guard (E6, E7, E13, E14, E15), so a second family (A2) would duplicate the ordering, locking and audit logic and split the single-reference rule across two writers. The approved DB design stores nothing derived and was approved on that basis (E25), prices are per-site and already resolved per site (E17, E18), and AC3 makes that site-dependence observable - so A3 would both contradict the approved schema and be wrong at the second site. The accepted mock is the API contract: two level codes (E22), a depth of 5 with three exact messages the backend must reproduce (E21), a refused-result error shape and one TODO(MP-691) marker per function naming its endpoint (E24); A1 is the only shape that lets the flip change no hook and no component. AC10 needs the usage record written, not redesigned: the table, its repository and its only reader already exist (E8, E9, E10) and the flag-off guard becomes effective the moment rows appear (E11). Finally, the human work request's backend half is unavoidably part of this stage: kind is still on the response, in the mapper constant and in one test assertion at the base (E1, E2, E3, E4, E5), and no routine before this one may touch backend/.

Design by area

This is a flip, not a redesign. The mock pair is the only place that knows the data is fake (E23, E24), which is what makes the change one greppable pair of files plus the line mirror.

1. api/formula-premix.ts. Each exported function becomes the apiClient call its TODO(MP-691) marker names: the pre-mix half of the ingredient search to GET /v1/formulas/premix-candidates, the (+) tree to GET /v1/formulas/{formulaId}/premix-tree with the pre-mix and the current site, and the daughters read to the live endpoint. searchCompositionCandidates keeps its current structure: it already reuses MP-690's live raw-material search unchanged and merges the pre-mix half into the ranked result (E24), so only the pre-mix half's source changes and the merge stays where it is. The refused-result contract is preserved: a 400 ProblemDetail becomes { outcome: "refused", message: <detail> }, so the hook's existing toast-and-revert path and the one-cell revert need no new branch, and a thrown error stays reserved for a genuine network or server failure. The site-slot device goes: the real siteId is passed through, which is what makes AC3 real rather than simulated.

2. lib/mock-premix-data.ts is deleted. Nothing else imports it, and its three devices go with it (E23): price slots assigned in first-seen order, one demo pre-mix line seeded into every formula at 1% in its own phase, and a usage record derived from the formula's own lines. Deleting it is what removes the ticket's three mock-stage limits and restores every formula's own total.

3. api/formula-composition.ts. The local line-response mirror and the line mapping gain the five new fields so the grid reads them from the live composition; the endpoint, its path and every other mapped field stay as they are, and no discriminator is reintroduced in any form.

4. use-formula-composition.ts. The mock overlay merge is removed where it injected mocked lines and line state, leaving the hook as the single owner of the composition's data reading one live response. Its refusal contract and its optimistic revert are unchanged.

5. use-formula-description.ts. listMockDaughters is replaced by the live daughters read; components/premix-impact-alert.tsx is not modified, and the page's refresh on the set of premixFormulaId values keeps working as written (E27).

6. Untouched on purpose: lib/composition-math.ts (the one cost calculation, including the dash with its reason, the exclusion reasons and the footer count), lib/premix-rules.ts (kept as the optimistic preview whose messages now match the server's word for word), the single pre-mix predicate over premixFormulaId (E28), premix-detail-rows.tsx, not-included-level-dialog.tsx, premix-badge.tsx, the column definitions and every page and route. If a served field name differs from the mock's, the DTO is renamed on the backend side rather than the component adapted - the mock is the contract.

7. Gate: npm run build and npm run lint in frontend/, then a pass on the preview against a real pre-mix - the price at two sites, the dash cases, the not-100% warning, the (+) tree to 5 levels, the empty INCI cell, the free-text lot, the two refusals and the level question - which is also what the Fullstack Review judges for AC-E1 and AC-E2.

The schema work is transcription, not design: the DB stage's document on the branch is the normative source and was approved at DB Review; this stage authors the migration it deliberately left out (E25).

FILE. backend/applications/cosmoreg-core/src/main/resources/db/migration/V035__Add_Premix_Reference_And_Not_Included_To_Formula_Phase_Line.sql. V034 is the highest version at the indexed base (E30), so V035 is next free; the builder re-checks the number against main before authoring, because another ticket's migration may have landed meanwhile.

COLUMNS on formula_phase_line (E6, E7).
- premix_formula_id UUID NULL, foreign key to formula(id) with an explicit ON DELETE RESTRICT, matching the table's existing raw-material and batch foreign keys and the guarantee that a pre-mix still used by a line cannot be deleted.
- not_included BOOLEAN NOT NULL DEFAULT FALSE. The DEFAULT is what makes the ALTER safe on populated rows; every existing line reads false, which is the behaviour before this ticket.
- not_included_level VARCHAR(20) NULL, a code set fixed by a CHECK rather than reference data - the design's deliberate, reviewed deviation, approved at the gate.

CHECKS, each named and each carrying its IS NOT NULL guard so it never fires on a legal NULL (the pattern the table already uses, E7).
- chk_formula_phase_line_single_reference: a line never holds both references. 'Neither' stays legal, because MP-690 creates an empty line with no raw material, and no new constraint is added for it - the ticket's reference rule and the work request both say so.
- no direct self-reference: premix_formula_id IS NULL OR premix_formula_id <> formula_id. The indirect cases cannot be a row-level CHECK and stay service rules.
- no picked batch on a pre-mix line: premix_formula_id IS NULL OR rawmaterial_batch_id IS NULL, which is the Lot-is-free-text-only rule for a pre-mix line.
- the level's value set: not_included_level IS NULL OR not_included_level IN ('THIS_PREMIX', 'FINAL_FORMULA') - exactly the two codes the mock exchanges (E22).
- the level needs the flag: not_included_level IS NULL OR not_included.
For each CHECK the file states its allowed, rejected-by-value, rejected-by-NULL and unaffected cases, as the design document does.

INDEX. idx_formula_phase_line_premix_formula_id. The table's existing indexes lead with formula_id, rawmaterial_id and rawmaterial_batch_id, so none serves a lookup by the new reference, which the foreign key's RESTRICT check, the level-by-level price walk and the usage reconciliation all perform.

REUSED UNCHANGED. formula_premix_use (V028) keeps its columns, its two foreign keys, its unique pair and its two indexes (E8); this stage gives it its single writer in the service layer, which is what makes the existing daughters reader and the flag-off guard truthful (E9, E10, E11). formula.is_premix and its partial index are untouched and simply queried by the candidate endpoint (E31). rawmaterial_site keeps serving per-site prices (E18).

NOT IN THE SCHEMA, deliberately. A line's resolved price and its reason, a node's share, the percentage in the final formula, a pre-mix's total, its code, name and INCI: all read-time results. The 5-level depth limit, indirect cycles, 'neither reference on a filled line', 'the referenced formula is a pre-mix' and 'the level is required on a pre-mix formula' span several rows or tables and stay service rules, each with the message the design lists.

ENTITY MAPPING (ddl-auto is validate, so it ships with the migration). FormulaPhaseLine gains premixFormula as a LAZY @ManyToOne on premix_formula_id, notIncluded as a non-null Boolean defaulting to false, and notIncludedLevel as @Enumerated(STRING) with length 20; the new enum NotIncludedLevel {THIS_PREMIX, FINAL_FORMULA} lives in domain/formula. The composition fetch join adds the referenced formula so the mapper never lazy-loads (E32).

VERIFICATION. A repository H2 integration test, following the existing H2 IT naming in repository/formula, asserts each CHECK's four cases, the RESTRICT behaviour and that an existing row reads not_included false after the migration.

One aggregate, one service, one controller surface. The pre-mix line is a composition line, so every write and read below extends the classes MP-690 merged (E13, E14, E15); nothing parallel is created.

DTOs.
- FormulaLineResponse: remove kind; add premixFormulaId (UUID, null unless the line references a pre-mix), premixCode and premixName (String, "" when absent, following the record's existing empty-string convention), notIncluded (Boolean), notIncludedLevel (String code or null). This completes the human work request's backend half together with the mapper constant and the test assertion (E1, E2, E3, E4, E5).
- UpdateFormulaLineRequest and AddFormulaLineRequest: add premixFormulaId, notIncluded, notIncludedLevel as plain nullable components, following the update record's documented full-replacement carve-out (E20); isQsp keeps its @NotNull.
- PremixCandidateResponse (new record): formulaId, code, name, statusCode, statusLabel, statusColorCode, totalPercentage.
- PremixTreeResponse and PremixTreeNodeResponse (new records): the tree for one pre-mix line plus one node per ingredient, each with path, depth, its share in its own pre-mix, name, isPremix, inci, pricePerUnit, currencyCode, unitCode, notIncluded and notIncludedLevel. The component names must be read off the mock's PremixTree, PremixIngredientNode and PremixLinePrice types at the branch head and matched exactly, so the flip changes no hook or component (E24, E26).

MAPPER. FormulaCompositionMapper drops LINE_KIND_RAW_MATERIAL and fills the pre-mix trio from line.getPremixFormula(), keeping the rule that it reads only initialised associations - so the composition query fetch-joins the referenced formula (E4, E32). It stays a static utility; the two new read shapes are mapped by the same class or by a sibling static mapper in mapper/formula, as the area's convention requires.

SERVICE: FormulaCompositionService (@Transactional, readOnly for reads). New private validation, invoked by addLine and updateLine before anything is written, so a refusal leaves the composition untouched exactly as the existing rules do:
  1. at most one reference per line (message: the preview's both-references wording);
  2. the referenced formula exists (404) and its is_premix is true (400);
  3. depth at most 5 over the referenced formula's own pre-mix lines;
  4. no cycle: a depth-first walk from the edited formula that accepts the same sub-pre-mix reached by two different paths and refuses only a genuine loop - the behaviour the mock review explicitly demanded;
  5. the Not included level is required on a line of a formula whose is_premix is true and must be null otherwise;
  6. a pre-mix line carries a typed lot only, never a picked batch.
Each throws BusinessRuleException with a messageKey; the depth, cycle and both-references texts reproduce the preview's wording verbatim (E21) so the user sees the same sentence from the optimistic check and from the server. applyValues applies the two references mutually exclusively - a pre-mix clears the raw material and the batch, a raw material clears the pre-mix - so a mixed edit returns the message rather than hitting the CHECK (E13).

USAGE RECORD, single writer. A private reconcile(formulaId) makes the formula's formula_premix_use rows equal the distinct non-null premixFormulaId values of its lines, reading findByFormula_Id and deleting or inserting the difference (E9). Called at the end of addLine, updateLine, deleteLine and copyComposition. copyLines' explicit column list gains the three new columns, lot and batch staying uncopied (E12), and copyComposition reconciles the duplicate afterwards (E14). Nothing else changes for AC10: the daughters endpoint and the flag-off guard are untouched (E10, E11).

FORMULA SERVICE. applyPremixChange gains the level handling for the flip (E11): on true-to-false, clear notIncludedLevel on that formula's lines; on false-to-true, refuse with its own key while a ticked line has no level. findPremixCandidates(q, siteId) reads formulas with is_premix true and no status filter (E19, E31), ranks them like the raw-material candidate search (E17), and computes each pre-mix's own total as the sum of its filled non-QSP line percentages plus a filled QSP line's derived share - as entered, never rescaled, which is what AC5 relies on.

PRE-MIX TREE. FormulaCompositionService#getPremixTree(formulaId, premixFormulaId, siteId) walks the referenced formula's lines level by level, capped at 5, refusing nothing and simply not walking past the cap; it resolves each leaf's name, INCI, price, currency and unit through RawMaterialSiteDataService at the requested siteId (E18), and multiplies the shares along the path so each node also carries its percentage in the final formula. {formulaId} is the formula being edited and siteId the site it is read at, which is what makes the same pre-mix price differently at another site (AC2, AC3). The service serves figures only: the dash with its reason, the excluded count in the footer and the not-100% warning stay in the one client-side cost calculation that already owns MP-690's exclusion reasons (E26).

CONTROLLERS. FormulaCompositionController gains one GET /premix-tree; FormulaController gains one GET /premix-candidates, placed before the /{id} mapping's resolution order. Both are reads open to any authenticated user, like the composition endpoints around them (E15, E16); neither changes an existing signature apart from the request records above.

ERRORS AND i18n. Every refusal is a BusinessRuleException (400) or ResourceNotFoundException (404) reaching GlobalExceptionHandler as a ProblemDetail; no broad catch. Every new key is added to messages.properties and messages_fr.properties beside the existing exception.formula.line.* family (E29).

TESTS. FormulaCompositionServiceTest: one test per rule, the reconciliation on add, update and delete, and the mutually exclusive references; the kind assertion is removed. FormulaServiceTest: the two flip behaviours and the pre-mix candidate query with a Development pre-mix. A repository H2 IT for the migration and its CHECKs. A Keycloak and Postgres controller IT for the two new endpoints: 401 unauthenticated, parameter validation, and the localized text of each new message. Gate: ./gradlew --no-daemon spotlessCheck and ./gradlew --no-daemon test.

Alternatives considered

• A1 — Extend MP-690's composition aggregate in place. The approved design's three columns land on formula_phase_line as V035 with the entity fields; FormulaLineResponse loses kind and gains the pre-mix trio and the Not included pair; the line write requests gain the same components; every new rule and the pre-mix usage reconciliation live in the existing FormulaCompositionService; two read endpoints are added, GET /v1/formulas/premix-candidates on the formula controller and GET /v1/formulas/{formulaId}/premix-tree on the composition controller; prices and INCI come from the existing per-site resolut…

  Pros: One home for a composition line, one cost calculation, one locked-formula guard - the ticket's live-analogue rule; The response records stay the shapes the accepted mock already returns, so the flip changes no hook and no component; Reuses the usage record, its repository and its reader unchanged: AC10 needs rows, not a redesign; Implements the approved DB design exactly as approved, with no schema decision reopened; The per-site price precedent of MP-690 answers AC2 and AC3 with no new stored value. Cons: FormulaCompositionService grows: the pre-mix rules, the tree walk and the usage reconciliation all attach to it; A pre-mix line's price is walked level by level at read time, which multiplies queries on deep nesting; The line response changes shape for a merged endpoint in the same release as the discriminator removal.

• A2 — Add a parallel pre-mix composition family: a PremixCompositionController and service under /v1/formula-premix-lines owning the pre-mix lines, their rules, their tree and the usage record, leaving MP-690's composition endpoints untouched apart from reading the new columns.

  Pros: Keeps the merged MP-690 service and its tests almost unchanged; The new rules sit in a class of their own. Cons: A second home for the composition line: two writers of one table, two lock guards, two audit paths and two orderings to keep in step; The grid would write a line through one route and a pre-mix line through another, which the accepted mock does not do - it writes every line through one data layer; Both-reference and single-reference rules would straddle two services, so a mixed edit could satisfy each one separately; Rejected by the ticket's live-analogue rule: extend the grid, its data layer and its cost calculation, do not build a second one.

• A3 — Store the derived pre-mix figures - a line's resolved price and reason, each node's share and the pre-mix's total - in new columns or a side table written on save, so the grid reads them without a walk.

  Pros: One read per composition however deep the nesting; The cost footer would need no client-side arithmetic. Cons: Contradicts the approved DB design, which stores nothing derived and was approved on that basis; A price is site-dependent: a stored figure is wrong for every other industrial site, which AC3 exercises directly; Every edit to any pre-mix at any level would have to invalidate the stored figures of every formula above it; Reopens a settled schema decision at the stage that implements it.

API contract

The frontend consumes exactly the shapes of the backend-plan's apiContract: the composition line without kind and with the pre-mix trio and the Not included pair, GET /v1/formulas/premix-candidates for the pre-mix half of the ingredient search, GET /v1/formulas/{formulaId}/premix-tree?premixFormulaId=&siteId= for the (+) detail, and the unchanged GET /v1/formulas/{id}/daughters for the impact alert. A rule refusal arrives as a 400 ProblemDetail and is surfaced as the existing { outcome: "refused", message } result.

GET /v1/formulas/{formulaId}/composition -> FormulaCompositionResponse{formulaId, referenceWeightG, lines[FormulaLineResponse{id, phaseId, phase, phaseSortOrder, sortOrder, premixFormulaId, premixCode, premixName, rawMaterialId, commercialName, percentage, isQsp, lot, batch, notIncluded, notIncludedLevel}]} - kind removed.
POST /v1/formulas/{formulaId}/lines, body AddFormulaLineRequest{afterLineId, phase, premixFormulaId?, notIncluded?, notIncludedLevel?} -> 201 + Location + AddFormulaLineResponse{createdLineId, composition}.
PUT /v1/formulas/{formulaId}/lines/{lineId}, body UpdateFormulaLineRequest{phase, rawMaterialId, premixFormulaId, percentage, isQsp, lot, batchId, notIncluded, notIncludedLevel} (full replacement, null clears) -> 200 + FormulaCompositionResponse.
DELETE /v1/formulas/{formulaId}/lines/{lineId} -> 204, usage record reconciled.
GET /v1/formulas/premix-candidates?q=&siteId= -> 200 + List<PremixCandidateResponse{formulaId, code, name, statusCode, statusLabel, statusColorCode, totalPercentage}>, any status.
GET /v1/formulas/{formulaId}/premix-tree?premixFormulaId=&siteId= -> 200 + PremixTreeResponse{premixFormulaId, totalPercentage, nodes[PremixTreeNodeResponse{path, depth, lineId, share, name, isPremix, inci, pricePerUnit, currencyCode, unitCode, notIncluded, notIncludedLevel}]}, capped at 5 levels, priced at siteId.
GET /v1/formulas/{id}/daughters -> unchanged, now non-empty.
Refusals: 400 ProblemDetail with the message key's text for both references, depth over 5, a cycle, a referenced formula that is not a pre-mix, a missing level on a pre-mix formula, a batch on a pre-mix line, and the isPremix flip; 404 for an unknown formula, line or pre-mix. The exact record component names are reconciled against the mock's types at the branch head before authoring.

Backend design

One aggregate, one service, one controller surface. The pre-mix line is a composition line, so every write and read below extends the classes MP-690 merged (E13, E14, E15); nothing parallel is created.

DTOs.
- FormulaLineResponse: remove kind; add premixFormulaId (UUID, null unless the line references a pre-mix), premixCode and premixName (String, "" when absent, following the record's existing empty-string convention), notIncluded (Boolean), notIncludedLevel (String code or null). This completes the human work request's backend half together with the mapper constant and the test assertion (E1, E2, E3, E4, E5).
- UpdateFormulaLineRequest and AddFormulaLineRequest: add premixFormulaId, notIncluded, notIncludedLevel as plain nullable components, following the update record's documented full-replacement carve-out (E20); isQsp keeps its @NotNull.
- PremixCandidateResponse (new record): formulaId, code, name, statusCode, statusLabel, statusColorCode, totalPercentage.
- PremixTreeResponse and PremixTreeNodeResponse (new records): the tree for one pre-mix line plus one node per ingredient, each with path, depth, its share in its own pre-mix, name, isPremix, inci, pricePerUnit, currencyCode, unitCode, notIncluded and notIncludedLevel. The component names must be read off the mock's PremixTree, PremixIngredientNode and PremixLinePrice types at the branch head and matched exactly, so the flip changes no hook or component (E24, E26).

MAPPER. FormulaCompositionMapper drops LINE_KIND_RAW_MATERIAL and fills the pre-mix trio from line.getPremixFormula(), keeping the rule that it reads only initialised associations - so the composition query fetch-joins the referenced formula (E4, E32). It stays a static utility; the two new read shapes are mapped by the same class or by a sibling static mapper in mapper/formula, as the area's convention requires.

SERVICE: FormulaCompositionService (@Transactional, readOnly for reads). New private validation, invoked by addLine and updateLine before anything is written, so a refusal leaves the composition untouched exactly as the existing rules do:
  1. at most one reference per line (message: the preview's both-references wording);
  2. the referenced formula exists (404) and its is_premix is true (400);
  3. depth at most 5 over the referenced formula's own pre-mix lines;
  4. no cycle: a depth-first walk from the edited formula that accepts the same sub-pre-mix reached by two different paths and refuses only a genuine loop - the behaviour the mock review explicitly demanded;
  5. the Not included level is required on a line of a formula whose is_premix is true and must be null otherwise;
  6. a pre-mix line carries a typed lot only, never a picked batch.
Each throws BusinessRuleException with a messageKey; the depth, cycle and both-references texts reproduce the preview's wording verbatim (E21) so the user sees the same sentence from the optimistic check and from the server. applyValues applies the two references mutually exclusively - a pre-mix clears the raw material and the batch, a raw material clears the pre-mix - so a mixed edit returns the message rather than hitting the CHECK (E13).

USAGE RECORD, single writer. A private reconcile(formulaId) makes the formula's formula_premix_use rows equal the distinct non-null premixFormulaId values of its lines, reading findByFormula_Id and deleting or inserting the difference (E9). Called at the end of addLine, updateLine, deleteLine and copyComposition. copyLines' explicit column list gains the three new columns, lot and batch staying uncopied (E12), and copyComposition reconciles the duplicate afterwards (E14). Nothing else changes for AC10: the daughters endpoint and the flag-off guard are untouched (E10, E11).

FORMULA SERVICE. applyPremixChange gains the level handling for the flip (E11): on true-to-false, clear notIncludedLevel on that formula's lines; on false-to-true, refuse with its own key while a ticked line has no level. findPremixCandidates(q, siteId) reads formulas with is_premix true and no status filter (E19, E31), ranks them like the raw-material candidate search (E17), and computes each pre-mix's own total as the sum of its filled non-QSP line percentages plus a filled QSP line's derived share - as entered, never rescaled, which is what AC5 relies on.

PRE-MIX TREE. FormulaCompositionService#getPremixTree(formulaId, premixFormulaId, siteId) walks the referenced formula's lines level by level, capped at 5, refusing nothing and simply not walking past the cap; it resolves each leaf's name, INCI, price, currency and unit through RawMaterialSiteDataService at the requested siteId (E18), and multiplies the shares along the path so each node also carries its percentage in the final formula. {formulaId} is the formula being edited and siteId the site it is read at, which is what makes the same pre-mix price differently at another site (AC2, AC3). The service serves figures only: the dash with its reason, the excluded count in the footer and the not-100% warning stay in the one client-side cost calculation that already owns MP-690's exclusion reasons (E26).

CONTROLLERS. FormulaCompositionController gains one GET /premix-tree; FormulaController gains one GET /premix-candidates, placed before the /{id} mapping's resolution order. Both are reads open to any authenticated user, like the composition endpoints around them (E15, E16); neither changes an existing signature apart from the request records above.

ERRORS AND i18n. Every refusal is a BusinessRuleException (400) or ResourceNotFoundException (404) reaching GlobalExceptionHandler as a ProblemDetail; no broad catch. Every new key is added to messages.properties and messages_fr.properties beside the existing exception.formula.line.* family (E29).

TESTS. FormulaCompositionServiceTest: one test per rule, the reconciliation on add, update and delete, and the mutually exclusive references; the kind assertion is removed. FormulaServiceTest: the two flip behaviours and the pre-mix candidate query with a Development pre-mix. A repository H2 IT for the migration and its CHECKs. A Keycloak and Postgres controller IT for the two new endpoints: 401 unauthenticated, parameter validation, and the localized text of each new message. Gate: ./gradlew --no-daemon spotlessCheck and ./gradlew --no-daemon test.

Backend changes

Data contract

formula_phase_line gains premix_formula_id (UUID, FK formula(id), ON DELETE RESTRICT, NULL), not_included (BOOLEAN NOT NULL DEFAULT FALSE) and not_included_level (VARCHAR(20) NULL, CHECK IN ('THIS_PREMIX','FINAL_FORMULA'), only when not_included). A line holds at most one of rawmaterial_id and premix_formula_id; neither stays legal. A pre-mix line holds no rawmaterial_batch_id. premix_formula_id <> formula_id. One index, idx_formula_phase_line_premix_formula_id. formula_premix_use (V028) is unchanged and holds one row per distinct (formula, pre-mix) pair referenced by the formula's lines, written only by the composition service.

Database design

The schema work is transcription, not design: the DB stage's document on the branch is the normative source and was approved at DB Review; this stage authors the migration it deliberately left out (E25).

FILE. backend/applications/cosmoreg-core/src/main/resources/db/migration/V035__Add_Premix_Reference_And_Not_Included_To_Formula_Phase_Line.sql. V034 is the highest version at the indexed base (E30), so V035 is next free; the builder re-checks the number against main before authoring, because another ticket's migration may have landed meanwhile.

COLUMNS on formula_phase_line (E6, E7).
- premix_formula_id UUID NULL, foreign key to formula(id) with an explicit ON DELETE RESTRICT, matching the table's existing raw-material and batch foreign keys and the guarantee that a pre-mix still used by a line cannot be deleted.
- not_included BOOLEAN NOT NULL DEFAULT FALSE. The DEFAULT is what makes the ALTER safe on populated rows; every existing line reads false, which is the behaviour before this ticket.
- not_included_level VARCHAR(20) NULL, a code set fixed by a CHECK rather than reference data - the design's deliberate, reviewed deviation, approved at the gate.

CHECKS, each named and each carrying its IS NOT NULL guard so it never fires on a legal NULL (the pattern the table already uses, E7).
- chk_formula_phase_line_single_reference: a line never holds both references. 'Neither' stays legal, because MP-690 creates an empty line with no raw material, and no new constraint is added for it - the ticket's reference rule and the work request both say so.
- no direct self-reference: premix_formula_id IS NULL OR premix_formula_id <> formula_id. The indirect cases cannot be a row-level CHECK and stay service rules.
- no picked batch on a pre-mix line: premix_formula_id IS NULL OR rawmaterial_batch_id IS NULL, which is the Lot-is-free-text-only rule for a pre-mix line.
- the level's value set: not_included_level IS NULL OR not_included_level IN ('THIS_PREMIX', 'FINAL_FORMULA') - exactly the two codes the mock exchanges (E22).
- the level needs the flag: not_included_level IS NULL OR not_included.
For each CHECK the file states its allowed, rejected-by-value, rejected-by-NULL and unaffected cases, as the design document does.

INDEX. idx_formula_phase_line_premix_formula_id. The table's existing indexes lead with formula_id, rawmaterial_id and rawmaterial_batch_id, so none serves a lookup by the new reference, which the foreign key's RESTRICT check, the level-by-level price walk and the usage reconciliation all perform.

REUSED UNCHANGED. formula_premix_use (V028) keeps its columns, its two foreign keys, its unique pair and its two indexes (E8); this stage gives it its single writer in the service layer, which is what makes the existing daughters reader and the flag-off guard truthful (E9, E10, E11). formula.is_premix and its partial index are untouched and simply queried by the candidate endpoint (E31). rawmaterial_site keeps serving per-site prices (E18).

NOT IN THE SCHEMA, deliberately. A line's resolved price and its reason, a node's share, the percentage in the final formula, a pre-mix's total, its code, name and INCI: all read-time results. The 5-level depth limit, indirect cycles, 'neither reference on a filled line', 'the referenced formula is a pre-mix' and 'the level is required on a pre-mix formula' span several rows or tables and stay service rules, each with the message the design lists.

ENTITY MAPPING (ddl-auto is validate, so it ships with the migration). FormulaPhaseLine gains premixFormula as a LAZY @ManyToOne on premix_formula_id, notIncluded as a non-null Boolean defaulting to false, and notIncludedLevel as @Enumerated(STRING) with length 20; the new enum NotIncludedLevel {THIS_PREMIX, FINAL_FORMULA} lives in domain/formula. The composition fetch join adds the referenced formula so the mapper never lazy-loads (E32).

VERIFICATION. A repository H2 integration test, following the existing H2 IT naming in repository/formula, asserts each CHECK's four cases, the RESTRICT behaviour and that an existing row reads not_included false after the migration.

Database changes

Files named by the steps

• backend/applications/cosmoreg-core/src/main/resources/db/migration/V035__Add_Premix_Reference_And_Not_Included_To_Formula_Phase_Line.sql
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/domain/formula/FormulaPhaseLine.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/domain/formula/NotIncludedLevel.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/repository/formula/FormulaPhaseLineRepository.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/FormulaLineResponse.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/mapper/formula/FormulaCompositionMapper.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/UpdateFormulaLineRequest.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/AddFormulaLineRequest.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaCompositionServiceTest.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaCompositionService.java
• backend/applications/cosmoreg-core/src/main/resources/messages.properties
• backend/applications/cosmoreg-core/src/main/resources/messages_fr.properties
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaService.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/controller/formula/FormulaController.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/PremixCandidateResponse.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/repository/formula/FormulaRepository.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/controller/formula/FormulaCompositionController.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/PremixTreeResponse.java
• backend/applications/cosmoreg-core/src/main/java/com/chromasoftware/cosmoreg/core/dto/formula/PremixTreeNodeResponse.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaServiceTest.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/repository/formula/FormulaPhaseLinePremixH2IT.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/controller/formula/FormulaPremixCompositionIT.java
• frontend/src/domains/formulation/features/formulas/api/formula-premix.ts
• frontend/src/domains/formulation/features/formulas/lib/mock-premix-data.ts
• frontend/src/domains/formulation/features/formulas/api/formula-composition.ts
• frontend/src/domains/formulation/features/formulas/description/hooks/use-formula-composition.ts
• frontend/src/domains/formulation/features/formulas/description/hooks/use-formula-description.ts

Components the review expects

• kind: create · path: backend/applications/cosmoreg-core/src/main/resources/db/migration/V035__Add_Premix_Reference_And_Not_Included_To_Formula_Phase_Line.sql
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-core/src/main/resources/messages.properties
• kind: modify · path: backend/applications/cosmoreg-core/src/main/resources/messages_fr.properties
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: create · path: backend/applications/cosmoreg-[redacted].java
• kind: modify · path: frontend/src/domains/formulation/features/formulas/api/formula-premix.ts
• kind: delete · path: frontend/src/domains/formulation/features/formulas/lib/mock-premix-data.ts
• kind: modify · path: frontend/src/domains/formulation/features/formulas/api/formula-composition.ts
• kind: modify · path: frontend/src/domains/formulation/features/formulas/description/hooks/use-formula-composition.ts
• kind: modify · path: frontend/src/domains/formulation/features/formulas/description/hooks/use-formula-description.ts

Review checks

• id: RC1 · check: V035 is the only new migration, its version is free on main, and it matches the approved design document on the branch line for line: three columns on formula_phase_line, one foreign key to formula with an explicit ON DELETE RESTRICT, five named CHECKs each with its IS NOT NULL guard, and one index on premix_formula_id. Nothing beyond the document is added, renamed or dropped, and…
• id: RC2 · check: not_included is NOT NULL with DEFAULT FALSE so the ALTER cannot abort on populated rows, not_included_level is constrained to THIS_PREMIX and FINAL_FORMULA and only when the flag is set, and formula_premix_use keeps its columns, keys, unique pair and indexes untouched. An empty line with neither reference is still accepted.
• id: RC3 · check: The entity matches the migration (ddl-auto is validate): premixFormula as a LAZY association, notIncluded non-null defaulting to false, notIncludedLevel mapped STRING with the two-value enum, and the composition query fetch-joins the referenced formula so the mapper never lazy-loads.
• id: RC4 · check: kind is gone from FormulaLineResponse, LINE_KIND_RAW_MATERIAL is gone from FormulaCompositionMapper, and the service test no longer asserts a line kind. No replacement discriminator, flag, computed value or constant of any name takes its place anywhere under backend/: the reference field is the only answer. The picker-label kind on raw-material candidates and the kind of lib/formu…
• id: RC5 · check: The line response carries premixFormulaId, premixCode, premixName, notIncluded and notIncludedLevel, and the two write requests carry premixFormulaId, notIncluded and notIncludedLevel as plain nullable components. Every new record component name matches the mock's own types at the branch head, so no hook and no component had to be adapted.
• id: RC6 · check: A line write applies the two references mutually exclusively - assigning a pre-mix clears the raw material and any picked batch, assigning a raw material clears the pre-mix - so a mixed edit returns the rule's message rather than a constraint violation, and a line holding both is refused.
• id: RC7 · check: Saving a composition that nests pre-mixes more than 5 levels deep is refused, and a formula that would contain itself directly or through other pre-mixes is refused; a sub-pre-mix legitimately reached twice by different paths is ACCEPTED. Both refusal texts are the preview's wording verbatim, in messages.properties and messages_fr.properties.
• id: RC8 · check: Referencing a formula whose is_premix is false is refused; a pre-mix line accepts a typed lot only and never a picked batch; on a formula that is itself a pre-mix a ticked line cannot be saved without a level, and on any other formula the level must be null. Every new message key exists in both properties files.
• id: RC9 · check: One writer of formula_premix_use: after an add, an update, a delete and a duplicate copy, the formula's rows equal the distinct pre-mix references of its lines. Adding a pre-mix to two formulas makes the daughters endpoint report 2, and removing it from one makes it report 1, with no change to the daughters query or to the flag-off guard.
• id: RC10 · check: copyLines carries premix_formula_id, not_included and not_included_level while still leaving lot and batch uncopied, and the duplicate gets its own usage rows - a duplicated formula's pre-mix lines are not rows with neither reference.
• id: RC11 · check: GET /v1/formulas/premix-candidates returns pre-mix formulas whatever their status, including Development, with code, name, status code/label/colour and the pre-mix's own total as entered, never rescaled; the live raw-material candidate endpoint is untouched and the two lists are merged in the data layer, not replaced.
• id: RC12 · check: GET /v1/formulas/{formulaId}/premix-tree walks the referenced formula to at most 5 levels and serves per node its share, name, whether it is itself a pre-mix, its INCI and its pricePerUnit, currencyCode and unitCode resolved at the requested siteId through the existing per-site service. A 50/50 pre-mix of raw materials at 2.00 and 4.00 EUR/kg at site S yields 3.00 EUR/kg, and the…
• id: RC13 · check: Nothing derived is stored or served as a verdict: no price, reason, tree, percentage, total, code, name or INCI column exists, and the dash with its reason plus the footer's excluded count remain the client-side cost calculation's result from the served price, currency and unit. A USD ingredient, an unpriced ingredient and a per-litre ingredient each produce the dash with the rea…
• id: RC14 · check: Turning isPremix off clears the formula's line levels; turning it on is refused, with its own localized message, while a ticked line has no level. The existing refusal to clear the flag while daughters consume the formula still names the daughter codes.
• id: RC15 · check: lib/mock-premix-data.ts is deleted, api/formula-premix.ts contains no fixture import and no TODO(MP-691) marker, and every one of its functions calls apiClient. A rule refusal still arrives as the existing refused result, so the toast-and-revert path and the one-cell revert are unchanged.
• id: RC16 · check: The three mock-stage limits are gone on the preview: a line can be added after a pre-mix line, no demo pre-mix line is seeded into any formula (a formula's total is its own again), and the daughters alert lists only real formulas.
• id: RC17 · check: No behaviour the PO accepted has changed: a pre-mix line's INCI cell is empty, its Lot takes free text with no batch suggestions, the (+) shows ingredients read-only with their INCI and their percentage in the final formula and opens nested pre-mixes to 5 levels with nothing editable, and a pre-mix totalling 95% is used as entered with its warning.
• id: RC18 · check: lib/composition-math.ts, lib/premix-rules.ts, the single pre-mix predicate, premix-detail-rows.tsx, not-included-level-dialog.tsx, premix-badge.tsx, premix-impact-alert.tsx and the column definitions are not rewritten: the flip changed the data source, not the behaviour. Existing estimateCost exclusion reasons are added to, never renamed.
• id: RC19 · check: The verification gate passes on the branch head: ./gradlew --no-daemon spotlessCheck and ./gradlew --no-daemon test in backend/, then npm run build and npm run lint in frontend/. Each of AC1 to AC11 has at least one test naming it, and the two new endpoints have 401, validation and i18n coverage in a Keycloak and Postgres controller IT.
• id: RC20 · check: Scope discipline: no second composition service, controller family or cost calculation; no new npm or Gradle dependency; no change to how a formula is marked as a pre-mix; no currency or unit conversion; no combined INCI list for the finished product; no all-levels-expanded view; and no change to formula_premix_use's shape, to rawmaterial_site or to the live raw-material search.

Test files

• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/repository/formula/FormulaPhaseLinePremixH2IT.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaCompositionServiceTest.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/service/formula/FormulaServiceTest.java
• backend/applications/cosmoreg-core/src/test/java/com/chromasoftware/cosmoreg/core/controller/formula/FormulaPremixCompositionIT.java

Reuse to verify

• area: db · element: formula_phase_line (V032) and the V035 migration · action: extend · why: The one composition line table is extended in place, exactly as the approved design describes. A second line table, a child table for the pre-mix reference, a reference-data table for the level or a stored kind column would each be a rejected alternative reappearing.
• area: db · element: formula_premix_use (V028) · action: reuse · why: Reused with its shape, keys and indexes untouched; MP-691 only gives it its single writer. A second record of which formula uses which pre-mix, or a derivation replacing it, must not appear.
• area: backend · element: FormulaCompositionService, FormulaCompositionController and FormulaCompositionMapper · action: extend · why: Rejected alternative A2: a parallel pre-mix composition service or controller family would be a second writer of one table with its own lock, ordering and audit path. Every new rule, the tree walk and the usage reconciliation belong in the existing composition class…
• area: backend · element: FormulaLineResponse.kind and FormulaCompositionMapper.LINE_KIND_RAW_MATERIAL · action: remove · why: The human work request's backend half. Watch for any replacement discriminator under a different name, in a DTO, a mapper, an enum or a test helper.
• area: backend · element: RawMaterialSiteDataService and POST /v1/raw-materials/site-data · action: reuse · why: Per-site price, currency, unit and INCI already exist and must be reused by the tree walk. A second price resolution path, or any stored price on a line, is rejected alternative A3.
• area: backend · element: GET /v1/formulas/{id}/daughters and the isPremix flag-off guard · action: reuse · why: Unchanged code that starts telling the truth once rows are written; a new endpoint or a new counter for AC10 would duplicate it.
• area: frontend · element: lib/mock-premix-data.ts · action: remove · why: The fixtures and their three preview devices must be deleted, not left behind a flag; any surviving seeded line or fictional daughter fails the ticket's mock-stage limits.
• area: frontend · element: lib/composition-math.ts and lib/premix-rules.ts · action: reuse · why: The one cost calculation and the optimistic preview stay as they are. A second cost calculation, a renamed exclusion reason or a server-side price verdict would each break the ticket's live-analogue rule.

Backend builder takes over the Backend stage from this plan.

RAG revision

6ff9aee4994f

Catalog

ead4cae607ae

Base SHA (RAG indexed)

3830b223cba4

Feature base

3830b223cba4

Branch head

945a5346234e

Main

3830b223cba4

Main overlay

none

Branch overlay

8dc7ee4dc40b

Branch

claude/mock-MP-691-premix-composition-line

PR

#143

Freshness

EXACT

RAG mode / profile

required

Stage binding

a51ef40cb084

Context manifest

62d5d3cf887a

Policy binding

08fde414b576

Writes

disabled

TicketSnapshot schema

ticket-snapshot/v2

TicketSnapshot hash

e5c2c3e4a6cf

TicketSnapshot size

32595 B

TicketSnapshot fetched

2026-10-16T16:18:50Z

FeatureContract schema

feature-contract/v2.1

FeatureContract hash

ffabe7ec47d7

Contract

feature-contract/v2.1 · ffabe7ec47d78be300cc79fefc3e49a52e5d9af6a454fb483a2a2083bab3ac71

Aggregate

ffabe7ec47d78be300cc79fefc3e49a52e5d9af6a454fb483a2a2083bab3ac71

RAG

RAG · EXACT

Cited evidence

Reuse and anti-duplication

Bound to

RAG revision

6ff9aee4994f

Catalog

ead4cae607ae

RAG indexed base

3830b223cba4

Feature base

3830b223cba4

Branch head

945a5346234e

Main

3830b223cba4

Ticket snapshot

e5c2c3e4a6cf

Contract sections

• architecture · 15612 B · 7344def129cb · shown
• frontend-plan · 6367 B · 1f1bed7c6389 · shown
• db-plan · 7458 B · 05090e47e046 · shown
• backend-plan · 15362 B · 375759a13782 · shown
• evidence · 16546 B · 125da81ee661 · shown
• review-plan · 14930 B · 7b0a0e8215ee · shown