package gudusoft.gsqlparser.dlineage.dataflow.model;

import java.util.ArrayList;
import java.util.Collections;
import java.util.IdentityHashMap;
import java.util.List;
import java.util.Map;
import java.util.Stack;
import java.util.concurrent.atomic.AtomicInteger;

import gudusoft.gsqlparser.TCustomSqlStatement;
import gudusoft.gsqlparser.nodes.TResultColumn;
import gudusoft.gsqlparser.dlineage.util.DlineageUtil;
import gudusoft.gsqlparser.nodes.TObjectName;

/**
 * What one dlineage analysis observed while it bound names, recorded for the SQL-LR producer
 * ({@code gudusoft.gsqlparser.lineage.v2.producer}, plan {@code docs/designs/data-lineage/06-sqllr-m2-producer-plan-zh.md}).
 *
 * <p>Internal API: the producer creates a recorder, gives it to the analyzer it runs, and reads it on the analysis
 * thread before {@code dispose()}. The hooks only record: they never change the model, allocate a model id or call
 * a resolver, so legacy output is byte-identical whether a recorder is present or not. With no recorder bound,
 * every hook is one volatile read.</p>
 *
 * <p>A recorder made with {@code producerMode = true} also switches the analysis into SQL-LR production: parsers
 * never guess between candidates, every input is its own unit with its text unchanged, and a failed top-level
 * statement is isolated instead of ending the analysis. Only the producer makes such a recorder; an observe-only
 * recorder ({@link #SqllrObservations()}) changes nothing.</p>
 *
 * <p>Not thread-safe: one recorder belongs to one analysis on one thread.</p>
 *
 * @since 4.2.17
 */
public final class SqllrObservations {

    /** Live recorders in this JVM; the hooks return immediately while it is zero. */
    private static final AtomicInteger ACTIVE = new AtomicInteger();

    /** One relationship element added as a source or set as a target, with the reference it was added under. */
    public static final class ElementRecord {
        private final AbstractRelationship relation;
        private final RelationshipElement<?> element;
        private final boolean target;
        private final TObjectName reference;
        private final TCustomSqlStatement statement;
        private final TCustomSqlStatement topStatement;
        private final long sequence;

        ElementRecord(AbstractRelationship relation, RelationshipElement<?> element, boolean target,
                TObjectName reference, TCustomSqlStatement statement, TCustomSqlStatement topStatement, long sequence) {
            this.relation = relation;
            this.element = element;
            this.target = target;
            this.reference = reference;
            this.statement = statement;
            this.topStatement = topStatement;
            this.sequence = sequence;
        }

        public AbstractRelationship getRelation() {
            return relation;
        }

        public RelationshipElement<?> getElement() {
            return element;
        }

        public boolean isTarget() {
            return target;
        }

        /** The name reference the analysis was processing when it added the element, or {@code null}. */
        public TObjectName getReference() {
            return reference;
        }

        /** The innermost statement being analysed ({@code stmtStack.peek()}). */
        public TCustomSqlStatement getStatement() {
            return statement;
        }

        /** The top-level statement of {@link #getStatement()}. */
        public TCustomSqlStatement getTopStatement() {
            return topStatement;
        }

        /** Recording order. */
        public long getSequence() {
            return sequence;
        }
    }

    /**
     * One name reference the analysis processed for a target, whether or not it added a source: a reference that
     * bound nothing (an ambiguous or unknown name) is still an attempted read.
     */
    public static final class ReferenceRecord {
        private final TObjectName reference;
        private final Object target;
        private final TCustomSqlStatement statement;
        private final TCustomSqlStatement topStatement;
        private final long sequence;

        ReferenceRecord(TObjectName reference, Object target, TCustomSqlStatement statement,
                TCustomSqlStatement topStatement, long sequence) {
            this.reference = reference;
            this.target = target;
            this.statement = statement;
            this.topStatement = topStatement;
            this.sequence = sequence;
        }

        public TObjectName getReference() {
            return reference;
        }

        /** The model object the reference was read for (the frame's target), or {@code null}. */
        public Object getTarget() {
            return target;
        }

        public TCustomSqlStatement getStatement() {
            return statement;
        }

        public TCustomSqlStatement getTopStatement() {
            return topStatement;
        }

        public long getSequence() {
            return sequence;
        }
    }

    /** One analysed top-level statement and how its analysis ended. */
    public static final class StatementRecord {
        private final TCustomSqlStatement statement;
        private final int unitIndex;
        private final boolean primary;
        private Throwable failure;
        private boolean finished;

        StatementRecord(TCustomSqlStatement statement, int unitIndex, boolean primary) {
            this.statement = statement;
            this.unitIndex = unitIndex;
            this.primary = primary;
        }

        /**
         * Whether the statement is one of its unit's parsed top-level statements; false for a statement the analysis
         * derived (dynamic SQL text) and analysed as a top-level statement of its own.
         */
        public boolean isPrimary() {
            return primary;
        }

        public TCustomSqlStatement getStatement() {
            return statement;
        }

        /** The index of the input (the analyzer's {@code SqlInfo[]}) the statement was parsed from, or -1. */
        public int getUnitIndex() {
            return unitIndex;
        }

        /** The exception that ended the statement's analysis, or {@code null}. */
        public Throwable getFailure() {
            return failure;
        }

        public boolean isFinished() {
            return finished;
        }
    }

    /**
     * A relationship as it stood when the analysis finished, before output materialization changed the model. Only
     * the relationship's target and sources are copied; the model objects they hold stay live, so a reader takes a
     * result set's columns from {@link #getFrozenColumns} and never from the live model.
     */
    public static final class FrozenRelation {
        private final AbstractRelationship relation;
        private final RelationshipElement<?> target;
        private final List<RelationshipElement<?>> sources;

        FrozenRelation(AbstractRelationship relation) {
            this.relation = relation;
            this.target = relation.getTarget();
            this.sources = Collections.unmodifiableList(new ArrayList<RelationshipElement<?>>(relation.getSources()));
        }

        public AbstractRelationship getRelation() {
            return relation;
        }

        public RelationshipElement<?> getTarget() {
            return target;
        }

        public List<RelationshipElement<?>> getSources() {
            return sources;
        }
    }

    /** One reference frame: the target its loop reads for and the reference of the current iteration. */
    private static final class Frame {
        final Object target;
        TObjectName reference;

        Frame(Object target) {
            this.target = target;
        }
    }

    private final boolean producerMode;
    private final List<Frame> frames = new ArrayList<Frame>();
    private final List<ElementRecord> elements = new ArrayList<ElementRecord>();
    private final List<ReferenceRecord> references = new ArrayList<ReferenceRecord>();
    private Map<ResultSet, List<ResultColumn>> frozenColumns;
    private List<ResultSet> frozenResultSets;
    private final Map<TCustomSqlStatement, StatementRecord> statements =
            new IdentityHashMap<TCustomSqlStatement, StatementRecord>();
    private final List<StatementRecord> statementOrder = new ArrayList<StatementRecord>();
    private final Map<String, Integer> unitIndexes = new java.util.HashMap<String, Integer>();
    private int currentUnit = -1;
    private List<FrozenRelation> frozen;
    private boolean closed;
    private long sequence;

    /**
     * Builds the value snapshot (plan 09, Section 3.1) alongside the live records. A failure while building it never
     * reaches the analysis: the snapshot is dropped and the failure kept ({@link #getSnapshotFailure()}).
     */
    private SnapshotRecorder snapshotRecorder = new SnapshotRecorder();
    private SqllrSnapshot snapshot;
    private String snapshotFailure;
    private long snapshotNanos = -1;

    private void snapshotFailed(String where, Throwable e) {
        if (snapshotFailure == null) {
            snapshotFailure = where + ": " + e;
        }
        snapshotRecorder = null;
    }

    /** An observe-only recorder: the analysis behaves exactly as without it. */
    public SqllrObservations() {
        this(false);
    }

    /**
     * @param producerMode true only for the SQL-LR producer's own analysis, which this switches into production
     *                     (see the class comment)
     */
    public SqllrObservations(boolean producerMode) {
        this.producerMode = producerMode;
        ACTIVE.incrementAndGet();
    }

    /** Whether the bound analysis runs as SQL-LR production rather than only being observed. */
    public boolean isProducerMode() {
        return producerMode;
    }

    /** Stops recording; the hooks of other analyses no longer pay for this recorder. Idempotent. */
    public void close() {
        if (!closed) {
            closed = true;
            ACTIVE.decrementAndGet();
        }
    }

    /** The recorder of the analysis bound to the current thread, or {@code null}. */
    public static SqllrObservations current() {
        if (ACTIVE.get() == 0) {
            return null;
        }
        ModelBindingManager manager = ModelBindingManager.get();
        SqllrObservations observations = manager == null ? null : manager.getSqllrObservations();
        return observations == null || observations.closed ? null : observations;
    }

    // ---------------------------------------------------------------------------------------------
    // Reference frames: the analysis opens a frame around a loop over name references and names the reference of
    // each iteration. A nested analysis opens a barrier (a frame with no reference) over its whole body, so neither
    // its own elements nor those it adds outside its loops inherit the reference of the loop that called it.
    // ---------------------------------------------------------------------------------------------

    /** Opens a barrier: elements added until it closes carry no reference unless an inner frame names one. */
    public int openFrame() {
        return openFrame(null);
    }

    /**
     * Opens a frame for a loop that reads references for {@code target}; pass the result to {@link #reference} and
     * {@link #closeFrame}.
     */
    public int openFrame(Object target) {
        frames.add(new Frame(target));
        return frames.size() - 1;
    }

    /** The reference the frame is processing from now on; recorded as an attempted read of the frame's target. */
    public void reference(int frame, TObjectName name) {
        if (frame >= 0 && frame < frames.size()) {
            Frame f = frames.get(frame);
            f.reference = name;
            if (name != null && frozen == null) {
                TCustomSqlStatement statement = currentStatement();
                TCustomSqlStatement top = statement == null ? null : DlineageUtil.getTopStmt(statement);
                long at = sequence++;
                references.add(new ReferenceRecord(name, f.target, statement, top, at));
                if (snapshotRecorder != null) {
                    try {
                        snapshotRecorder.referenceEvent(at, name, f.target, statement, top);
                    } catch (RuntimeException e) {
                        snapshotFailed("reference", e);
                    }
                }
            }
        }
    }

    /** Closes the frame and any frame a failed nested analysis left open above it. */
    public void closeFrame(int frame) {
        while (frame >= 0 && frames.size() > frame) {
            frames.remove(frames.size() - 1);
        }
    }

    private TObjectName currentReference() {
        return frames.isEmpty() ? null : frames.get(frames.size() - 1).reference;
    }

    private static TCustomSqlStatement currentStatement() {
        Stack<TCustomSqlStatement> stack = ModelBindingManager.getGlobalStmtStack();
        return stack == null || stack.isEmpty() ? null : stack.peek();
    }

    // ---------------------------------------------------------------------------------------------
    // Hooks
    // ---------------------------------------------------------------------------------------------

    /** Called by {@link AbstractRelationship#addSource} before its de-duplication, so {@code a + a} is seen twice. */
    void onSource(AbstractRelationship relation, RelationshipElement<?> element) {
        record(relation, element, false);
    }

    /** Called by {@link AbstractRelationship#setTarget}. */
    void onTarget(AbstractRelationship relation, RelationshipElement<?> element) {
        record(relation, element, true);
    }

    private void record(AbstractRelationship relation, RelationshipElement<?> element, boolean target) {
        if (element == null || frozen != null) {
            return;
        }
        TCustomSqlStatement statement = currentStatement();
        TCustomSqlStatement top = statement == null ? null : DlineageUtil.getTopStmt(statement);
        if (injectDuringPrefix != null && top != null && top.toString().trim().startsWith(injectDuringPrefix)) {
            injectDuringPrefix = null;
            if (injectError) {
                throw new AssertionError("injected error");
            }
            throw new IllegalStateException("injected failure during the analysis");
        }
        long at = sequence++;
        elements.add(new ElementRecord(relation, element, target, currentReference(), statement, top, at));
        if (snapshotRecorder != null) {
            try {
                snapshotRecorder.elementEvent(at, relation, element, target, currentReference(), statement, top);
            } catch (RuntimeException e) {
                snapshotFailed("element", e);
            }
        }
    }

    // ---------------------------------------------------------------------------------------------
    // Statement entries and fallback decisions (observe-only; snapshot only)
    // ---------------------------------------------------------------------------------------------

    /** The analysis enters a statement: every statement it analyses, nested and dynamic ones included. */
    public void enterStatement(TCustomSqlStatement statement) {
        if (snapshotRecorder == null || frozen != null) {
            return;
        }
        try {
            snapshotRecorder.enter(statement);
        } catch (RuntimeException e) {
            snapshotFailed("enter", e);
        }
    }

    /** An orphan column linked to the first FROM item ({@code Option.linkOrphanColumnToFirstTable}). */
    public static final String DECISION_ORPHAN_FIRST_TABLE = "ORPHAN_FIRST_TABLE";
    /** An orphan column with a qualified prefix linked to a pseudo table named after the prefix. */
    public static final String DECISION_ORPHAN_PSEUDO_TABLE = "ORPHAN_PSEUDO_TABLE";
    /** An ARRAY_AGG ORDER BY key linked to the first FROM item, written back to the parse tree. */
    public static final String DECISION_ARRAY_AGG_ORDER_BY_FIRST_TABLE = "ARRAY_AGG_ORDER_BY_FIRST_TABLE";
    /** The array an UNNEST reads taken from the first FROM item. */
    public static final String DECISION_UNNEST_FIRST_TABLE = "UNNEST_FIRST_TABLE";
    /** A column bound to the first FROM item that lists a column of its name ({@code ModelBindingManager.getTable}). */
    public static final String DECISION_FIRST_TABLE_WITH_COLUMN = "FIRST_TABLE_WITH_COLUMN";
    /** A column bound to any table the run has seen with a column of its name ({@code guessTable}). */
    public static final String DECISION_GUESS_TABLE = "GUESS_TABLE";

    /**
     * The analysis decided a binding by a fallback (plan 06, Section 3.3): called before it acts on the decision, so
     * the reference is recorded as it stood. {@code selected} is the parse tree node or model object chosen.
     */
    public void decision(String id, TObjectName reference, Object selected, String reason) {
        if (snapshotRecorder == null || frozen != null) {
            return;
        }
        try {
            snapshotRecorder.decision(sequence++, id, reference, selected, reason, currentStatement());
        } catch (RuntimeException e) {
            snapshotFailed("decision", e);
        }
    }

    /** The analyzer keyed input {@code index} as {@code unitKey}. */
    public void registerUnit(String unitKey, int index) {
        unitIndexes.put(unitKey, Integer.valueOf(index));
    }

    /** The analyzer starts the statements of the unit with this key. */
    public void beginUnit(String unitKey) {
        Integer index = unitIndexes.get(unitKey);
        currentUnit = index == null ? -1 : index.intValue();
    }

    /** One parsed unit: its top-level statements and syntax errors, copied when it was parsed. */
    public static final class UnitRecord {
        private final int unitIndex;
        private final int parseResult;
        private final List<TCustomSqlStatement> statements;
        private final List<gudusoft.gsqlparser.TSyntaxError> syntaxErrors;
        private final List<gudusoft.gsqlparser.TSyntaxError> recoveredSyntaxErrors;
        private final String parsedText;

        UnitRecord(int unitIndex, gudusoft.gsqlparser.TGSqlParser parser, int parseResult) {
            this.unitIndex = unitIndex;
            this.parseResult = parseResult;
            this.parsedText = parser.sqltext;
            List<TCustomSqlStatement> list = new ArrayList<TCustomSqlStatement>();
            if (parser.sqlstatements != null) {
                for (int i = 0; i < parser.sqlstatements.size(); i++) {
                    list.add(parser.sqlstatements.get(i));
                }
            }
            this.statements = Collections.unmodifiableList(list);
            List<gudusoft.gsqlparser.TSyntaxError> errors = new ArrayList<gudusoft.gsqlparser.TSyntaxError>();
            if (parser.getSyntaxErrors() != null) {
                errors.addAll(parser.getSyntaxErrors());
            }
            this.syntaxErrors = Collections.unmodifiableList(errors);
            List<gudusoft.gsqlparser.TSyntaxError> recovered = new ArrayList<gudusoft.gsqlparser.TSyntaxError>();
            if (parser.getRecoveredSyntaxErrors() != null) {
                recovered.addAll(parser.getRecoveredSyntaxErrors());
            }
            this.recoveredSyntaxErrors = Collections.unmodifiableList(recovered);
        }

        public int getUnitIndex() {
            return unitIndex;
        }

        /** The result of {@code TGSqlParser.parse()} for the unit: 0 when it parsed without error. */
        public int getParseResult() {
            return parseResult;
        }

        /** The top-level statements of the unit, in text order; valid until the analyzer is disposed. */
        public List<TCustomSqlStatement> getStatements() {
            return statements;
        }

        public List<gudusoft.gsqlparser.TSyntaxError> getSyntaxErrors() {
            return syntaxErrors;
        }

        /** The text the parser read for the unit. */
        public String getParsedText() {
            return parsedText;
        }

        /** Errors of statements routine-body recovery skipped: the parse "succeeded" without them. */
        public List<gudusoft.gsqlparser.TSyntaxError> getRecoveredSyntaxErrors() {
            return recoveredSyntaxErrors;
        }
    }

    private final List<UnitRecord> units = new ArrayList<UnitRecord>();

    /** The analyzer parsed the unit it announced with {@link #beginUnit}. */
    public void parsedUnit(gudusoft.gsqlparser.TGSqlParser parser, int parseResult) {
        // The analysis parses every input with one parser, whose token list the next parse clears and refills, so the
        // tokens of an earlier input would find the next input's tokens at their positions. Right after its parse,
        // before it is analysed or recorded, an input's tokens get a list of their own, in their order, so that
        // whatever reads its trees later (SQL-LR spans and keyword scans, the snapshot recorder) finds its own
        // neighbours. Producer mode only: an observe-only recorder leaves the analysis exactly as without it (Codex
        // 13a #6).
        gudusoft.gsqlparser.TSourceTokenList shared = parser == null || !producerMode ? null : parser.sourcetokenlist;
        if (shared != null) {
            gudusoft.gsqlparser.TSourceTokenList own = new gudusoft.gsqlparser.TSourceTokenList();
            own.setGsqlparser(parser);
            for (int i = 0; i < shared.size(); i++) {
                own.add(shared.get(i));
            }
            for (int i = 0; i < own.size(); i++) {
                if (own.get(i).container == shared) {
                    own.get(i).container = own;
                }
            }
        }
        units.add(new UnitRecord(currentUnit, parser, parseResult));
    }

    /** The parsed units, in analysis order. */
    public List<UnitRecord> getUnits() {
        return Collections.unmodifiableList(units);
    }

    /** A statement of dynamic SQL text the analysis parsed, with the statement whose analysis parsed it (its site). */
    public static final class DerivedRecord {
        private final TCustomSqlStatement statement;
        private final TCustomSqlStatement site;

        DerivedRecord(TCustomSqlStatement statement, TCustomSqlStatement site) {
            this.statement = statement;
            this.site = site;
        }

        public TCustomSqlStatement getStatement() {
            return statement;
        }

        public TCustomSqlStatement getSite() {
            return site;
        }
    }

    private final Map<Object, TResultColumn> structItems = new java.util.IdentityHashMap<Object, TResultColumn>();
    private final List<Object> structOrder = new ArrayList<Object>();

    /** A column the analysis built for a field of a STRUCT that a select item constructs. Observe-only. */
    public void structField(Object column, TResultColumn item) {
        if (structItems.put(column, item) == null) {
            structOrder.add(column);
        }
        if (snapshotRecorder != null) {
            try {
                snapshotRecorder.model(column);
            } catch (RuntimeException e) {
                snapshotFailed("struct field", e);
            }
        }
    }

    /** The select item whose STRUCT a field column belongs to, or null. */
    public TResultColumn getStructItem(Object column) {
        return structItems.get(column);
    }

    /** The field columns {@link #structField} recorded, in the order it first recorded them. */
    public List<Object> getStructFieldColumns() {
        return Collections.unmodifiableList(structOrder);
    }

    private final List<DerivedRecord> derived = new ArrayList<DerivedRecord>();

    /** A statement of dynamic SQL text is analysed, inside the analysis of {@code site}. Observe-only. */
    public void derivedStatement(TCustomSqlStatement statement, TCustomSqlStatement site) {
        if (statement != null) {
            derived.add(new DerivedRecord(statement, site));
            if (snapshotRecorder != null) {
                snapshotRecorder.handle(statement);
                snapshotRecorder.handle(site);
            }
        }
    }

    /** The statements of dynamic SQL texts, in analysis order. */
    public List<DerivedRecord> getDerived() {
        return Collections.unmodifiableList(derived);
    }

    /** A top-level statement's analysis starts. */
    public void beginStatement(TCustomSqlStatement statement) {
        if (statement == null || statements.containsKey(statement)) {
            return;
        }
        boolean primary = false;
        if (!units.isEmpty()) {
            for (TCustomSqlStatement s : units.get(units.size() - 1).getStatements()) {
                if (s == statement) {
                    primary = true;
                    break;
                }
            }
        }
        StatementRecord record = new StatementRecord(statement, currentUnit, primary);
        statements.put(statement, record);
        statementOrder.add(record);
        if (snapshotRecorder != null) {
            try {
                snapshotRecorder.statement(statement, null);
            } catch (RuntimeException e) {
                snapshotFailed("statement", e);
            }
        }
        checkInjectedFailure(statement, true);
    }

    private String injectPrefix;
    private boolean injectBefore;
    private String injectDuringPrefix;
    private boolean injectError;

    /**
     * Tests only: make the analysis of the first top-level statement whose text starts with {@code prefix} fail,
     * before its analysis ({@code before}) or after it changed the model. Exercises the failure isolation of SQL-LR
     * production.
     */
    public void injectFailure(String prefix, boolean before) {
        this.injectPrefix = prefix;
        this.injectBefore = before;
    }

    /**
     * Tests only: make the analysis of the first top-level statement whose text starts with {@code prefix} fail inside
     * the analysis, when it records its first relationship element; with {@code error} the failure is a
     * {@code java.lang.Error}.
     */
    public void injectFailureDuring(String prefix, boolean error) {
        this.injectDuringPrefix = prefix;
        this.injectError = error;
    }

    /** Called by the analyzer: throws the injected failure for this statement and point, if any. */
    public void checkInjectedFailure(TCustomSqlStatement statement, boolean before) {
        if (injectPrefix != null && before == injectBefore && statement.toString().trim().startsWith(injectPrefix)) {
            injectPrefix = null;
            throw new IllegalStateException("injected failure");
        }
    }

    /** A top-level statement's analysis ended, normally ({@code failure == null}) or with an exception. */
    public void endStatement(TCustomSqlStatement statement, Throwable failure) {
        StatementRecord record = statements.get(statement);
        if (record != null) {
            record.finished = true;
            if (failure != null && record.failure == null) {
                record.failure = failure;
            }
        }
    }

    /**
     * Freezes the runtime graph when the analysis is complete and before output materialization changes it
     * ({@code SELECT *} links, inferred sources). Later hook calls are ignored.
     */
    public void freeze(ModelBindingManager manager) {
        if (frozen != null) {
            return;
        }
        List<FrozenRelation> list = new ArrayList<FrozenRelation>();
        Map<ResultSet, List<ResultColumn>> columns = new IdentityHashMap<ResultSet, List<ResultColumn>>();
        List<ResultSet> resultSets = new ArrayList<ResultSet>();
        for (Object rs : manager.getResultSets()) {
            if (rs instanceof ResultSet && !columns.containsKey(rs)) {
                columns.put((ResultSet) rs, Collections.unmodifiableList(
                        new ArrayList<ResultColumn>(((ResultSet) rs).getColumns())));
                resultSets.add((ResultSet) rs);
            }
        }
        for (Relationship relation : manager.getRelations()) {
            if (relation instanceof AbstractRelationship) {
                FrozenRelation f = new FrozenRelation((AbstractRelationship) relation);
                list.add(f);
                freezeColumns(f.getTarget(), columns, resultSets);
                for (RelationshipElement<?> source : f.getSources()) {
                    freezeColumns(source, columns, resultSets);
                }
            }
        }
        frozen = Collections.unmodifiableList(list);
        frozenColumns = columns;
        frozenResultSets = Collections.unmodifiableList(resultSets);
        if (snapshotRecorder != null) {
            long started = System.nanoTime();
            try {
                snapshot = snapshotRecorder.freeze(manager, frozen, frozenColumns, statementOrder, units, derived,
                        structItems);
                snapshotNanos = System.nanoTime() - started;
            } catch (RuntimeException e) {
                snapshotFailed("freeze", e);
            }
            snapshotRecorder = null; // the snapshot holds values only; the live objects it read are released
        }
        if (freezeHook != null) {
            try {
                freezeHook.frozen(this);
            } catch (RuntimeException | StackOverflowError e) {
                freezeHookFailure = e;
            }
        }
    }

    /**
     * The value snapshot of the analysis (plan 09, Section 3.1), taken at {@link #freeze}; {@code null} before the
     * freeze or when building it failed ({@link #getSnapshotFailure()}). It holds no live object and stays readable
     * after the analyzer is disposed, from any thread.
     */
    public SqllrSnapshot getSnapshot() {
        return snapshot;
    }

    /** Why the snapshot could not be built, or {@code null}. */
    public String getSnapshotFailure() {
        return snapshotFailure;
    }

    /** Called at the end of {@link #freeze}: the SQL-LR producer projects what it reads there (plan 09, slice 1b). */
    public interface FreezeHook {
        void frozen(SqllrObservations observations);
    }

    private FreezeHook freezeHook;
    private Throwable freezeHookFailure;

    /** The producer's hook, run once when the analysis freezes; a failure is kept, never thrown into the analysis. */
    public void setFreezeHook(FreezeHook hook) {
        this.freezeHook = hook;
    }

    /** What the freeze hook threw, or {@code null}. */
    public Throwable getFreezeHookFailure() {
        return freezeHookFailure;
    }

    /** How long building the snapshot's topology at the freeze took, in nanoseconds; -1 when it was not built. */
    public long getSnapshotNanos() {
        return snapshotNanos;
    }

    /** Output materialization adds the columns a {@code SELECT *} expands to: the producer reads the list as it was. */
    private static void freezeColumns(RelationshipElement<?> element, Map<ResultSet, List<ResultColumn>> columns,
            List<ResultSet> resultSets) {
        Object model = element == null ? null : element.getElement();
        if (model instanceof ResultColumn) {
            ResultSet rs = ((ResultColumn) model).getResultSet();
            if (rs != null && !columns.containsKey(rs)) {
                columns.put(rs, Collections.unmodifiableList(new ArrayList<ResultColumn>(rs.getColumns())));
                resultSets.add(rs);
            }
        }
    }

    /** Every result set at the freeze (the model's, then any only a relationship reaches), in creation order. */
    public List<ResultSet> getFrozenResultSets() {
        return frozenResultSets;
    }

    /**
     * The columns of a result set at the freeze, or {@code null} when no frozen relationship reaches the result set.
     */
    public List<ResultColumn> getFrozenColumns(ResultSet resultSet) {
        return frozenColumns == null ? null : frozenColumns.get(resultSet);
    }

    /** Every reference the analysis read for a target, in recording order. */
    public List<ReferenceRecord> getReferences() {
        return Collections.unmodifiableList(references);
    }

    public boolean isFrozen() {
        return frozen != null;
    }

    /** The relationships at the freeze, in creation order; {@code null} before {@link #freeze}. */
    public List<FrozenRelation> getFrozenRelations() {
        return frozen;
    }

    /** Every recorded element, in recording order. */
    public List<ElementRecord> getElements() {
        return Collections.unmodifiableList(elements);
    }

    /** The analysed top-level statements, in the order their analysis started. */
    public List<StatementRecord> getStatements() {
        return Collections.unmodifiableList(statementOrder);
    }
}