package gudusoft.gsqlparser.dlineage.dataflow.model;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
 * An immutable value projection of what one dlineage analysis observed and built, for the SQL-LR producer (plan
 * {@code docs/designs/data-lineage/09-sqllr-v2-runtime-driven-coverage-plan-zh.md}, Section 3.1).
 *
 * <p>The snapshot holds values only: strings, numbers, flags and handles. It never holds a runtime model object, a
 * parse tree node, a token, a parser, a resolver namespace, a catalog, a {@code Throwable} or anything that reads a
 * {@code ThreadLocal}, so it stays readable after the analyzer is disposed and from any thread. Records refer to each
 * other by handle: every object of the analysis (statement, name reference, model node, relationship, parse text) gets
 * one handle, the first time the recorder sees it, and keeps it. Handle 0 means none.</p>
 *
 * <p>Two kinds of values are kept apart. Events ({@link ElementEvent}, {@link ReferenceEvent}, {@link Name},
 * {@link Statement}) are copied when they happen, before the analysis de-duplicates or rewrites anything:
 * {@code a + a} is two element events. The topology ({@link Node}, {@link Relation}, {@link Contribution}) is copied
 * once, when the analysis is complete and before output materialization changes the model: {@code a + a} is one
 * contribution, which lists both of its events.</p>
 *
 * <p>Internal API of the SQL-LR producer.</p>
 *
 * @since 4.2.17
 */
public final class SqllrSnapshot {

    static <T> List<T> copy(List<T> list) {
        return list == null || list.isEmpty() ? Collections.<T>emptyList()
                : Collections.unmodifiableList(new ArrayList<T>(list));
    }

    private static void field(StringBuilder out, String name, Object value) {
        out.append(name).append('=');
        if (value == null) {
            out.append('~');
        } else if (value instanceof String) {
            String s = (String) value;
            out.append(s.length()).append(':').append(s);
        } else if (value instanceof Writable) {
            out.append('{');
            ((Writable) value).write(out);
            out.append('}');
        } else if (value instanceof List) {
            out.append('[');
            for (Object o : (List<?>) value) {
                field(out, "", o);
                out.append(',');
            }
            out.append(']');
        } else {
            out.append(value);
        }
        out.append(';');
    }

    /** A record that writes itself canonically, for {@link #digest()}. */
    interface Writable {
        void write(StringBuilder out);
    }

    // ---------------------------------------------------------------------------------------------
    // Positions in parse texts
    // ---------------------------------------------------------------------------------------------

    /** A source token as the parse left it when it was copied. */
    public static final class Token implements Writable {
        private final long text;
        private final int position;
        private final long line;
        private final long column;
        private final long offset;
        private final String spelling;
        private final String type;

        Token(long text, int position, long line, long column, long offset, String spelling, String type) {
            this.text = text;
            this.position = position;
            this.line = line;
            this.column = column;
            this.offset = offset;
            this.spelling = spelling;
            this.type = type;
        }

        /** The handle of the parse text ({@link Text}) the token belongs to, or 0. */
        public long getText() {
            return text;
        }

        /** The index of the token in its parse text. */
        public int getPosition() {
            return position;
        }

        public long getLine() {
            return line;
        }

        public long getColumn() {
            return column;
        }

        /** The offset of the token in its parse text, as the lexer counted it. */
        public long getOffset() {
            return offset;
        }

        /** The token as written. */
        public String getSpelling() {
            return spelling;
        }

        /** The token type ({@code ETokenType} name). */
        public String getType() {
            return type;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "x", Long.valueOf(text));
            field(out, "p", Integer.valueOf(position));
            field(out, "l", Long.valueOf(line));
            field(out, "c", Long.valueOf(column));
            field(out, "o", Long.valueOf(offset));
            field(out, "s", spelling);
            field(out, "t", type);
        }
    }

    /** Where a parse tree node lies: its class and its first and last tokens. */
    public static final class Anchor implements Writable {
        private final String nodeClass;
        private final Token start;
        private final Token end;

        Anchor(String nodeClass, Token start, Token end) {
            this.nodeClass = nodeClass;
            this.start = start;
            this.end = end;
        }

        /** The simple name of the node's class. */
        public String getNodeClass() {
            return nodeClass;
        }

        public Token getStart() {
            return start;
        }

        public Token getEnd() {
            return end;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "k", nodeClass);
            field(out, "s", start);
            field(out, "e", end);
        }
    }

    /** One parse text (a token list): an input unit's, or one the analysis parsed from dynamic SQL. */
    public static final class Text implements Writable {
        private final long handle;
        private final int unit;
        private final String text;

        Text(long handle, int unit, String text) {
            this.handle = handle;
            this.unit = unit;
            this.text = text;
        }

        public long getHandle() {
            return handle;
        }

        /** The input unit whose parse made the text, or -1 for a text the analysis parsed itself. */
        public int getUnit() {
            return unit;
        }

        /** The text: its tokens, concatenated. */
        public String getText() {
            return text;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "h", Long.valueOf(handle));
            field(out, "u", Integer.valueOf(unit));
            field(out, "t", text);
        }
    }

    /** A syntax error of a parsed unit. */
    public static final class SyntaxError implements Writable {
        private final String token;
        private final long line;
        private final long column;
        private final String errorType;
        private final int errorNo;
        private final String hint;

        SyntaxError(String token, long line, long column, String errorType, int errorNo, String hint) {
            this.token = token;
            this.line = line;
            this.column = column;
            this.errorType = errorType;
            this.errorNo = errorNo;
            this.hint = hint;
        }

        public String getToken() {
            return token;
        }

        public long getLine() {
            return line;
        }

        public long getColumn() {
            return column;
        }

        public String getErrorType() {
            return errorType;
        }

        public int getErrorNo() {
            return errorNo;
        }

        public String getHint() {
            return hint;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "t", token);
            field(out, "l", Long.valueOf(line));
            field(out, "c", Long.valueOf(column));
            field(out, "k", errorType);
            field(out, "n", Integer.valueOf(errorNo));
            field(out, "h", hint);
        }
    }

    /** One parsed input unit. */
    public static final class Unit implements Writable {
        private final int index;
        private final int parseResult;
        private final long text;
        private final List<Long> statements;
        private final List<SyntaxError> syntaxErrors;
        private final List<SyntaxError> recoveredSyntaxErrors;

        Unit(int index, int parseResult, long text, List<Long> statements, List<SyntaxError> syntaxErrors,
                List<SyntaxError> recoveredSyntaxErrors) {
            this.index = index;
            this.parseResult = parseResult;
            this.text = text;
            this.statements = copy(statements);
            this.syntaxErrors = copy(syntaxErrors);
            this.recoveredSyntaxErrors = copy(recoveredSyntaxErrors);
        }

        public int getIndex() {
            return index;
        }

        public int getParseResult() {
            return parseResult;
        }

        /** The handle of the parse text the parser read for the unit. */
        public long getText() {
            return text;
        }

        /** The handles of the unit's top-level statements, in text order. */
        public List<Long> getStatements() {
            return statements;
        }

        public List<SyntaxError> getSyntaxErrors() {
            return syntaxErrors;
        }

        public List<SyntaxError> getRecoveredSyntaxErrors() {
            return recoveredSyntaxErrors;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "i", Integer.valueOf(index));
            field(out, "r", Integer.valueOf(parseResult));
            field(out, "x", Long.valueOf(text));
            field(out, "s", statements);
            field(out, "e", syntaxErrors);
            field(out, "v", recoveredSyntaxErrors);
        }
    }

    // ---------------------------------------------------------------------------------------------
    // Statements and name references (events: copied when first seen)
    // ---------------------------------------------------------------------------------------------

    /** A statement the analysis worked in, copied when first seen. */
    public static final class Statement implements Writable {
        private final long handle;
        private final String statementClass;
        private final String statementType;
        private final long stackParent;
        private final long parent;
        private final Anchor anchor;
        private final int entries;
        private final boolean analysed;
        private final int unit;
        private final boolean primary;
        private final boolean finished;
        private final String failureClass;
        private final String failureMessage;

        Statement(long handle, String statementClass, String statementType, long stackParent, long parent,
                Anchor anchor, int entries, boolean analysed, int unit, boolean primary, boolean finished,
                String failureClass, String failureMessage) {
            this.handle = handle;
            this.statementClass = statementClass;
            this.statementType = statementType;
            this.stackParent = stackParent;
            this.parent = parent;
            this.anchor = anchor;
            this.entries = entries;
            this.analysed = analysed;
            this.unit = unit;
            this.primary = primary;
            this.finished = finished;
            this.failureClass = failureClass;
            this.failureMessage = failureMessage;
        }

        public long getHandle() {
            return handle;
        }

        public String getStatementClass() {
            return statementClass;
        }

        /** The statement type ({@code ESqlStatementType} name). */
        public String getStatementType() {
            return statementType;
        }

        /**
         * The statement the analysis was working in when it entered this one (the entry below it on the analysis's
         * statement stack), or 0 for a statement analysed at the top.
         */
        public long getStackParent() {
            return stackParent;
        }

        /** The parse tree's parent statement, or 0. */
        public long getParent() {
            return parent;
        }

        public Anchor getAnchor() {
            return anchor;
        }

        /**
         * How many times the analysis entered the statement ({@code analyzeCustomSqlStmt}), nested statements and
         * statements of dynamic SQL included; 0 for a statement it only reached (a parse parent, a query's SELECT).
         */
        public int getEntries() {
            return entries;
        }

        /** Whether the analysis analysed the statement as a top-level statement of its own. */
        public boolean isAnalysed() {
            return analysed;
        }

        /** For an analysed statement, the input unit it was parsed from, or -1. */
        public int getUnit() {
            return unit;
        }

        /** For an analysed statement, whether it is one of its unit's parsed top-level statements. */
        public boolean isPrimary() {
            return primary;
        }

        /** For an analysed statement, whether its analysis ended. */
        public boolean isFinished() {
            return finished;
        }

        /** For an analysed statement whose analysis failed, the exception's class name, else null. */
        public String getFailureClass() {
            return failureClass;
        }

        public String getFailureMessage() {
            return failureMessage;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "h", Long.valueOf(handle));
            field(out, "c", statementClass);
            field(out, "t", statementType);
            field(out, "sp", Long.valueOf(stackParent));
            field(out, "p", Long.valueOf(parent));
            field(out, "a", anchor);
            field(out, "en", Integer.valueOf(entries));
            field(out, "an", Boolean.valueOf(analysed));
            field(out, "u", Integer.valueOf(unit));
            field(out, "pr", Boolean.valueOf(primary));
            field(out, "f", Boolean.valueOf(finished));
            field(out, "fc", failureClass);
            field(out, "fm", failureMessage);
        }
    }

    /** A name reference the analysis read, copied when first seen. */
    public static final class Name implements Writable {
        private final long handle;
        private final String objectType;
        private final Anchor anchor;
        private final String spelling;
        private final Token server;
        private final Token database;
        private final Token schema;
        private final Token object;
        private final Token part;
        private final Token pkg;
        private final boolean wildcard;
        private final String resolution;
        private final String sourceNamespace;

        Name(long handle, String objectType, Anchor anchor, String spelling, Token server, Token database,
                Token schema, Token object, Token part, Token pkg, boolean wildcard, String resolution,
                String sourceNamespace) {
            this.handle = handle;
            this.objectType = objectType;
            this.anchor = anchor;
            this.spelling = spelling;
            this.server = server;
            this.database = database;
            this.schema = schema;
            this.object = object;
            this.part = part;
            this.pkg = pkg;
            this.wildcard = wildcard;
            this.resolution = resolution;
            this.sourceNamespace = sourceNamespace;
        }

        public long getHandle() {
            return handle;
        }

        /** The object type the parse gave the name ({@code EDbObjectType} name). */
        public String getObjectType() {
            return objectType;
        }

        public Anchor getAnchor() {
            return anchor;
        }

        /** The name as written: the text of its tokens. */
        public String getSpelling() {
            return spelling;
        }

        public Token getServer() {
            return server;
        }

        public Token getDatabase() {
            return database;
        }

        public Token getSchema() {
            return schema;
        }

        public Token getObject() {
            return object;
        }

        public Token getPart() {
            return part;
        }

        public Token getPackage() {
            return pkg;
        }

        /** Whether the name's column part is a wildcard, decided by the parse (its token type). */
        public boolean isWildcard() {
            return wildcard;
        }

        /** The resolver's status for the name ({@code ResolutionStatus} name), or null when it has none. */
        public String getResolution() {
            return resolution;
        }

        /** For an exact match, the simple class name of the namespace the column comes from, else null. */
        public String getSourceNamespace() {
            return sourceNamespace;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "h", Long.valueOf(handle));
            field(out, "t", objectType);
            field(out, "a", anchor);
            field(out, "s", spelling);
            field(out, "sv", server);
            field(out, "db", database);
            field(out, "sc", schema);
            field(out, "ob", object);
            field(out, "pt", part);
            field(out, "pk", pkg);
            field(out, "w", Boolean.valueOf(wildcard));
            field(out, "r", resolution);
            field(out, "ns", sourceNamespace);
        }
    }

    // ---------------------------------------------------------------------------------------------
    // Topology (copied at the freeze)
    // ---------------------------------------------------------------------------------------------

    /** A {@code Pair3<Long, Long, String>} position of the model. */
    public static final class Position implements Writable {
        private final Long line;
        private final Long column;
        private final String hash;

        Position(Long line, Long column, String hash) {
            this.line = line;
            this.column = column;
            this.hash = hash;
        }

        public Long getLine() {
            return line;
        }

        public Long getColumn() {
            return column;
        }

        public String getHash() {
            return hash;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "l", line);
            field(out, "c", column);
            field(out, "h", hash);
        }
    }

    /** A function or CASE the analysis built a result set for, described by its parse. */
    public static final class Call implements Writable {
        private final Anchor anchor;
        private final String vendor;
        private final Token nameToken;
        private final boolean qualified;
        private final boolean windowed;
        private final int arguments;
        private final boolean starArgument;
        private final List<Anchor> conditions;

        Call(Anchor anchor, String vendor, Token nameToken, boolean qualified, boolean windowed, int arguments,
                boolean starArgument, List<Anchor> conditions) {
            this.anchor = anchor;
            this.vendor = vendor;
            this.nameToken = nameToken;
            this.qualified = qualified;
            this.windowed = windowed;
            this.arguments = arguments;
            this.starArgument = starArgument;
            this.conditions = copy(conditions);
        }

        public Anchor getAnchor() {
            return anchor;
        }

        public String getVendor() {
            return vendor;
        }

        /** The token of the function's own name (its part token, else its object token), or null. */
        public Token getNameToken() {
            return nameToken;
        }

        /** Whether the function name is written with a qualifier (schema, database, server or package). */
        public boolean isQualified() {
            return qualified;
        }

        /** Whether the call has an OVER clause. */
        public boolean isWindowed() {
            return windowed;
        }

        /** The number of arguments, or -1 when the call has no argument list. */
        public int getArguments() {
            return arguments;
        }

        /** Whether the only argument is a wildcard ({@code COUNT(*)}), decided by its token type. */
        public boolean isStarArgument() {
            return starArgument;
        }

        /** For a CASE: the operand of a simple CASE, then each WHEN condition, in order. */
        public List<Anchor> getConditions() {
            return conditions;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "a", anchor);
            field(out, "v", vendor);
            field(out, "n", nameToken);
            field(out, "q", Boolean.valueOf(qualified));
            field(out, "w", Boolean.valueOf(windowed));
            field(out, "ar", Integer.valueOf(arguments));
            field(out, "st", Boolean.valueOf(starArgument));
            field(out, "cd", conditions);
        }
    }

    /**
     * A node of the runtime model: a table, view, variable, result set, function, column, relation-rows pseudo column,
     * process or routine, as it stood at the freeze.
     */
    public static final class Node implements Writable {
        private final long handle;
        private final String modelClass;
        private final long modelId;
        private final String kind;
        private final String setOperator;
        private final String name;
        private final String alias;
        private final String fullName;
        private final long owner;
        private final List<Long> members;
        private final List<String> flags;
        private final Anchor anchor;
        private final Anchor columnAnchor;
        private final Call call;
        private final long selectStatement;
        private final Anchor cte;
        private final Position start;
        private final Position end;
        private final boolean wildcard;

        Node(long handle, String modelClass, long modelId, String kind, String setOperator, String name, String alias,
                String fullName, long owner, List<Long> members, List<String> flags, Anchor anchor,
                Anchor columnAnchor, Call call, long selectStatement, Anchor cte, Position start, Position end,
                boolean wildcard) {
            this.handle = handle;
            this.modelClass = modelClass;
            this.modelId = modelId;
            this.kind = kind;
            this.setOperator = setOperator;
            this.name = name;
            this.alias = alias;
            this.fullName = fullName;
            this.owner = owner;
            this.members = copy(members);
            this.flags = copy(flags);
            this.anchor = anchor;
            this.columnAnchor = columnAnchor;
            this.call = call;
            this.selectStatement = selectStatement;
            this.cte = cte;
            this.start = start;
            this.end = end;
            this.wildcard = wildcard;
        }

        public long getHandle() {
            return handle;
        }

        /** The simple name of the model class ({@code Table}, {@code QueryTable}, {@code ResultColumn}, ...). */
        public String getModelClass() {
            return modelClass;
        }

        /** The model's own id, or -1 when the model has none. */
        public long getModelId() {
            return modelId;
        }

        /**
         * For a result set, its {@link ResultSetClassifier.Kind} name; for a table, its sub type
         * ({@code SubType} name) or null; else null.
         */
        public String getKind() {
            return kind;
        }

        /** For a set operation, its operator ({@code ESetOperatorType} name), else null. */
        public String getSetOperator() {
            return setOperator;
        }

        /** The model's name, as the model holds it (a display value, never an identity). */
        public String getName() {
            return name;
        }

        public String getAlias() {
            return alias;
        }

        public String getFullName() {
            return fullName;
        }

        /** For a column, the handle of the table or result set holding it; for relation rows, of their holder. */
        public long getOwner() {
            return owner;
        }

        /** For a table or result set, the handles of its columns at the freeze, in order. */
        public List<Long> getMembers() {
            return members;
        }

        /** Boolean properties that hold, by name ({@code constant}, {@code variable}, {@code star}, ...), sorted. */
        public List<String> getFlags() {
            return flags;
        }

        /** The parse tree node the model was built for ({@code getGspObject()}, the table object, ...), or null. */
        public Anchor getAnchor() {
            return anchor;
        }

        /** For a column, its column object, or null. */
        public Anchor getColumnAnchor() {
            return columnAnchor;
        }

        /** For a function result set, its function or CASE, else null. */
        public Call getCall() {
            return call;
        }

        /** For a select result set or set operation, the handle of its SELECT statement, else 0. */
        public long getSelectStatement() {
            return selectStatement;
        }

        /** For a query table over a CTE, the CTE's name, else null. */
        public Anchor getCte() {
            return cte;
        }

        /** For a table column, its start position, else null. */
        public Position getStart() {
            return start;
        }

        public Position getEnd() {
            return end;
        }

        /** For a result column, whether its column object is a wildcard, decided by the parse. */
        public boolean isWildcard() {
            return wildcard;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "h", Long.valueOf(handle));
            field(out, "c", modelClass);
            field(out, "id", Long.valueOf(modelId));
            field(out, "k", kind);
            field(out, "op", setOperator);
            field(out, "n", name);
            field(out, "al", alias);
            field(out, "fn", fullName);
            field(out, "ow", Long.valueOf(owner));
            field(out, "m", members);
            field(out, "f", flags);
            field(out, "a", anchor);
            field(out, "ca", columnAnchor);
            field(out, "call", call);
            field(out, "sel", Long.valueOf(selectStatement));
            field(out, "cte", cte);
            field(out, "s", start);
            field(out, "e", end);
            field(out, "w", Boolean.valueOf(wildcard));
        }
    }

    /** A transform the analysis attached to a relationship element. */
    public static final class TransformValue implements Writable {
        private final String type;
        private final Anchor code;

        TransformValue(String type, Anchor code) {
            this.type = type;
            this.code = code;
        }

        public String getType() {
            return type;
        }

        public Anchor getCode() {
            return code;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "t", type);
            field(out, "c", code);
        }
    }

    /** A relationship element: the node it stands for and how the relationship reads it. */
    public static final class Element implements Writable {
        private final long node;
        private final String elementClass;
        private final String clause;
        private final int starIndex;
        private final Integer columnIndex;
        private final String tableAlias;
        private final boolean positionUnproven;
        private final long columnName;
        private final Position referenceStart;
        private final Position referenceEnd;
        private final List<TransformValue> transforms;

        Element(long node, String elementClass, String clause, int starIndex, Integer columnIndex, String tableAlias,
                boolean positionUnproven, long columnName, Position referenceStart, Position referenceEnd,
                List<TransformValue> transforms) {
            this.node = node;
            this.elementClass = elementClass;
            this.clause = clause;
            this.starIndex = starIndex;
            this.columnIndex = columnIndex;
            this.tableAlias = tableAlias;
            this.positionUnproven = positionUnproven;
            this.columnName = columnName;
            this.referenceStart = referenceStart;
            this.referenceEnd = referenceEnd;
            this.transforms = copy(transforms);
        }

        /** The handle of the model node, or 0. */
        public long getNode() {
            return node;
        }

        /** The simple name of the element class. */
        public String getElementClass() {
            return elementClass;
        }

        /** Where the relationship reads the element ({@code ESqlClause} name), or null. */
        public String getClause() {
            return clause;
        }

        public int getStarIndex() {
            return starIndex;
        }

        public Integer getColumnIndex() {
            return columnIndex;
        }

        public String getTableAlias() {
            return tableAlias;
        }

        public boolean isPositionUnproven() {
            return positionUnproven;
        }

        /** The handle of the name the element carries ({@link Name}), or 0. */
        public long getColumnName() {
            return columnName;
        }

        public Position getReferenceStart() {
            return referenceStart;
        }

        public Position getReferenceEnd() {
            return referenceEnd;
        }

        /** The transforms; copied only at the freeze (an event carries none). */
        public List<TransformValue> getTransforms() {
            return transforms;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "n", Long.valueOf(node));
            field(out, "c", elementClass);
            field(out, "cl", clause);
            field(out, "si", Integer.valueOf(starIndex));
            field(out, "ci", columnIndex);
            field(out, "ta", tableAlias);
            field(out, "pu", Boolean.valueOf(positionUnproven));
            field(out, "cn", Long.valueOf(columnName));
            field(out, "rs", referenceStart);
            field(out, "re", referenceEnd);
            field(out, "t", transforms);
        }
    }

    /** One element of a frozen relationship (its target, or one de-duplicated source) with the events that gave it. */
    public static final class Contribution implements Writable {
        private final Element element;
        private final List<Long> events;

        Contribution(Element element, List<Long> events) {
            this.element = element;
            this.events = copy(events);
        }

        public Element getElement() {
            return element;
        }

        /**
         * The sequence numbers of the element events ({@link ElementEvent#getSequence()}) the contribution stands for:
         * a source read twice has two; a target set again has every setting; empty when no event gave the element.
         */
        public List<Long> getEvents() {
            return events;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "el", element);
            field(out, "ev", events);
        }
    }

    /** A relationship as it stood at the freeze. */
    public static final class Relation implements Writable {
        private final long handle;
        private final long modelId;
        private final String relationClass;
        private final String type;
        private final String effectType;
        private final String function;
        private final Contribution target;
        private final List<Contribution> sources;
        private final List<Long> supersededTargetEvents;

        Relation(long handle, long modelId, String relationClass, String type, String effectType, String function,
                Contribution target, List<Contribution> sources, List<Long> supersededTargetEvents) {
            this.supersededTargetEvents = copy(supersededTargetEvents);
            this.handle = handle;
            this.modelId = modelId;
            this.relationClass = relationClass;
            this.type = type;
            this.effectType = effectType;
            this.function = function;
            this.target = target;
            this.sources = copy(sources);
        }

        public long getHandle() {
            return handle;
        }

        public long getModelId() {
            return modelId;
        }

        /** The simple name of the relationship class ({@code DataFlowRelationship}, {@code ImpactRelationship}, ...). */
        public String getRelationClass() {
            return relationClass;
        }

        /** The relationship type ({@code RelationshipType} name), or null. */
        public String getType() {
            return type;
        }

        public String getEffectType() {
            return effectType;
        }

        public String getFunction() {
            return function;
        }

        /** The target, or null when the relationship has none. */
        public Contribution getTarget() {
            return target;
        }

        /** The de-duplicated sources, in the order the relationship holds them. */
        public List<Contribution> getSources() {
            return sources;
        }

        /**
         * The sequences of target events that set a target the relationship no longer has: a later setting replaced
         * it. Their own element is in the event ({@link ElementEvent#getElement()}).
         */
        public List<Long> getSupersededTargetEvents() {
            return supersededTargetEvents;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "h", Long.valueOf(handle));
            field(out, "id", Long.valueOf(modelId));
            field(out, "c", relationClass);
            field(out, "t", type);
            field(out, "ef", effectType);
            field(out, "fn", function);
            field(out, "tg", target);
            field(out, "s", sources);
            field(out, "sup", supersededTargetEvents);
        }
    }

    // ---------------------------------------------------------------------------------------------
    // Events
    // ---------------------------------------------------------------------------------------------

    /** An element added as a source of a relationship, or set as its target, copied when it happened. */
    public static final class ElementEvent implements Writable {
        private final long sequence;
        private final long relation;
        private final boolean target;
        private final Element element;
        private final long reference;
        private final Resolution resolution;
        private final long statement;
        private final long topStatement;

        ElementEvent(long sequence, long relation, boolean target, Element element, long reference,
                Resolution resolution, long statement, long topStatement) {
            this.sequence = sequence;
            this.relation = relation;
            this.target = target;
            this.element = element;
            this.reference = reference;
            this.resolution = resolution;
            this.statement = statement;
            this.topStatement = topStatement;
        }

        /** How the reference stood when the event happened (it can change later), or null without a reference. */
        public Resolution getResolution() {
            return resolution;
        }

        /** The recording order, shared with {@link ReferenceEvent}. */
        public long getSequence() {
            return sequence;
        }

        /** The handle of the relationship. */
        public long getRelation() {
            return relation;
        }

        public boolean isTarget() {
            return target;
        }

        /** The element as it was when the event happened; it carries no transforms. */
        public Element getElement() {
            return element;
        }

        /** The handle of the name reference the analysis was processing ({@link Name}), or 0. */
        public long getReference() {
            return reference;
        }

        /** The handle of the innermost statement being analysed, or 0. */
        public long getStatement() {
            return statement;
        }

        /** The handle of its top-level statement, or 0. */
        public long getTopStatement() {
            return topStatement;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "q", Long.valueOf(sequence));
            field(out, "r", Long.valueOf(relation));
            field(out, "t", Boolean.valueOf(target));
            field(out, "el", element);
            field(out, "rf", Long.valueOf(reference));
            field(out, "res", resolution);
            field(out, "s", Long.valueOf(statement));
            field(out, "ts", Long.valueOf(topStatement));
        }
    }

    /** A name reference the analysis read for a target, whether or not it added a source. */
    public static final class ReferenceEvent implements Writable {
        private final long sequence;
        private final long reference;
        private final Resolution resolution;
        private final long target;
        private final long statement;
        private final long topStatement;

        ReferenceEvent(long sequence, long reference, Resolution resolution, long target, long statement,
                long topStatement) {
            this.sequence = sequence;
            this.reference = reference;
            this.resolution = resolution;
            this.target = target;
            this.statement = statement;
            this.topStatement = topStatement;
        }

        /** How the reference stood when it was read. */
        public Resolution getResolution() {
            return resolution;
        }

        public long getSequence() {
            return sequence;
        }

        /** The handle of the name ({@link Name}). */
        public long getReference() {
            return reference;
        }

        /** The handle of the model node the reference was read for, or 0. */
        public long getTarget() {
            return target;
        }

        public long getStatement() {
            return statement;
        }

        public long getTopStatement() {
            return topStatement;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "q", Long.valueOf(sequence));
            field(out, "rf", Long.valueOf(reference));
            field(out, "res", resolution);
            field(out, "tg", Long.valueOf(target));
            field(out, "s", Long.valueOf(statement));
            field(out, "ts", Long.valueOf(topStatement));
        }
    }

    /** A statement of dynamic SQL text, with the statement whose analysis parsed it. */
    public static final class Derived implements Writable {
        private final long statement;
        private final long site;

        Derived(long statement, long site) {
            this.statement = statement;
            this.site = site;
        }

        public long getStatement() {
            return statement;
        }

        public long getSite() {
            return site;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", Long.valueOf(statement));
            field(out, "site", Long.valueOf(site));
        }
    }

    /** A column built for a field of a STRUCT that a select item constructs. */
    public static final class StructField implements Writable {
        private final long column;
        private final Anchor item;

        StructField(long column, Anchor item) {
            this.column = column;
            this.item = item;
        }

        public long getColumn() {
            return column;
        }

        public Anchor getItem() {
            return item;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "c", Long.valueOf(column));
            field(out, "i", item);
        }
    }


    // ---------------------------------------------------------------------------------------------
    // Resolution evidence and decisions (events)
    // ---------------------------------------------------------------------------------------------

    /** One alternative the resolver gave a name: where its column comes from, unflattened. */
    public static final class Alternative implements Writable {
        private final String namespaceClass;
        private final Anchor range;
        private final String exposedName;
        private final Anchor definition;
        private final Anchor override;
        private final String confidence;
        private final String evidenceType;
        private final String evidence;

        Alternative(String namespaceClass, Anchor range, String exposedName, Anchor definition, Anchor override,
                String confidence, String evidenceType, String evidence) {
            this.namespaceClass = namespaceClass;
            this.range = range;
            this.exposedName = exposedName;
            this.definition = definition;
            this.override = override;
            this.confidence = confidence;
            this.evidenceType = evidenceType;
            this.evidence = evidence;
        }

        /** The simple class name of the namespace the column comes from ({@code TableNamespace}, ...). */
        public String getNamespaceClass() {
            return namespaceClass;
        }

        /**
         * The range variable as written: the table of a table namespace, the FROM item that reads a CTE (else the
         * CTE's query), the query of a derived table; null for another namespace.
         */
        public Anchor getRange() {
            return range;
        }

        /** The column name the namespace exposes. */
        public String getExposedName() {
            return exposedName;
        }

        /** Where the column is defined (a select item, a column definition), or null. */
        public Anchor getDefinition() {
            return definition;
        }

        /** The table the resolver set over the namespace's own, or null. */
        public Anchor getOverride() {
            return override;
        }

        /** The resolver's confidence, as written by {@code String.valueOf(double)}. */
        public String getConfidence() {
            return confidence;
        }

        /** The evidence type ({@code EvidenceType} name), or null. */
        public String getEvidenceType() {
            return evidenceType;
        }

        public String getEvidence() {
            return evidence;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "ns", namespaceClass);
            field(out, "r", range);
            field(out, "x", exposedName);
            field(out, "d", definition);
            field(out, "o", override);
            field(out, "c", confidence);
            field(out, "et", evidenceType);
            field(out, "e", evidence);
        }
    }

    /** A name's resolution as it stood at one moment: status, every alternative and the table linked to it. */
    public static final class Resolution implements Writable {
        private final String status;
        private final List<Alternative> alternatives;
        private final Anchor sourceTable;

        Resolution(String status, List<Alternative> alternatives, Anchor sourceTable) {
            this.status = status;
            this.alternatives = copy(alternatives);
            this.sourceTable = sourceTable;
        }

        /** The resolver's status ({@code ResolutionStatus} name), or null when the resolver left no result. */
        public String getStatus() {
            return status;
        }

        /** The exact match's source, or every candidate of an ambiguous name, in the resolver's order. */
        public List<Alternative> getAlternatives() {
            return alternatives;
        }

        /** The table the name was linked to ({@code TObjectName.getSourceTable()}), or null. */
        public Anchor getSourceTable() {
            return sourceTable;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", status);
            field(out, "a", alternatives);
            field(out, "t", sourceTable);
        }
    }

    /**
     * A binding the analysis decided by a fallback (plan 06, Section 3.3, decision points), recorded before it acts on
     * it: the reference as it stood, what was selected and why.
     */
    public static final class Decision implements Writable {
        private final long sequence;
        private final String id;
        private final long reference;
        private final Resolution resolution;
        private final Anchor selected;
        private final long selectedNode;
        private final String reason;
        private final long statement;

        Decision(long sequence, String id, long reference, Resolution resolution, Anchor selected, long selectedNode,
                String reason, long statement) {
            this.sequence = sequence;
            this.id = id;
            this.reference = reference;
            this.resolution = resolution;
            this.selected = selected;
            this.selectedNode = selectedNode;
            this.reason = reason;
            this.statement = statement;
        }

        /** The recording order, shared with the element and reference events. */
        public long getSequence() {
            return sequence;
        }

        /** The decision point ({@code SqllrObservations.DECISION_*}). */
        public String getId() {
            return id;
        }

        /** The handle of the name decided for ({@link Name}), or 0. */
        public long getReference() {
            return reference;
        }

        /** The name's resolution just before the decision. */
        public Resolution getResolution() {
            return resolution;
        }

        /** The parse tree node selected (a FROM item), or null. */
        public Anchor getSelected() {
            return selected;
        }

        /** The model node selected, or 0. */
        public long getSelectedNode() {
            return selectedNode;
        }

        public String getReason() {
            return reason;
        }

        public long getStatement() {
            return statement;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "q", Long.valueOf(sequence));
            field(out, "id", id);
            field(out, "rf", Long.valueOf(reference));
            field(out, "res", resolution);
            field(out, "sel", selected);
            field(out, "sn", Long.valueOf(selectedNode));
            field(out, "why", reason);
            field(out, "s", Long.valueOf(statement));
        }
    }

    /** The members of one model registry, in the registry's order (processes, packages, routines, tables, ...). */
    public static final class RegistryEntry implements Writable {
        private final String category;
        private final List<Long> nodes;

        RegistryEntry(String category, List<Long> nodes) {
            this.category = category;
            this.nodes = copy(nodes);
        }

        public String getCategory() {
            return category;
        }

        public List<Long> getNodes() {
            return nodes;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "c", category);
            field(out, "n", nodes);
        }
    }

    // ---------------------------------------------------------------------------------------------
    // What has no relationship: declarations, layouts, written rows (copied from the parse at the freeze)
    // ---------------------------------------------------------------------------------------------

    /** A declared parameter or variable, used or not. */
    public static final class Declaration implements Writable {
        private final long statement;
        private final String kind;
        private final Anchor name;
        private final String mode;
        private final Anchor dataType;
        private final Anchor defaultValue;
        private final Anchor declaration;

        Declaration(long statement, String kind, Anchor name, String mode, Anchor dataType, Anchor defaultValue,
                Anchor declaration) {
            this.statement = statement;
            this.kind = kind;
            this.name = name;
            this.mode = mode;
            this.dataType = dataType;
            this.defaultValue = defaultValue;
            this.declaration = declaration;
        }

        /** The handle of the statement whose parse holds the declaration. */
        public long getStatement() {
            return statement;
        }

        /** {@code PARAMETER} or {@code VARIABLE}. */
        public String getKind() {
            return kind;
        }

        public Anchor getName() {
            return name;
        }

        /** A parameter's mode ({@code EParameterMode} name), else null. */
        public String getMode() {
            return mode;
        }

        public Anchor getDataType() {
            return dataType;
        }

        /** The default or initial value, or null. */
        public Anchor getDefaultValue() {
            return defaultValue;
        }

        /** The whole declaration. */
        public Anchor getDeclaration() {
            return declaration;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", Long.valueOf(statement));
            field(out, "k", kind);
            field(out, "n", name);
            field(out, "m", mode);
            field(out, "t", dataType);
            field(out, "d", defaultValue);
            field(out, "a", declaration);
        }
    }

    /** The output layout of one query block: its items, also when there are none. */
    public static final class Layout implements Writable {
        private final long statement;
        private final Anchor select;
        private final String setOperator;
        private final int columns;
        private final List<String> kinds;
        private final List<Anchor> items;
        private final boolean into;

        Layout(long statement, Anchor select, String setOperator, int columns, List<String> kinds, List<Anchor> items,
                boolean into) {
            this.statement = statement;
            this.select = select;
            this.setOperator = setOperator;
            this.columns = columns;
            this.kinds = copy(kinds);
            this.items = copy(items);
            this.into = into;
        }

        /** The handle of the statement whose parse holds the query. */
        public long getStatement() {
            return statement;
        }

        public Anchor getSelect() {
            return select;
        }

        /** For a set operation, its operator ({@code ESetOperatorType} name); its operands have their own layouts. */
        public String getSetOperator() {
            return setOperator;
        }

        /** The number of select items: 0 for {@code SELECT FROM t} (complete and empty), -1 for a set operation. */
        public int getColumns() {
            return columns;
        }

        /** Per item: {@code WILDCARD} (decided by the parse) or the expression type ({@code EExpressionType}). */
        public List<String> getKinds() {
            return kinds;
        }

        public List<Anchor> getItems() {
            return items;
        }

        /** Whether the query has an INTO clause. */
        public boolean isInto() {
            return into;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", Long.valueOf(statement));
            field(out, "q", select);
            field(out, "op", setOperator);
            field(out, "n", Integer.valueOf(columns));
            field(out, "k", kinds);
            field(out, "i", items);
            field(out, "into", Boolean.valueOf(into));
        }
    }

    /** One row an INSERT writes from a VALUES list (or DEFAULT VALUES), item by item. */
    public static final class WriteRow implements Writable {
        private final long statement;
        private final Anchor target;
        private final String insertSource;
        private final int targetColumns;
        private final int row;
        private final List<String> kinds;
        private final List<Anchor> items;

        WriteRow(long statement, Anchor target, String insertSource, int targetColumns, int row, List<String> kinds,
                List<Anchor> items) {
            this.statement = statement;
            this.target = target;
            this.insertSource = insertSource;
            this.targetColumns = targetColumns;
            this.row = row;
            this.kinds = copy(kinds);
            this.items = copy(items);
        }

        public long getStatement() {
            return statement;
        }

        /** The target table as written. */
        public Anchor getTarget() {
            return target;
        }

        /** The kind of source ({@code EInsertSource} name). */
        public String getInsertSource() {
            return insertSource;
        }

        /** The number of target columns listed, or -1 when the statement lists none. */
        public int getTargetColumns() {
            return targetColumns;
        }

        /** The row's position in the VALUES list, from 0; -1 for DEFAULT VALUES. */
        public int getRow() {
            return row;
        }

        /** Per item: {@code DEFAULT} (the keyword) or the expression type ({@code EExpressionType}). */
        public List<String> getKinds() {
            return kinds;
        }

        public List<Anchor> getItems() {
            return items;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", Long.valueOf(statement));
            field(out, "t", target);
            field(out, "src", insertSource);
            field(out, "tc", Integer.valueOf(targetColumns));
            field(out, "r", Integer.valueOf(row));
            field(out, "k", kinds);
            field(out, "i", items);
        }
    }

    /**
     * A column reference of the parse, whether the analysis read it or not (a failed read leaves no event): its name
     * and its resolution at the freeze.
     */
    public static final class ColumnReference implements Writable {
        private final long statement;
        private final long name;
        private final Resolution resolution;

        ColumnReference(long statement, long name, Resolution resolution) {
            this.statement = statement;
            this.name = name;
            this.resolution = resolution;
        }

        public long getStatement() {
            return statement;
        }

        /** The handle of the name ({@link Name}). */
        public long getName() {
            return name;
        }

        public Resolution getResolution() {
            return resolution;
        }

        @Override
        public void write(StringBuilder out) {
            field(out, "s", Long.valueOf(statement));
            field(out, "n", Long.valueOf(name));
            field(out, "res", resolution);
        }
    }

    // ---------------------------------------------------------------------------------------------

    private final List<Text> texts;
    private final List<Unit> units;
    private final List<Statement> statements;
    private final List<Name> names;
    private final List<Node> nodes;
    private final List<Relation> relations;
    private final List<ElementEvent> elementEvents;
    private final List<ReferenceEvent> referenceEvents;
    private final List<Derived> derived;
    private final List<StructField> structFields;
    private final List<Decision> decisions;
    private final List<RegistryEntry> registry;
    private final List<Declaration> declarations;
    private final List<Layout> layouts;
    private final List<WriteRow> writeRows;
    private final List<ColumnReference> columnReferences;
    private final String projectionFailure;

    SqllrSnapshot(List<Text> texts, List<Unit> units, List<Statement> statements, List<Name> names, List<Node> nodes,
            List<Relation> relations, List<ElementEvent> elementEvents, List<ReferenceEvent> referenceEvents,
            List<Derived> derived, List<StructField> structFields, List<Decision> decisions,
            List<RegistryEntry> registry, List<Declaration> declarations, List<Layout> layouts,
            List<WriteRow> writeRows, List<ColumnReference> columnReferences, String projectionFailure) {
        this.columnReferences = copy(columnReferences);
        this.decisions = copy(decisions);
        this.registry = copy(registry);
        this.declarations = copy(declarations);
        this.layouts = copy(layouts);
        this.writeRows = copy(writeRows);
        this.projectionFailure = projectionFailure;
        this.texts = copy(texts);
        this.units = copy(units);
        this.statements = copy(statements);
        this.names = copy(names);
        this.nodes = copy(nodes);
        this.relations = copy(relations);
        this.elementEvents = copy(elementEvents);
        this.referenceEvents = copy(referenceEvents);
        this.derived = copy(derived);
        this.structFields = copy(structFields);
    }

    /** Every parse text a copied token belongs to, by handle. */
    public List<Text> getTexts() {
        return texts;
    }

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

    /** Every statement the analysis worked in, in handle order. */
    public List<Statement> getStatements() {
        return statements;
    }

    /** Every name reference an event carries, in handle order. */
    public List<Name> getNames() {
        return names;
    }

    /**
     * Every model node: those the model registers for output (processes, routines, tables, views, result sets), then
     * any other node an element or member reaches, in handle order.
     */
    public List<Node> getNodes() {
        return nodes;
    }

    /** Every relationship at the freeze, in creation order. */
    public List<Relation> getRelations() {
        return relations;
    }

    /** Every element event, in recording order. */
    public List<ElementEvent> getElementEvents() {
        return elementEvents;
    }

    /** Every reference event, in recording order. */
    public List<ReferenceEvent> getReferenceEvents() {
        return referenceEvents;
    }

    public List<Derived> getDerived() {
        return derived;
    }

    public List<StructField> getStructFields() {
        return structFields;
    }

    /** Every fallback decision, in recording order. */
    public List<Decision> getDecisions() {
        return decisions;
    }

    /** The model's registries, each in its own order; a node may also be reached only through a relationship. */
    public List<RegistryEntry> getRegistry() {
        return registry;
    }

    /** Every declared parameter and variable of the analysed statements, used or not, in text order. */
    public List<Declaration> getDeclarations() {
        return declarations;
    }

    /** The output layout of every query block of the analysed statements, in text order. */
    public List<Layout> getLayouts() {
        return layouts;
    }

    /** Every row an INSERT of the analysed statements writes from VALUES (or DEFAULT VALUES), in text order. */
    public List<WriteRow> getWriteRows() {
        return writeRows;
    }

    /** Every column reference of the analysed statements' parse, read or not, in text order. */
    public List<ColumnReference> getColumnReferences() {
        return columnReferences;
    }

    /**
     * Why copying the declarations, layouts, written rows and column references from the parse stopped (they are then
     * incomplete), or null.
     */
    public String getProjectionFailure() {
        return projectionFailure;
    }

    /** The snapshot written canonically: equal snapshots, and only equal ones, write the same text. */
    public String canonical() {
        StringBuilder out = new StringBuilder();
        field(out, "texts", texts);
        field(out, "units", units);
        field(out, "statements", statements);
        field(out, "names", names);
        field(out, "nodes", nodes);
        field(out, "relations", relations);
        field(out, "elementEvents", elementEvents);
        field(out, "referenceEvents", referenceEvents);
        field(out, "derived", derived);
        field(out, "structFields", structFields);
        field(out, "decisions", decisions);
        field(out, "registry", registry);
        field(out, "declarations", declarations);
        field(out, "layouts", layouts);
        field(out, "writeRows", writeRows);
        field(out, "columnReferences", columnReferences);
        field(out, "projectionFailure", projectionFailure);
        return out.toString();
    }

    /** The SHA-256 of {@link #canonical()}, in lower-case hex. */
    public String digest() {
        try {
            byte[] d = MessageDigest.getInstance("SHA-256").digest(canonical().getBytes(StandardCharsets.UTF_8));
            StringBuilder hex = new StringBuilder();
            for (byte b : d) {
                hex.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
            }
            return hex.toString();
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException(e);
        }
    }
}