@formicoidea/labre-core 0.36.0 → 0.38.1

package/dist/_pkgs/affine-block-frame/frame-manager.d.ts

@@ -35,6 +35,37 @@ export declare class EdgelessFrameManager extends GfxExtension {
     }>(a: T, b: T): 0 | 1 | -1;
     private _addChildrenToLegacyFrame;
     private _addFrameBlock;
+    /**
+     * The index a frame gets when it is placed at `bound`.
+     *
+     * A frame's index is deliberately at the BACK of the stack, so it renders
+     * behind everything it owns. On a bare canvas that is right. On a framework
+     * board it is not: a Wardley map — a C4 board, a BPMN pool, any
+     * `FrameworkBackgroundElementModel` — is an OPAQUE canvas element, so a
+     * frame sent behind the whole surface goes behind the paint and only the
+     * part overhanging the board stays visible. The back of the SURFACE and the
+     * back of the BOARD are two different depths.
+     *
+     * So the frame lands just above the topmost background it covers, which is
+     * still behind every artefact drawn on that board — the depth a Wardley zone
+     * already needed, for the same reason, in #213. See
+     * {@link indexOverBackgrounds}.
+     */
+    frameIndexAt(bound: Bound): string;
+    /**
+     * A frame DROPPED onto a framework background is raised above it, exactly as
+     * a frame drawn there is ({@link frameIndexAt}) — same gesture, arriving a
+     * moment later.
+     *
+     * Only ever upwards, and only while the frame is actually BELOW a background
+     * it overlaps. So a frame already above one is left alone (a drag writes an
+     * index at most once, and only on the move that buries it), and undo is safe
+     * for the same reason: the restored position is the one the frame came from,
+     * where nothing overlapping was above it. A frame the author sent to the
+     * back on purpose is only raised again if they move it — on a board, moving
+     * a frame means wanting to see it.
+     */
+    private _watchFrameMoved;
     private _watchElementAdded;
     /**
      * Whether `element` fully encloses `frame`.

package/dist/_pkgs/affine-block-frame/frame-manager.js

@@ -1,4 +1,4 @@
-import { Overlay } from '../affine-block-surface/index.js';
+import { indexOverBackgrounds, Overlay, stackedElementsOf, } from '../affine-block-surface/index.js';
 import { FrameworkBackgroundElementModel } from '../affine-model/index.js';
 import { EditPropsStore } from '../affine-shared/services/index.js';
 import { DisposableGroup } from '../global/disposable/index.js';
@@ -100,6 +100,7 @@ export class EdgelessFrameManager extends GfxExtension {
         super(gfx);
         this._disposable = new DisposableGroup();
         this._watchElementAdded();
+        this._watchFrameMoved();
     }
     static framePresentationComparator(a, b) {
         function stringCompare(a, b) {
@@ -145,7 +146,7 @@ export class EdgelessFrameManager extends GfxExtension {
             .applyLastProps('affine:frame', {
             title: new Text(new Y.Text(`Frame ${this.frames.length + 1}`)),
             xywh: bound.serialize(),
-            index: this.gfx.layer.generateIndex(true),
+            index: this.frameIndexAt(bound),
             presentationIndex: this.generatePresentationIndex(),
         });
         const id = this.gfx.doc.addBlock('affine:frame', props, surfaceModel);
@@ -155,6 +156,65 @@ export class EdgelessFrameManager extends GfxExtension {
         }
         return frameModel;
     }
+    /**
+     * The index a frame gets when it is placed at `bound`.
+     *
+     * A frame's index is deliberately at the BACK of the stack, so it renders
+     * behind everything it owns. On a bare canvas that is right. On a framework
+     * board it is not: a Wardley map — a C4 board, a BPMN pool, any
+     * `FrameworkBackgroundElementModel` — is an OPAQUE canvas element, so a
+     * frame sent behind the whole surface goes behind the paint and only the
+     * part overhanging the board stays visible. The back of the SURFACE and the
+     * back of the BOARD are two different depths.
+     *
+     * So the frame lands just above the topmost background it covers, which is
+     * still behind every artefact drawn on that board — the depth a Wardley zone
+     * already needed, for the same reason, in #213. See
+     * {@link indexOverBackgrounds}.
+     */
+    frameIndexAt(bound) {
+        return (indexOverBackgrounds(stackedElementsOf(this.gfx), bound) ??
+            this.gfx.layer.generateIndex(true));
+    }
+    /**
+     * A frame DROPPED onto a framework background is raised above it, exactly as
+     * a frame drawn there is ({@link frameIndexAt}) — same gesture, arriving a
+     * moment later.
+     *
+     * Only ever upwards, and only while the frame is actually BELOW a background
+     * it overlaps. So a frame already above one is left alone (a drag writes an
+     * index at most once, and only on the move that buries it), and undo is safe
+     * for the same reason: the restored position is the one the frame came from,
+     * where nothing overlapping was above it. A frame the author sent to the
+     * back on purpose is only raised again if they move it — on a board, moving
+     * a frame means wanting to see it.
+     */
+    _watchFrameMoved() {
+        this._disposable.add(this.gfx.doc.slots.blockUpdated.subscribe(payload => {
+            if (payload.type !== 'update' ||
+                !payload.isLocal ||
+                payload.flavour !== 'affine:frame' ||
+                payload.props.key !== 'xywh') {
+                return;
+            }
+            const frame = this.gfx.getElementById(payload.id);
+            // A nested frame keeps its parent's ordering: `compare` reads the
+            // ancestor's index, so raising the child would change nothing.
+            if (!frame || !isFrameBlock(frame) || frame.group !== null)
+                return;
+            const siblings = stackedElementsOf(this.gfx, frame);
+            const box = frame.elementBound;
+            const buried = siblings.some(element => element.isBackground &&
+                element.index > frame.index &&
+                Bound.deserialize(element.xywh).isOverlapWithBound(box));
+            if (!buried)
+                return;
+            const over = indexOverBackgrounds(siblings, box);
+            if (over !== null) {
+                this.gfx.updateElement(frame, { index: over });
+            }
+        }));
+    }
     _watchElementAdded() {
         if (!this.gfx.surface) {
             return;

package/dist/_pkgs/affine-block-frame/frame-tool.js

@@ -44,12 +44,16 @@ export class FrameTool extends BaseTool {
             return;
         if (!this._frame) {
             const frames = this.gfx.layer.blocks.filter(block => block.flavour === 'affine:frame');
+            const bound = Bound.fromPoints([this._startPoint, currentPoint]);
             const props = this.std
                 .get(EditPropsStore)
                 .applyLastProps('affine:frame', {
                 title: new Text(new Y.Text(`Frame ${frames.length + 1}`)),
-                xywh: Bound.fromPoints([this._startPoint, currentPoint]).serialize(),
-                index: this.gfx.layer.generateIndex(true),
+                xywh: bound.serialize(),
+                // Not the raw back of the stack: a frame drawn on a framework
+                // background must sit just above it, or the author draws blind
+                // behind an opaque map. See `EdgelessFrameManager.frameIndexAt`.
+                index: this.frameManager.frameIndexAt(bound),
                 presentationIndex: this.frameManager.generatePresentationIndex(),
             });
             const id = this.doc.addBlock('affine:frame', props, this.gfx.surface);

package/dist/_pkgs/affine-block-surface/extensions/audit.js

@@ -31,7 +31,7 @@ import { getAuditCriteria, requestAudit, TelemetryProvider, } from '../../affine
 import { GfxControllerIdentifier, GfxPrimitiveElementModel, roleIsA, } from '../../std/gfx/index.js';
 import { z } from 'zod';
 import { backgroundInstanceZones, backgroundPlot, } from '../framework-background/def.js';
-import { backgroundAxisFacts } from '../framework-background/facts.js';
+import { backgroundAxisFacts, containingFrame, } from '../framework-background/facts.js';
 import { ValidationManager, ValidationRuleIdentifier, } from './validation.js';
 /**
  * `map.audit` takes no required parameter: the assistant audits what is
@@ -105,6 +105,7 @@ function collectFrames(rules, elements) {
             const profileId = el.validationProfile;
             frames.push({
                 def,
+                id: el.id,
                 bound: el.elementBound,
                 fact: {
                     elementId: el.id,
@@ -135,41 +136,12 @@ function collectFrames(rules, elements) {
     }
     return frames;
 }
-/** Squared edge-to-edge gap — the same attribution heuristic the engine uses. */
-function gapSquared(frame, bound) {
-    const dx = Math.max(frame.x - bound.maxX, bound.x - frame.maxX, 0);
-    const dy = Math.max(frame.y - bound.maxY, bound.y - frame.maxY, 0);
-    return dx * dx + dy * dy;
-}
-/**
- * The frame an element belongs to: the one that CONTAINS it, failing that the
- * nearest by edge-to-edge gap, ties broken by the smaller id.
- *
- * Deliberately the same answer `attributeBackground` gives inside the engine —
- * an audit that attributed an element to a different map than the rule that
- * indicted it would produce two findings about one component that disagree
- * about which map it is on.
- */
-function attribute(bound, frames) {
-    let nearest = null;
-    let nearestDistance = Infinity;
-    for (const frame of frames) {
-        if (frame.bound.contains(bound))
-            return frame;
-        const distance = gapSquared(frame.bound, bound);
-        if (distance < nearestDistance ||
-            (distance === nearestDistance &&
-                nearest !== null &&
-                frame.fact.elementId < nearest.fact.elementId)) {
-            nearestDistance = distance;
-            nearest = frame;
-        }
-    }
-    return nearest;
-}
 /**
  * Where an element's centre sits inside a frame's PLOT, as ratios.
  *
+ * A POSITION, not a membership test: it is asked only about an element some
+ * frame already contains, and answers where in that frame's plot it lies.
+ *
  * Ratios of the plot and not of the element box: a Wardley transition drawn at
  * `0.4` is 40 % of the PLOT, not of the map element, and the margin between the
  * two is exactly where the axis titles live. `backgroundPlot` is the one place
@@ -262,7 +234,13 @@ export function collectAuditFacts(std) {
         if (role === undefined || frameIds.has(el.id))
             continue;
         const bound = el.elementBound;
-        const frame = attribute(bound, frames);
+        // Membership is WHOLE containment (PF2.4), and there is no nearest-frame
+        // fallback: an element straddling the edge of a map is not on it, so the
+        // audit reports it exactly as it reports one on bare canvas — id and role,
+        // no frame, no position, no zone. Anything else would tell an assistant a
+        // component is on a map the engine is simultaneously indicting it for
+        // hanging off.
+        const frame = containingFrame(bound, frames, candidate => candidate.bound);
         if (frame === null) {
             elementFacts.push({ id: el.id, role });
             continue;

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.d.ts

@@ -1,19 +1,6 @@
 import { nothing, type TemplateResult } from 'lit';
 import { EditorAnchoredPanel } from './editor-anchored-panel.js';
 export declare const READING_PROPOSAL_WIDGET = "affine-reading-proposal-widget";
-/**
- * How the panel names each side of a parent-child relation, keyed under
- * `com.labre.reading.relations.`. Chrome, and only chrome.
- *
- * Exported because it is DATA: the translation-key manifest walks it rather
- * than restating the two wordings, which a source scan could not check — the
- * key is built as a template literal and the fallback reaches `translateKey`
- * through a local helper.
- */
-export declare const RELATION_SIDE_FALLBACK: {
-    readonly consumers: "Consumers (above)";
-    readonly suppliers: "Suppliers (below)";
-};
 /**
  * **The proposal panel** — what the tool reads of one component, offered for
  * confirmation (MF3).
@@ -94,6 +81,14 @@ export declare class ReadingProposalWidget extends EditorAnchoredPanel {
      * host's word into the document.
      */
     private _renderNature;
+    /**
+     * The typed edges touching the subject, grouped by side and named with the
+     * FRAMEWORK's own two words (`ReadingRelationDef.sides`).
+     *
+     * The `data-testid` keeps the shape it shipped with — `reading-consumers`,
+     * `reading-suppliers` — because it names the SIDE, which is generic, and not
+     * the wording, which is now the framework's.
+     */
     private _renderRelations;
     /**
      * **Value flow** — the same typed edges as the relations above, said the way
@@ -110,8 +105,25 @@ export declare class ReadingProposalWidget extends EditorAnchoredPanel {
      * "Value flows up from X to Y"; a host that translates
      * `com.labre.reading.value-flow` gets the same two slots in its own order via
      * the `.to` suffix key.
+     *
+     * ## Why it is gated on the framework's `geometry`
+     *
+     * "Up" is a claim about the board, not about the edge: it is only true where
+     * the framework said the vertical axis carries the order
+     * (`ReadingRelationDef.geometry`). Wardley says it, and this section is the
+     * value chain read from the bottom. Nobody else does, and "value flows up
+     * from Receive order to Check stock" would be a sentence BPMN never said.
      */
     private _renderValueFlow;
+    /**
+     * Where the subject sits along the frame's phase axis.
+     *
+     * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
+     * frame. The empty state below is about a component that could have been on a
+     * map and is not; telling the author of a BPMN task that it is "not on a
+     * framework background" would be answering a question their notation never
+     * asks.
+     */
     private _renderPhase;
     private _renderNaming;
     /**

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.js

@@ -46,18 +46,16 @@ export const READING_PROPOSAL_WIDGET = 'affine-reading-proposal-widget';
 const TAG_SET_ID = 'tag.set';
 const PIVOT_BIND_ID = 'pivot.bind';
 /**
- * How the panel names each side of a parent-child relation, keyed under
- * `com.labre.reading.relations.`. Chrome, and only chrome.
+ * The two sides of a relation, in the order the panel lists them: what needs
+ * the subject first, then what the subject needs.
  *
- * Exported because it is DATA: the translation-key manifest walks it rather
- * than restating the two wordings, which a source scan could not check — the
- * key is built as a template literal and the fallback reaches `translateKey`
- * through a local helper.
+ * The WORDINGS are no longer here. They used to be a chrome table
+ * (`Consumers (above)` / `Suppliers (below)`), which was Wardley's sentence
+ * written into the engine — a BPMN sequence flow has no "above". Each framework
+ * now names its own two sides on its {@link ReadingProfile}, Wardley included,
+ * and restates those very keys and wordings so nothing on a Wardley map moved.
  */
-export const RELATION_SIDE_FALLBACK = {
-    consumers: 'Consumers (above)',
-    suppliers: 'Suppliers (below)',
-};
+const RELATION_SIDES = ['consumer', 'supplier'];
 /**
  * **The proposal panel** — what the tool reads of one component, offered for
  * confirmation (MF3).
@@ -411,24 +409,38 @@ let ReadingProposalWidget = (() => {
           </div>`
                 : nothing}`);
         }
-        _renderRelations(reading) {
-            const consumers = reading.relations.filter(r => r.side === 'consumer');
-            const suppliers = reading.relations.filter(r => r.side === 'supplier');
-            const line = (relations, key) => relations.length
-                ? html `<div class="reading-value" data-testid=${`reading-${key}`}>
-            ${translateKey(this.std, `com.labre.reading.relations.${key}`, RELATION_SIDE_FALLBACK[key])}:
-            ${relations
+        /**
+         * The typed edges touching the subject, grouped by side and named with the
+         * FRAMEWORK's own two words (`ReadingRelationDef.sides`).
+         *
+         * The `data-testid` keeps the shape it shipped with — `reading-consumers`,
+         * `reading-suppliers` — because it names the SIDE, which is generic, and not
+         * the wording, which is now the framework's.
+         */
+        _renderRelations(reading, profile) {
+            const sides = profile.relation?.sides;
+            const line = (side) => {
+                const relations = reading.relations.filter(r => r.side === side);
+                const wording = sides?.[side];
+                // No wording means the framework declared no relation at all, in which
+                // case there is nothing to list either. Silence rather than a heading
+                // this library would have had to invent.
+                if (!relations.length || !wording)
+                    return nothing;
+                return html `<div class="reading-value" data-testid=${`reading-${side}s`}>
+        ${translateKey(this.std, wording.labelKey, wording.labelFallback)}:
+        ${relations
                     .map(relation => relation.otherName || relation.otherId)
                     .join(', ')}
-          </div>`
-                : nothing;
+      </div>`;
+            };
             const contradictions = reading.relations.filter(r => r.contradictsGeometry);
             return this._field('reading-relations', translateKey(this.std, 'com.labre.reading.field.relations', 'Parent-child relations'), html `${reading.relations.length === 0
                 ? html `<div class="reading-empty">
             ${translateKey(this.std, 'com.labre.reading.relations.none', 'No typed link touches this component.')}
           </div>`
                 : nothing}
-      ${line(consumers, 'consumers')} ${line(suppliers, 'suppliers')}
+      ${RELATION_SIDES.map(line)}
       ${contradictions.length
                 ? html `<div class="reading-note" data-testid="reading-contradiction">
             ${translateKey(this.std, 'com.labre.reading.relations.contradiction', 'A link states the opposite of what the positions show')}:
@@ -453,8 +465,18 @@ let ReadingProposalWidget = (() => {
          * "Value flows up from X to Y"; a host that translates
          * `com.labre.reading.value-flow` gets the same two slots in its own order via
          * the `.to` suffix key.
+         *
+         * ## Why it is gated on the framework's `geometry`
+         *
+         * "Up" is a claim about the board, not about the edge: it is only true where
+         * the framework said the vertical axis carries the order
+         * (`ReadingRelationDef.geometry`). Wardley says it, and this section is the
+         * value chain read from the bottom. Nobody else does, and "value flows up
+         * from Receive order to Check stock" would be a sentence BPMN never said.
          */
-        _renderValueFlow(reading) {
+        _renderValueFlow(reading, profile) {
+            if (profile.relation?.geometry !== 'vertical')
+                return nothing;
             const flows = readValueFlows(reading);
             if (flows.length === 0)
                 return nothing;
@@ -468,7 +490,18 @@ let ReadingProposalWidget = (() => {
             ${from} ${flow.from} ${to} ${flow.to}
           </div>`)}`);
         }
-        _renderPhase(reading) {
+        /**
+         * Where the subject sits along the frame's phase axis.
+         *
+         * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
+         * frame. The empty state below is about a component that could have been on a
+         * map and is not; telling the author of a BPMN task that it is "not on a
+         * framework background" would be answering a question their notation never
+         * asks.
+         */
+        _renderPhase(reading, profile) {
+            if (!profile.frame)
+                return nothing;
             const { phase } = reading;
             return this._field('reading-phase', translateKey(this.std, 'com.labre.reading.field.phase', 'Evolution phase'), phase
                 ? html `<div class="reading-value" data-zone-id=${phase.zoneId}>
@@ -600,8 +633,9 @@ let ReadingProposalWidget = (() => {
         ${translateKey(this.std, 'com.labre.reading.panel.title', 'What this map says about this component')}
       </div>`, html `${this._renderNodeType(reading, profile)}
       ${this._renderNature(reading, profile, record, writable)}
-      ${this._renderRelations(reading)} ${this._renderValueFlow(reading)}
-      ${this._renderPhase(reading)} ${this._renderNaming(reading)}
+      ${this._renderRelations(reading, profile)}
+      ${this._renderValueFlow(reading, profile)}
+      ${this._renderPhase(reading, profile)} ${this._renderNaming(reading)}
       ${this._renderRecord(reading, writable)}
       ${writable ? this._renderDrift(reading) : nothing}`);
         }

package/dist/_pkgs/affine-block-surface/extensions/reading.d.ts

@@ -80,6 +80,53 @@ export interface ReadingNamingConvention {
     /** English default, for a host that ships no catalogue. */
     hintFallback: string;
 }
+/**
+ * How a framework names ONE end of its typed relation, in the panel.
+ *
+ * Key plus the framework's own wording, exactly like a role's label or a rule's
+ * message: the host localises it, and a host with no catalogue still reads a
+ * real phrase.
+ */
+export interface ReadingRelationSideLabel {
+    labelKey: string;
+    /** The framework's own English wording, for a host that ships no catalogue. */
+    labelFallback: string;
+}
+/**
+ * The typed edge a reading walks, and the two words the framework reads it
+ * with.
+ *
+ * The wordings live HERE rather than in the panel because they are the
+ * framework's own sentence and nobody else's: "Consumers (above)" is a Wardley
+ * value chain, "Followed by" is a BPMN sequence, "Upstream" is a context map.
+ * The panel used to hard-code the first pair, which is exactly what made the
+ * reading a Wardley feature wearing a generic coat.
+ */
+export interface ReadingRelationDef {
+    edgeRole: RoleId;
+    /**
+     * One wording per side, keyed by what the OTHER end is to the subject — the
+     * same convention {@link ReadingRelation.side} carries. `supplier` labels the
+     * edges LEAVING the subject (the subject is the `source`, i.e. the subject of
+     * the role's verb), `consumer` the edges arriving at it.
+     */
+    sides: Record<ReadingRelationSide, ReadingRelationSideLabel>;
+    /**
+     * The framework claims its board has a VERTICAL reading — that the axis the
+     * elements are drawn along IS the statement of order, so a link and the two
+     * positions can contradict each other.
+     *
+     * Opt-in, and only Wardley opts in: on a value chain a consumer is drawn
+     * above what it needs (ADR 0010 § 5), so an edge pointing the other way is a
+     * disagreement worth reporting. On a BPMN pool, a context map or a storming
+     * roll, "above" means nothing — two tasks side by side are not in conflict —
+     * and a contradiction note there would be a complaint about a drawing that is
+     * perfectly correct. Absent, {@link ReadingRelation.contradictsGeometry} is
+     * always `false`, and the panel also drops the VALUE FLOW section: "value
+     * flows up from X to Y" is the same vertical claim said the other way round.
+     */
+    geometry?: 'vertical';
+}
 /**
  * One framework's reading contract. Every section is optional: a framework that
  * declares only `appliesTo` gets the node-type line and nothing else, which is
@@ -109,9 +156,7 @@ export interface ReadingProfile {
         conventions: readonly ReadingNamingConvention[];
     };
     /** The typed edge whose two ends the relation reading walks. */
-    relation?: {
-        edgeRole: RoleId;
-    };
+    relation?: ReadingRelationDef;
     /** The frame the phase is read from. */
     frame?: {
         backgroundRole: RoleId;
@@ -159,6 +204,10 @@ export interface ReadingRelation {
      * says one thing and the two positions say the other, the reading says so
      * rather than picking a winner: that is W4 seen from the record's side, and
      * the user is the one who decides which of the two was the mistake.
+     *
+     * Always `false` unless the framework declared
+     * {@link ReadingRelationDef.geometry} — a board whose axis carries no order
+     * has nothing to contradict.
      */
     contradictsGeometry: boolean;
 }
@@ -279,6 +328,15 @@ export interface ReadingValueFlow {
 export declare function readValueFlows(reading: ElementReading): ReadingValueFlow[];
 /** The profile governing an element, or `null` — the first match wins. */
 export declare function readingProfileFor(element: GfxPrimitiveElementModel, profiles: readonly ReadingProfile[]): ReadingProfile | null;
+/**
+ * How the engine asks the HOST for a wording — `translateKey`, curried with the
+ * `std` its caller owns.
+ *
+ * A function rather than a scope, so every comparison below stays a pure
+ * function of its arguments and one caller ({@link ReadingManager}) owns the
+ * single `std` read.
+ */
+export type ReadingTranslate = (key: string, fallback: string) => string;
 /**
  * What the LINKED RECORD says about the two fields a reading can compare
  * itself against. Bounded by construction: the profile names at most two host
@@ -341,6 +399,16 @@ export interface ResolvedRecordNature {
  *   its words would be inventing it;
  * - **`values: 'open'`** — the def says any string is a value of this tag, so
  *   everything resolves. That is the def's own claim, not ours.
+ *
+ * ## Why there is no `translate` here, unlike {@link compareReading}
+ *
+ * There is nothing to translate. `TagValueDef.label` is documented as "already
+ * localized by the host" (ADR 0007): a pack is SEEDED with the wording of the
+ * deployment that seeded it, so the label this resolver already matches against
+ * IS the localized one. Adding a resolver would be a parameter that could never
+ * change an answer. The zone labels are the opposite case — they are declared
+ * in the library, in English, with an i18n key beside them — which is why the
+ * phase comparison takes one.
  */
 export declare function resolveRecordNature(def: TagDef | undefined, values: readonly string[]): ResolvedRecordNature;
 /** One field on which the drawing and the record disagree. */
@@ -389,11 +457,19 @@ export declare function readRecord(std: BlockStdScope, element: GfxPrimitiveElem
  * side. `readRecord` has already resolved what CAN be compared; what could not
  * is not a difference of opinion, it is a difference of alphabet.
  *
- * The phase comparison accepts either the zone id or the zone's own wording,
- * because a host is free to store "Product" where the declaration says
- * `product`, and neither spelling is more correct than the other.
+ * The phase comparison accepts the zone id, the zone's own English wording, and
+ * — when a `translate` is handed in — the wording the HOST's catalogue gives
+ * that zone. A French deployment stores "Produit" in its record and reads
+ * `product` off the board; without the third spelling the panel would report a
+ * permanent, false disagreement on a component nobody had moved. Same shape as
+ * the value-id resolution above: a difference of alphabet is not a difference
+ * of opinion.
+ *
+ * `translate` is a PARAMETER rather than a `std` read, so this stays a pure
+ * function of its arguments; {@link ReadingManager} owns the single `std` the
+ * closure is built from.
  */
-export declare function compareReading(reading: ElementReading, record: RecordReading): ReadingDriftField[];
+export declare function compareReading(reading: ElementReading, record: RecordReading, translate?: ReadingTranslate): ReadingDriftField[];
 /** A framework registers its reading profile here; nothing else registers one. */
 export declare const ReadingProfileIdentifier: import("../../global/di/types.js").ServiceIdentifier<ReadingProfile> & (<U extends ReadingProfile = ReadingProfile>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
 /**