@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/dist/hcl/jsonencode.js

@@ -0,0 +1,442 @@
+/**
+ * Read the argument of a `jsonencode(...)` call as structure, when it is
+ * literal (chant #2286, shared with #2287).
+ *
+ * hcl2json does not evaluate expressions. `policy = jsonencode({...})` and
+ * `container_definitions = jsonencode([...])` both reach a block body as ONE
+ * string holding the expression's source text, wrapped as an interpolation:
+ *
+ * ```
+ * "${jsonencode({\n    Version = \"2012-10-17\"\n    Statement = [{ Action = \"*\" }]\n  })}"
+ * ```
+ *
+ * The text inside is HCL object syntax, not JSON (`=` or `:` separators, bare
+ * keys, newline-separated items, `#` comments). A rule that wants the policy
+ * or the container definitions has to read that text itself. This file does
+ * so, narrowly: it accepts literal objects, tuples, quoted strings, numbers,
+ * `true`, `false` and `null`, and nothing else. Any expression in the
+ * argument (a reference, a function call, a for-expression, a splat, a
+ * conditional, an operator, a template interpolation inside a string, a
+ * heredoc, a parenthesised key) makes the whole read `not-determined`, with a
+ * reason naming what was found. It never evaluates anything, so it can never
+ * return a value Terraform would not also produce from the same text.
+ *
+ * Three answers:
+ * - `literal`: the value is a single whole-string `${jsonencode(...)}` and
+ *   its argument is fully literal. `value` is the plain JS value
+ *   `jsonencode` would encode.
+ * - `not-determined`: the value is a `${jsonencode(...)}` call, but the
+ *   argument holds something this reader does not evaluate.
+ * - `not-jsonencode`: the value is not a `${jsonencode(...)}` call at all
+ *   (a plain string, a reference, `file(...)`, a number, absent). Callers
+ *   decide what that means for their attribute; a plain string, for example,
+ *   may itself be JSON from a heredoc.
+ *
+ * The whole-string test is shape-based: the string starts `${jsonencode(` and
+ * ends `)}`. A string that matches that shape but is really a template with
+ * two interpolations (`${jsonencode(a)}-${jsonencode(b)}`) fails the literal
+ * parse at the point where the first call closes early, and reads as
+ * `not-determined`, never as `literal`.
+ */
+/** Marks a value position `readJsonencode(raw, { unknownLeaves: true })` could not read. */
+export const UNKNOWN = Symbol("jsonencode.unknown");
+/**
+ * Marks an object, read with `unknownLeaves`, that had members whose KEY is an
+ * expression (`"router-${var.n}.rule" = ...`, `(var.k) = ...`). Those members
+ * are dropped from the object and their reasons listed here, so a reader can
+ * tell "this key is absent" from "some key here could not be read".
+ */
+export const UNKNOWN_KEYS = Symbol("jsonencode.unknownKeys");
+/** Whether `obj` is an object that dropped one or more members with an expression key. */
+export function hasUnknownKeys(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        Array.isArray(obj[UNKNOWN_KEYS]) &&
+        obj[UNKNOWN_KEYS].length > 0);
+}
+/** Whether `v` is a value position the reader skipped. */
+export function isUnknown(v) {
+    return typeof v === "object" && v !== null && v[UNKNOWN] === true;
+}
+const PREFIX = /^\$\{\s*jsonencode\s*\(/;
+const SUFFIX = /\)\s*\}$/;
+/** Read `raw` (an hcl2json attribute value) as a `jsonencode(...)` call. */
+export function readJsonencode(raw, options = {}) {
+    if (typeof raw !== "string")
+        return { kind: "not-jsonencode" };
+    const prefix = PREFIX.exec(raw);
+    if (!prefix || !SUFFIX.test(raw))
+        return { kind: "not-jsonencode" };
+    const reader = new Reader(raw, prefix[0].length, options.unknownLeaves === true);
+    try {
+        const value = reader.value(0);
+        reader.skipSpace();
+        // The argument must end at the call's own `)`, then the interpolation's `}`.
+        reader.expect(")", "a second argument or an expression after the literal");
+        reader.skipSpace();
+        reader.expect("}", "text after the jsonencode call");
+        if (!reader.atEnd())
+            throw new NotLiteral("text after the jsonencode call");
+        return { kind: "literal", value };
+    }
+    catch (err) {
+        if (err instanceof NotLiteral)
+            return { kind: "not-determined", reason: err.message };
+        throw err;
+    }
+}
+class NotLiteral extends Error {
+}
+/** Damage to the shape itself: never recovered by skipping a leaf. */
+class Structural extends NotLiteral {
+}
+/** An object key that is an expression; recoverable by dropping the member under `unknownLeaves`. */
+class KeyNotLiteral extends Structural {
+}
+const IDENT = /[A-Za-z_][A-Za-z0-9_-]*/y;
+const NUMBER = /-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+/** A cursor over the source text of the jsonencode argument. */
+class Reader {
+    constructor(src, pos, unknownLeaves = false) {
+        this.src = src;
+        this.pos = pos;
+        this.unknownLeaves = unknownLeaves;
+    }
+    atEnd() {
+        return this.pos >= this.src.length;
+    }
+    peek() {
+        return this.src[this.pos] ?? "";
+    }
+    expect(ch, what) {
+        if (this.peek() !== ch)
+            throw new NotLiteral(what === "" ? `expected "${ch}"` : what);
+        this.pos++;
+    }
+    /** Whitespace, newlines and the three HCL comment forms. */
+    skipSpace(newlines = true) {
+        for (;;) {
+            const c = this.peek();
+            if (c === " " || c === "\t" || c === "\r" || (newlines && c === "\n")) {
+                this.pos++;
+            }
+            else if (c === "#" || (c === "/" && this.src[this.pos + 1] === "/")) {
+                const end = this.src.indexOf("\n", this.pos);
+                this.pos = end === -1 ? this.src.length : end;
+            }
+            else if (c === "/" && this.src[this.pos + 1] === "*") {
+                const end = this.src.indexOf("*/", this.pos + 2);
+                if (end === -1)
+                    throw new NotLiteral("an unterminated comment");
+                this.pos = end + 2;
+            }
+            else {
+                return;
+            }
+        }
+    }
+    /** One value. `depth` is 0 for the whole argument, which is never skipped. */
+    value(depth) {
+        this.skipSpace();
+        if (!this.unknownLeaves || depth === 0)
+            return this.literal(depth);
+        const start = this.pos;
+        try {
+            return this.literal(depth);
+        }
+        catch (err) {
+            if (!(err instanceof NotLiteral) || err instanceof Structural)
+                throw err;
+            this.pos = start;
+            this.skipExpression();
+            return { [UNKNOWN]: true, reason: err.message, source: this.src.slice(start, this.pos).trim() };
+        }
+    }
+    literal(depth) {
+        const c = this.peek();
+        let v;
+        if (c === "{")
+            v = this.object(depth + 1);
+        else if (c === "[")
+            v = this.tuple(depth + 1);
+        else if (c === '"')
+            v = this.string();
+        else if (c === "<" && this.src.startsWith("<<", this.pos))
+            throw new NotLiteral("a heredoc");
+        else if (c === "(")
+            throw new NotLiteral("a parenthesised expression");
+        else if (c === "-" || (c >= "0" && c <= "9"))
+            v = this.number();
+        else
+            v = this.keyword();
+        this.afterValue();
+        return v;
+    }
+    /**
+     * A literal is complete only if what follows it closes or separates. An
+     * operator, a conditional, an attribute access or an index after it makes
+     * the whole thing an expression.
+     */
+    afterValue() {
+        this.skipSpace(false);
+        const c = this.peek();
+        if (c === "" || c === "\n" || c === "," || c === "}" || c === "]" || c === ")")
+            return;
+        const next = this.src[this.pos + 1];
+        if (c === "#" || (c === "/" && (next === "/" || next === "*")))
+            return; // a comment, consumed by the caller's skipSpace
+        if (c === "?")
+            throw new NotLiteral("a conditional expression");
+        if (c === "." || c === "[")
+            throw new NotLiteral("an attribute access, index or splat");
+        throw new NotLiteral(`an operator or expression ("${c}")`);
+    }
+    object(depth) {
+        this.expect("{", "");
+        const out = {};
+        for (;;) {
+            this.skipSpace();
+            if (this.peek() === "}") {
+                this.pos++;
+                return out;
+            }
+            const quoted = this.peek() === '"';
+            const memberStart = this.pos;
+            let key;
+            try {
+                key = this.key();
+            }
+            catch (err) {
+                if (!(err instanceof KeyNotLiteral) || !this.unknownLeaves)
+                    throw err;
+                // Drop the whole member: the skip runs from the key through its value
+                // to the separator, balancing brackets and quotes on the way.
+                this.pos = memberStart;
+                this.skipExpression();
+                const bag = out;
+                (bag[UNKNOWN_KEYS] ?? (bag[UNKNOWN_KEYS] = [])).push(err.message);
+                this.skipSpace(false);
+                if (this.peek() === ",")
+                    this.pos++;
+                continue;
+            }
+            this.skipSpace(false);
+            const sep = this.peek();
+            if (sep !== "=" && sep !== ":") {
+                // A for-expression is a VALUE: under unknownLeaves the enclosing
+                // value() skips it as a leaf; as the whole argument it is not determined.
+                if (!quoted && key === "for")
+                    throw new NotLiteral("a for-expression");
+                throw new Structural(`an expression where "${key}" needs = or :`);
+            }
+            this.pos++;
+            out[key] = this.value(depth);
+            this.skipSpace(false);
+            if (this.peek() === ",")
+                this.pos++;
+        }
+    }
+    key() {
+        const c = this.peek();
+        if (c === '"') {
+            try {
+                return this.string();
+            }
+            catch (err) {
+                if (err instanceof NotLiteral)
+                    throw new KeyNotLiteral(`an object key holding ${err.message.replace(/^a string with /, "")}`);
+                throw err;
+            }
+        }
+        if (c === "(")
+            throw new KeyNotLiteral("a computed object key");
+        IDENT.lastIndex = this.pos;
+        const m = IDENT.exec(this.src);
+        if (!m)
+            throw new Structural(`an unexpected "${c}" where an object key belongs`);
+        this.pos += m[0].length;
+        return m[0];
+    }
+    tuple(depth) {
+        this.expect("[", "");
+        this.skipSpace();
+        if (/^for\s/.test(this.src.slice(this.pos, this.pos + 4)))
+            throw new NotLiteral("a for-expression");
+        const out = [];
+        for (;;) {
+            this.skipSpace();
+            if (this.peek() === "]") {
+                this.pos++;
+                return out;
+            }
+            out.push(this.value(depth));
+            this.skipSpace();
+            if (this.peek() === ",")
+                this.pos++;
+            else if (this.peek() !== "]")
+                throw new NotLiteral("a tuple item followed by an expression");
+        }
+    }
+    /** A quoted HCL string. A `${` or `%{` (not escaped as `$${`/`%%{`) is a template. */
+    string() {
+        this.expect('"', "");
+        let out = "";
+        for (;;) {
+            const c = this.peek();
+            if (c === "")
+                throw new NotLiteral("an unterminated string");
+            if (c === "\n")
+                throw new NotLiteral("a newline inside a quoted string");
+            if (c === '"') {
+                this.pos++;
+                return out;
+            }
+            if ((c === "$" || c === "%") && this.src[this.pos + 1] === c && this.src[this.pos + 2] === "{") {
+                out += `${c}{`;
+                this.pos += 3;
+                continue;
+            }
+            if ((c === "$" || c === "%") && this.src[this.pos + 1] === "{") {
+                throw new NotLiteral(c === "$" ? "a string with a ${...} interpolation" : "a string with a %{...} directive");
+            }
+            if (c === "\\") {
+                out += this.escape();
+                continue;
+            }
+            out += c;
+            this.pos++;
+        }
+    }
+    escape() {
+        const e = this.src[this.pos + 1] ?? "";
+        this.pos += 2;
+        switch (e) {
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            case '"':
+                return '"';
+            case "\\":
+                return "\\";
+            case "u":
+            case "U": {
+                const len = e === "u" ? 4 : 8;
+                const hex = this.src.slice(this.pos, this.pos + len);
+                if (!/^[0-9A-Fa-f]+$/.test(hex) || hex.length !== len)
+                    throw new NotLiteral("a malformed unicode escape");
+                this.pos += len;
+                return String.fromCodePoint(parseInt(hex, 16));
+            }
+            default:
+                throw new NotLiteral(`an unknown string escape "\\${e}"`);
+        }
+    }
+    number() {
+        NUMBER.lastIndex = this.pos;
+        const m = NUMBER.exec(this.src);
+        if (!m)
+            throw new NotLiteral("a unary operator on an expression");
+        this.pos += m[0].length;
+        return Number(m[0]);
+    }
+    keyword() {
+        IDENT.lastIndex = this.pos;
+        const m = IDENT.exec(this.src);
+        if (!m)
+            throw new NotLiteral(`an unexpected "${this.peek()}"`);
+        const word = m[0];
+        this.pos += word.length;
+        if (word === "true")
+            return true;
+        if (word === "false")
+            return false;
+        if (word === "null")
+            return null;
+        this.skipSpace(false);
+        if (this.peek() === "(")
+            throw new NotLiteral(`a function call (${word}(...))`);
+        if (word === "for")
+            throw new NotLiteral("a for-expression");
+        return this.reference(word);
+    }
+    /**
+     * Skip one value expression from the cursor: balance `()[]{}` and quoted
+     * strings (with their `${...}` interpolations), stop at a `,`, a newline, a
+     * comment or a closing bracket at depth 0. A heredoc is skipped to its
+     * closing marker line.
+     */
+    skipExpression() {
+        let depth = 0;
+        while (!this.atEnd()) {
+            const c = this.peek();
+            if (depth === 0) {
+                if (c === "," || c === "\n" || c === "}" || c === "]" || c === ")" || c === "#")
+                    return;
+                if (c === "/" && (this.src[this.pos + 1] === "/" || this.src[this.pos + 1] === "*"))
+                    return;
+            }
+            if (c === '"')
+                this.skipQuoted();
+            else if (c === "<" && this.src.startsWith("<<", this.pos))
+                this.skipHeredoc();
+            else {
+                if (c === "(" || c === "[" || c === "{")
+                    depth++;
+                else if (c === ")" || c === "]" || c === "}")
+                    depth--;
+                this.pos++;
+            }
+        }
+    }
+    /** Skip a quoted string, including any `${...}` interpolations (which may hold strings). */
+    skipQuoted() {
+        this.pos++;
+        while (!this.atEnd()) {
+            const c = this.peek();
+            if (c === "\\")
+                this.pos += 2;
+            else if (c === '"') {
+                this.pos++;
+                return;
+            }
+            else if ((c === "$" || c === "%") && this.src[this.pos + 1] === "{") {
+                this.pos += 2;
+                let depth = 1;
+                while (!this.atEnd() && depth > 0) {
+                    const d = this.peek();
+                    if (d === '"') {
+                        this.skipQuoted();
+                        continue;
+                    }
+                    if (d === "{")
+                        depth++;
+                    else if (d === "}")
+                        depth--;
+                    this.pos++;
+                }
+            }
+            else
+                this.pos++;
+        }
+        throw new Structural("an unterminated string");
+    }
+    skipHeredoc() {
+        const head = /<<-?([A-Za-z_][A-Za-z0-9_-]*)[ \t]*\n/y;
+        head.lastIndex = this.pos;
+        const m = head.exec(this.src);
+        if (!m)
+            throw new Structural("a malformed heredoc");
+        const close = new RegExp(`^[ \\t]*${m[1]}[ \\t]*$`, "m");
+        const rest = this.src.slice(this.pos + m[0].length);
+        const end = close.exec(rest);
+        if (!end)
+            throw new Structural("an unterminated heredoc");
+        this.pos += m[0].length + end.index + end[0].length;
+    }
+    reference(word) {
+        throw new NotLiteral(`a reference (${word}${this.peek() === "." ? "..." : ""})`);
+    }
+}

package/dist/hcl/marker.js

@@ -0,0 +1,212 @@
+/**
+ * choudoufu's live resource markers, as chant reads them (#2104).
+ *
+ * On a live root the ownership record is not a state file and not a chant
+ * stamp: it is two AWS tags on the resource itself, `tofu-estate` and
+ * `tofu-address`, specified in `live/MARKERS.md` in
+ * https://github.com/INTENTIUS/choudoufu. That file calls itself the one
+ * integration surface external tools may rely on, so this module implements
+ * exactly what it specifies and nothing beyond it. The spec's own tables are
+ * this module's tests (`./marker.test.ts`).
+ *
+ * ## Escape, then compare. Never decode a tag blind
+ *
+ * A canonical terraform address uses `[`, `]` and `"` to write an instance
+ * key, and AWS allows none of the three in a tag value. So an address is
+ * escaped before it is written, and the spec's comparison rule is one
+ * sentence: escape the address you already know and compare strings. The
+ * reverse, decoding a tag and hoping to recover the address, is ambiguous
+ * (`this[2]` and `this["2"]` escape alike) and the spec says not to do it
+ * where a verdict depends on the answer.
+ *
+ * The rule itself, from "Escaping rule":
+ *
+ *   1. escape the content of every instance key first (see
+ *      {@link escapeForEachKey}); a `count` index is only ever digits, so
+ *      this is a no-op for one;
+ *   2. replace every `[` with `:`;
+ *   3. delete every `]`;
+ *   4. delete every `"`.
+ *
+ * Step 1 first is what makes a `:` in an escaped value always mean "an index
+ * starts here": a key's own `.` and `:` are already gone by the time steps
+ * 2 to 4 run.
+ *
+ * ## Three escapings on the declared side
+ *
+ * The key escaping gained a layer twice, and neither change rewrote the
+ * markers already on live resources. A marker stamped before choudoufu's
+ * issue #178 escaped no key at all; one stamped between #178 and #210
+ * doubled `@`, `.` and `:` but did not carry out-of-charset characters into
+ * the AWS-legal set. So {@link addressMatches} escapes the declared address
+ * three ways and accepts any of them, which is what `AddressMatches` does in
+ * choudoufu itself. Writing always uses {@link escapeAddress}, the current
+ * form.
+ */
+/** `tofu-estate`: the estate that owns the resource. The entire ownership claim. */
+export const MARKER_TAG_ESTATE = "tofu-estate";
+/** `tofu-address`: the resource's escaped canonical address, or its first 256-character chunk. */
+export const MARKER_TAG_ADDRESS = "tofu-address";
+/** `tofu-slot`: the stable, opaque cardinality slot a `count` instance carries. */
+export const MARKER_TAG_SLOT = "tofu-slot";
+/**
+ * `tofu-address-2` through `tofu-address-4`, in order. A reader concatenates
+ * `tofu-address` and whichever of these are present; they are never
+ * meaningful on their own.
+ */
+export const MARKER_TAG_ADDRESS_CONTINUATIONS = [
+    "tofu-address-2",
+    "tofu-address-3",
+    "tofu-address-4",
+];
+/** The characters AWS allows in a tag value beside letters, digits and space. */
+const AWS_LEGAL_PUNCTUATION = new Set(["+", "-", "=", ".", "_", ":", "/", "@"]);
+/** The escape introducer of the out-of-charset layer (choudoufu issue #210). */
+const INTRODUCER = "+";
+function isAwsLegal(ch) {
+    return /^[A-Za-z0-9 ]$/.test(ch) || AWS_LEGAL_PUNCTUATION.has(ch);
+}
+/**
+ * Carry every character outside the AWS-legal set into it: `+` doubles
+ * because it is the introducer, and anything else becomes `+` followed by its
+ * Unicode code point in six uppercase hex digits. `a(b)` becomes
+ * `a+000028b+000029`; `plus+one` becomes `plus++one`.
+ */
+function escapeOutOfCharset(key) {
+    let out = "";
+    for (const ch of key) {
+        if (ch === INTRODUCER)
+            out += "++";
+        else if (isAwsLegal(ch))
+            out += ch;
+        else
+            out += INTRODUCER + ch.codePointAt(0).toString(16).toUpperCase().padStart(6, "0");
+    }
+    return out;
+}
+/**
+ * The `@` / `.` / `:` doubling (choudoufu issue #178), applied in that order
+ * so every `@` these steps introduce is never itself doubled again: `@`
+ * becomes `@@`, then `.` becomes `@d`, then `:` becomes `@c`.
+ */
+function escapeReservedPunctuation(key) {
+    let out = "";
+    for (const ch of key) {
+        if (ch === "@")
+            out += "@@";
+        else if (ch === ".")
+            out += "@d";
+        else if (ch === ":")
+            out += "@c";
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * Escape one `for_each` instance key, both layers in the specified order:
+ * out-of-charset escaping first, then the `@` / `.` / `:` doubling over its
+ * output. Order is load-bearing: the first layer's introducer is `+`, none of
+ * the three characters the second layer scans for, so the second never
+ * mistakes the first's output for its own escape sequences.
+ *
+ * Six characters cannot be carried at all and are refused at choudoufu's own
+ * lint rather than here (`"`, `\`, any non-printable, `$`, `%`, `[`, `]`);
+ * this function escapes what it is given without judging it, because chant
+ * never writes a marker, and a key chant meets in a `tofu-address` tag has
+ * already passed that lint.
+ */
+export function escapeForEachKey(key) {
+    return escapeReservedPunctuation(escapeOutOfCharset(key));
+}
+/** The pre-#210 key escaping: the doubling alone, with no out-of-charset layer. */
+function escapeForEachKeyPre210(key) {
+    return escapeReservedPunctuation(key);
+}
+/**
+ * Apply `escapeKey` to the content of every quoted instance key in `address`,
+ * then run the address-level substitution: `[` to `:`, `]` and `"` deleted.
+ */
+function escapeAddressWith(address, escapeKey) {
+    // Only a quoted key carries content that needs escaping; a `count` index is
+    // digits, which every layer leaves alone.
+    const keysEscaped = address.replace(/\["((?:[^"\\]|\\.)*)"\]/g, (_all, key) => `["${escapeKey(key)}"]`);
+    return keysEscaped.replace(/\[/g, ":").replace(/\]/g, "").replace(/"/g, "");
+}
+/**
+ * The `tofu-address` value for a canonical terraform address: the current
+ * escaping, which is the only one anything ever writes.
+ */
+export function escapeAddress(address) {
+    return escapeAddressWith(address, escapeForEachKey);
+}
+/**
+ * Every escaping a live marker could have been written under, current first:
+ * the current one, the pre-#210 one (the doubling alone), and the pre-#178
+ * one (no key escaping at all). Duplicates are collapsed, so the common
+ * address with no `for_each` key yields exactly one string.
+ */
+export function escapeAddressVariants(address) {
+    const variants = [
+        escapeAddress(address),
+        escapeAddressWith(address, escapeForEachKeyPre210),
+        escapeAddressWith(address, (key) => key),
+    ];
+    return [...new Set(variants)];
+}
+/**
+ * Does a live resource's `tofu-address` value name this declared address?
+ * The declared side is escaped and the strings are compared, three escapings
+ * deep for the migration windows; the tag is never decoded.
+ */
+export function addressMatches(declaredAddress, tagValue) {
+    return escapeAddressVariants(declaredAddress).includes(tagValue);
+}
+/**
+ * Concatenate `tofu-address` and whatever continuation tags follow it, which
+ * is the only sanctioned way to read a split address.
+ *
+ * A chain with a gap in it (`tofu-address-3` present while `tofu-address-2`
+ * is not) cannot be concatenated into anything and returns `undefined` rather
+ * than the address up to the gap.
+ */
+export function joinMarkerAddress(tags) {
+    const head = tags[MARKER_TAG_ADDRESS];
+    if (head === undefined || head === "")
+        return undefined;
+    let address = head;
+    let ended = false;
+    for (const key of MARKER_TAG_ADDRESS_CONTINUATIONS) {
+        const chunk = tags[key];
+        if (chunk === undefined || chunk === "") {
+            ended = true;
+            continue;
+        }
+        if (ended)
+            return undefined; // a gap: the chain is malformed, not shorter
+        address += chunk;
+    }
+    return address;
+}
+/**
+ * The ownership verdict `live/MARKERS.md`'s "Ownership semantics" section
+ * defines, read off one live resource's tags. Three outcomes, and no fourth:
+ * a `tofu-estate` value is the entire ownership claim with no secondary
+ * check, neither key present is foreign, and an estate without a readable
+ * address is malformed rather than either of the two.
+ */
+export function readMarker(tags) {
+    const estate = tags?.[MARKER_TAG_ESTATE];
+    if (estate === undefined || estate === "")
+        return { kind: "foreign" };
+    const address = joinMarkerAddress(tags);
+    if (address === undefined) {
+        return {
+            kind: "malformed",
+            estate,
+            detail: `carries ${MARKER_TAG_ESTATE}=${estate} but no readable ${MARKER_TAG_ADDRESS} (missing, empty, or a continuation chain with a gap in it)`,
+        };
+    }
+    const slot = tags[MARKER_TAG_SLOT];
+    return { kind: "owned", estate, address, ...(slot ? { slot } : {}) };
+}