~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
1589 lines · 67.5 KB Raw History
//! A composer's writes: the template a view's `Compose` gives (`writes`),
//! filled with what the person wrote (`values`: its fields' and its given
//! values) into the records `apply_writes` writes at once, as Bluesky's and
//! Grain's apps do with `applyWrites`.
//!
//! A template is an array of writes, each `{ collection, record, as?,
//! each?, when?, whenItem?, rkey?, update? }`: `each` names a value that is
//! an array (photos), one record made per element; `when` names values that
//! must be there for it to be made; `whenItem` a path within the element
//! that must be; `as` names it, for others to read its at-uri or record
//! key; `rkey`, `{"$rkey": as}`, takes another write's key (a threadgate
//! keeps its post's). `update`, a record key (`self`) or `{"$value": name}`
//! holding one (a gallery's, given), replaces the one record there (a
//! profile, a gallery): `apply_writes` reads it first,
//! `{"$stored": path}` reads that, and what is written is the record as it
//! was stored with the fields the template names set to what they make
//! (taken out where they make nothing), the rest kept as they are; where
//! there is none yet, it is created. A record's values are literals or:
//!
//! - `{"$value": "name.path"}`: a value, or a path within it (an array's
//!   element by its index, `photos.0.blob`);
//! - `{"$item": "path"}` (`"."` the element itself), `{"$index": true}`:
//!   within an `each` write, or a `$each`;
//! - `{"$each": name, "value": template}`: an array, one per element;
//! - `{"$when": [names], "value": template}`: the template, where every
//!   value named is there;
//! - `{"$first": [templates]}`: the first of 2 to 4 that is there;
//! - `{"$merge": [templates]}`: objects merged, the later winning;
//! - `{"$uri": as}`, `{"$rkey": as}`: another write's at-uri or record key
//!   (the same element's, where both are made per element);
//! - `{"$stored": "path"}` (`"."` the record itself): within an update, the
//!   record it replaces, as stored (a profile's avatar, its blob ref);
//! - `{"$now": true}`: the time it is sent;
//! - `{"$facets": key}`: left as it is, for `create`'s facets
//!   (`writes::facets_made`), the text in the record's field `key`.
//!
//! What is not there (a value not given, null) is left out: an object's
//! field, an array's element; a record made of nothing is refused.

use serde_json::{Map, Value, json};

/// The most writes a template names.
pub const MAX_TEMPLATE: usize = 8;
/// The most records one send creates (Grain's 10 photos, each its item and
/// its camera's details, and the gallery).
pub const MAX_WRITES: usize = 32;
/// How deep a template nests.
const MAX_DEPTH: usize = 12;

/// A record to write: its collection, its record key and the record, and
/// for an update, what it replaces.
#[derive(Debug, PartialEq)]
pub struct Made {
    pub collection: String,
    pub rkey: String,
    pub record: Value,
    pub update: Option<Update>,
}

/// An update's: the record it replaces as stored (none where there is none
/// yet, and it is created) and the fields its template names.
#[derive(Clone, Debug, PartialEq)]
pub struct Update {
    pub stored: Option<Value>,
    pub names: Vec<String>,
}

impl Update {
    /// The record written: the stored one, each field the template names
    /// set to what it `made` (taken out where it made nothing), the rest
    /// kept as they are; with none stored, what it made.
    pub fn over(self, made: Value) -> Value {
        match (self.stored, made) {
            (Some(Value::Object(mut out)), Value::Object(made)) => {
                out.retain(|k, _| !self.names.contains(k));
                out.extend(made);
                Value::Object(out)
            }
            (_, made) => made,
        }
    }
}

const KEYS: &[&str] = &[
    "collection",
    "record",
    "as",
    "each",
    "when",
    "whenItem",
    "rkey",
    "update",
];

fn is_name(s: &str) -> bool {
    !s.is_empty()
        && s.len() <= 32
        && s.chars().next().is_some_and(|c| c.is_ascii_lowercase())
        && s.chars().all(|c| c.is_ascii_alphanumeric())
}

fn is_path(s: &str) -> bool {
    s == "."
        || (!s.is_empty()
            && s.len() <= 128
            && s.split('.')
                .all(|k| !k.is_empty() && k.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')))
}

/// What a writes template's problems are, each where it is: `names` the
/// values it may read (its fields' and given values' names), or any.
pub fn problems(writes: &Value, names: Option<&[String]>) -> Vec<String> {
    let mut out = Vec::new();
    let Some(list) = writes
        .as_array()
        .filter(|a| (1..=MAX_TEMPLATE).contains(&a.len()))
    else {
        out.push(format!(
            "writes: must be an array of 1 to {MAX_TEMPLATE} writes"
        ));
        return out;
    };
    let known = |n: &str| names.is_none_or(|ns| ns.iter().any(|k| k == n));
    let named: Vec<&str> = list.iter().filter_map(|w| w["as"].as_str()).collect();
    for (i, w) in list.iter().enumerate() {
        let at = format!("writes[{i}]");
        let Some(o) = w.as_object() else {
            out.push(format!("{at}: must be an object"));
            continue;
        };
        for k in o.keys().filter(|k| !KEYS.contains(&k.as_str())) {
            out.push(format!("{at}.{k}: a write has no {k}"));
        }
        if !o
            .get("collection")
            .and_then(Value::as_str)
            .is_some_and(atproto::syntax::is_nsid)
        {
            out.push(format!("{at}.collection: required: an NSID"));
        }
        if let Some(a) = o.get("as") {
            match a.as_str() {
                Some(a) if is_name(a) && named.iter().filter(|n| **n == a).count() == 1 => {}
                _ => out.push(format!("{at}.as: a name, once among the writes")),
            }
        }
        let each = o.get("each");
        if let Some(e) = each
            && !e.as_str().is_some_and(|e| is_name(e) && known(e))
        {
            out.push(format!("{at}.each: names a value given or written"));
        }
        if let Some(w) = o.get("when") {
            let ok = w.as_array().is_some_and(|a| {
                (1..=4).contains(&a.len())
                    && a.iter()
                        .all(|n| n.as_str().is_some_and(|n| is_name(n) && known(n)))
            });
            if !ok {
                out.push(format!("{at}.when: 1 to 4 names of values"));
            }
        }
        if let Some(p) = o.get("whenItem")
            && (each.is_none() || !p.as_str().is_some_and(is_path))
        {
            out.push(format!(
                "{at}.whenItem: a path within each element, with each"
            ));
        }
        if let Some(r) = o.get("rkey")
            && !r
                .as_object()
                .filter(|r| r.len() == 1)
                .and_then(|r| r.get("$rkey"))
                .and_then(Value::as_str)
                .is_some_and(|a| named.contains(&a))
        {
            out.push(format!("{at}.rkey: {{\"$rkey\": as}}, another write's"));
        }
        let update = o.contains_key("update");
        let key_of_its_own = o
            .get("update")
            .and_then(Value::as_str)
            .is_some_and(atproto::syntax::is_record_key);
        let key_given = o.get("update").and_then(Value::as_object).is_some_and(|u| {
            u.len() == 1
                && u.get("$value").and_then(Value::as_str).is_some_and(|p| {
                    is_path(p) && p != "." && known(p.split('.').next().unwrap_or(""))
                })
        });
        if update && (!(key_of_its_own || key_given) || each.is_some() || o.contains_key("rkey")) {
            out.push(format!(
                "{at}.update: the record key of the one record it replaces, or {{\"$value\": name}} holding it, with no each or rkey"
            ));
        }
        match o.get("record") {
            Some(Value::Object(r))
                if update && r.keys().any(|k| k.starts_with('$') && k != "$type") =>
            {
                out.push(format!(
                    "{at}.record: an update's record names its fields, with no operator at its top"
                ));
            }
            Some(r @ Value::Object(_)) => {
                let within = Within {
                    item: each.is_some(),
                    stored: update,
                    named: &named,
                    known: &known,
                };
                template(&mut out, r, &format!("{at}.record"), 1, within);
            }
            _ => out.push(format!("{at}.record: required: an object")),
        }
    }
    out
}

/// What a template's operators may read where it is: an element (within
/// `each` or `$each`), the record an update replaces, the writes' names
/// (`as`), and whether a value's name is known.
#[derive(Clone, Copy)]
struct Within<'a> {
    item: bool,
    stored: bool,
    named: &'a [&'a str],
    known: &'a dyn Fn(&str) -> bool,
}

fn template(out: &mut Vec<String>, v: &Value, at: &str, depth: usize, w: Within) {
    if depth > MAX_DEPTH {
        out.push(format!("{at}: a template nests at most {MAX_DEPTH} deep"));
        return;
    }
    let op = v
        .as_object()
        .and_then(|o| o.keys().find(|k| k.starts_with('$') && *k != "$type"))
        .cloned();
    let o = v.as_object();
    let alone = |k: &str| o.is_some_and(|o| o.len() == 1 && o.contains_key(k));
    let mut bad = |what: &str| out.push(format!("{at}: {what}"));
    match op.as_deref() {
        None => match v {
            Value::Object(o) => {
                for (k, x) in o {
                    if k == "$type" && !x.is_string() {
                        out.push(format!("{at}.$type: must be a string"));
                    } else if k != "$type" {
                        template(out, x, &format!("{at}.{k}"), depth + 1, w);
                    }
                }
            }
            Value::Array(a) => {
                for (i, x) in a.iter().enumerate() {
                    template(out, x, &format!("{at}[{i}]"), depth + 1, w);
                }
            }
            _ => {}
        },
        Some("$value") => {
            let ok = alone("$value")
                && v["$value"].as_str().is_some_and(|p| {
                    is_path(p) && p != "." && (w.known)(p.split('.').next().unwrap_or(""))
                });
            if !ok {
                bad("{\"$value\": path} has the key alone, a path whose first key names a value");
            }
        }
        Some("$item") => {
            if !w.item {
                bad("$item reads an element, within each or $each alone");
            } else if !(alone("$item") && v["$item"].as_str().is_some_and(is_path)) {
                bad("{\"$item\": path} has the key alone, a path or \".\"");
            }
        }
        Some("$stored") => {
            if !w.stored {
                bad("$stored reads the record an update replaces, within an update alone");
            } else if !(alone("$stored") && v["$stored"].as_str().is_some_and(is_path)) {
                bad("{\"$stored\": path} has the key alone, a path or \".\"");
            }
        }
        Some("$index") => {
            if !w.item || !alone("$index") || v["$index"] != Value::Bool(true) {
                bad("{\"$index\": true} alone, within each or $each");
            }
        }
        Some("$now") => {
            if !alone("$now") || v["$now"] != Value::Bool(true) {
                bad("{\"$now\": true} has the key $now alone, true");
            }
        }
        Some("$uri" | "$rkey") => {
            let k = op.as_deref().unwrap_or_default();
            if !(alone(k) && v[k].as_str().is_some_and(|a| w.named.contains(&a))) {
                bad(&format!("{{\"{k}\": as}} has the key alone, a write's as"));
            }
        }
        Some("$facets") => {
            if !alone("$facets") || !v["$facets"].is_string() {
                bad("{\"$facets\": key} has the key alone, the field holding the text");
            }
        }
        Some("$each") => {
            let ok = o.is_some_and(|o| o.len() == 2 && o.contains_key("value"))
                && v["$each"]
                    .as_str()
                    .is_some_and(|e| is_name(e) && (w.known)(e));
            if ok {
                let inner = Within { item: true, ..w };
                template(out, &v["value"], &format!("{at}.value"), depth + 1, inner);
            } else {
                bad("{\"$each\": name, \"value\": template}, a value's name");
            }
        }
        Some("$when") => {
            let ok = o.is_some_and(|o| o.len() == 2 && o.contains_key("value"))
                && v["$when"].as_array().is_some_and(|a| {
                    (1..=4).contains(&a.len())
                        && a.iter()
                            .all(|n| n.as_str().is_some_and(|n| is_name(n) && (w.known)(n)))
                });
            if ok {
                template(out, &v["value"], &format!("{at}.value"), depth + 1, w);
            } else {
                bad("{\"$when\": [names], \"value\": template}, 1 to 4 values' names");
            }
        }
        Some(k @ ("$first" | "$merge")) => match v[k].as_array() {
            Some(a) if alone(k) && (2..=4).contains(&a.len()) => {
                for (i, x) in a.iter().enumerate() {
                    template(out, x, &format!("{at}.{k}[{i}]"), depth + 1, w);
                }
            }
            _ => bad(&format!(
                "{{\"{k}\": [templates]}} has the key alone, 2 to 4 templates"
            )),
        },
        Some(k) => bad(&format!(
            "{k}: a key starting with $ is $type, or $value's, $item's, $index's, $each's, $when's, $first's, $merge's, $uri's, $rkey's, $stored's, $now's or $facets' alone"
        )),
    }
}

/// The kinds of field a composer asks, and the keys each takes beside
/// `name`, `kind`, `label` and `required`. `value`, a binding the view
/// reads, is what it opens holding: a text's words, a photo's picture
/// (shown, kept unless another is picked). A photos field's `exif` and a
/// place's `locate` may be bindings too, an account's preference, on
/// unless it holds false.
const KINDS: &[(&str, &[&str])] = &[
    (
        "text",
        &["placeholder", "max", "facets", "suggest", "value"],
    ),
    ("line", &["placeholder", "max", "value"]),
    (
        "photos",
        &[
            "min", "max", "alt", "exif", "maxBytes", "maxSide", "value", "round", "camera",
        ],
    ),
    ("langs", &["max"]),
    ("labels", &["options"]),
    ("choice", &["options", "multiple"]),
    ("place", &["from", "locate"]),
    ("card", &["from"]),
];

/// A binding `{"$": path}` (or paths) the view reads.
fn is_bound(v: &Value) -> bool {
    v.as_object()
        .is_some_and(|o| o.len() == 1 && o.get("$").is_some_and(|p| p.is_string() || p.is_array()))
}

/// Words joined `{"$join": [parts]}`, each a string or a binding: what a
/// text or line opens holding, as a reply's `@handle ` of whom it answers.
fn is_joined(v: &Value) -> bool {
    v.as_object()
        .filter(|o| o.len() == 1)
        .and_then(|o| o.get("$join"))
        .and_then(Value::as_array)
        .is_some_and(|parts| {
            !parts.is_empty() && parts.iter().all(|p| p.is_string() || is_bound(p))
        })
}

/// What a composer's fields' problems are, each where it is, and their
/// names (what its writes may read, with its given values').
pub fn fields_problems(fields: &Value, at: &str) -> (Vec<String>, Vec<String>) {
    let mut out = Vec::new();
    let mut names = Vec::new();
    let Some(list) = fields.as_array().filter(|a| (1..=10).contains(&a.len())) else {
        out.push(format!("{at}: must be an array of 1 to 10 fields"));
        return (out, names);
    };
    let short = |v: &Value, max: usize| {
        v.as_str().is_some_and(|s| {
            (1..=max).contains(&s.chars().count()) && !s.contains(char::is_control)
        })
    };
    let int = |v: &Value, lo: u64, hi: u64| v.as_u64().is_some_and(|n| (lo..=hi).contains(&n));
    let of_kind = |kind: &str| -> Vec<&str> {
        list.iter()
            .filter(|f| f["kind"] == kind)
            .filter_map(|f| f["name"].as_str())
            .collect()
    };
    let (texts, photos) = (of_kind("text"), of_kind("photos"));
    for (i, f) in list.iter().enumerate() {
        let fat = format!("{at}[{i}]");
        let mut bad = |k: &str, what: &str| out.push(format!("{fat}.{k}: {what}"));
        let Some(o) = f.as_object() else {
            out.push(format!("{fat}: must be an object"));
            continue;
        };
        let name = o.get("name").and_then(Value::as_str).filter(|n| is_name(n));
        match name {
            Some(n) if !names.iter().any(|k| k == n) => names.push(n.to_string()),
            _ => bad(
                "name",
                "a name (lowercase letters and digits), once among the fields",
            ),
        }
        let Some((kind, takes)) = o
            .get("kind")
            .and_then(Value::as_str)
            .and_then(|k| KINDS.iter().find(|(n, _)| *n == k))
        else {
            bad(
                "kind",
                &format!(
                    "one of {}",
                    KINDS.iter().map(|(k, _)| *k).collect::<Vec<_>>().join(", ")
                ),
            );
            continue;
        };
        for (k, v) in o {
            match k.as_str() {
                "name" | "kind" => {}
                "label" if !short(v, 40) => bad(k, "text of at most 40 characters"),
                "required" if !v.is_boolean() => bad(k, "true or false"),
                "label" | "required" => {}
                k if !takes.contains(&k) => bad(k, &format!("a {kind} field takes no {k}")),
                "placeholder" if !short(v, 80) => bad(k, "text of at most 80 characters"),
                "max" if *kind == "text" && !int(v, 1, 10000) => bad(k, "graphemes, 1 to 10000"),
                "max" if *kind == "line" && !int(v, 1, 1000) => bad(k, "graphemes, 1 to 1000"),
                "max" if *kind == "photos" && !int(v, 1, 10) => bad(k, "1 to 10 photos"),
                "max" if *kind == "langs" && !int(v, 1, 3) => bad(k, "1 to 3 languages"),
                "min" if !int(v, 0, 10) => bad(k, "0 to 10 photos"),
                "maxBytes" if !int(v, 10_000, 2_000_000) => bad(k, "bytes, 10000 to 2000000"),
                "maxSide" if !int(v, 256, 4096) => bad(k, "pixels, 256 to 4096"),
                "facets" | "alt" | "multiple" | "round" | "camera" if !v.is_boolean() => {
                    bad(k, "true or false")
                }
                "exif" | "locate" if !v.is_boolean() && !is_bound(v) => bad(
                    k,
                    "true or false, or a binding {\"$\": path}, on unless false",
                ),
                "from" if *kind == "card" && !v.as_str().is_some_and(|t| texts.contains(&t)) => {
                    bad(k, "names a text field")
                }
                "from" if *kind == "place" && !v.as_str().is_some_and(|t| photos.contains(&t)) => {
                    bad(k, "names a photos field")
                }
                "suggest" => suggest_problems(v, &mut bad),
                "value" if !is_bound(v) && !(*kind != "photos" && is_joined(v)) => bad(
                    k,
                    "a binding {\"$\": path} (a text or line's also {\"$join\": [parts]}), what it opens holding",
                ),
                "options" => {
                    let opts = v.as_array().filter(|a| (1..=8).contains(&a.len()));
                    let ok = opts.is_some_and(|a| {
                        a.iter().all(|o| {
                            o.as_object().is_some_and(|o| {
                                o.keys()
                                    .all(|k| matches!(k.as_str(), "label" | "value" | "only"))
                                    && short(&o["label"], 40)
                                    && o.contains_key("value")
                                    && (*kind != "labels" || short(&o["value"], 64))
                                    && o.get("only").is_none_or(Value::is_boolean)
                            })
                        })
                    });
                    if !ok {
                        bad(k, "1 to 8 options, each { label, value, only? }");
                    }
                }
                _ => {}
            }
        }
        if *kind == "photos" {
            let (min, max) = (
                o.get("min").and_then(Value::as_u64),
                o.get("max").and_then(Value::as_u64),
            );
            if min.zip(max).is_some_and(|(a, b)| a > b) {
                bad("min", "at most max");
            }
            for k in ["max", "maxBytes", "maxSide"] {
                if !o.contains_key(k) {
                    bad(k, "required");
                }
            }
        }
        if matches!(*kind, "labels" | "choice") && !o.contains_key("options") {
            bad("options", "required");
        }
        if *kind == "card" && !o.contains_key("from") {
            bad("from", "required: the text field whose link it shows");
        }
    }
    (out, names)
}

/// The most a composer's field may hold, as the lexicons of the records its
/// value is written into say: grapheme clusters (`maxGraphemes`) and UTF-8
/// bytes (`maxLength`), the narrowest of each where several write it.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Limit {
    pub graphemes: Option<u64>,
    pub bytes: Option<u64>,
}

/// `at` narrowed to `by`, whichever of them is a limit.
fn narrow(at: Option<u64>, by: Option<u64>) -> Option<u64> {
    at.into_iter().chain(by).min()
}

/// The limit of the field `name` by the writes template `writes`: each
/// record property its value is, whole (`{"$value": name}`), read in the
/// record's bundled lexicon. A collection with none limits nothing.
pub fn limit(name: &str, writes: &Value) -> Limit {
    let whole = json!({ "$value": name });
    let mut out = Limit::default();
    for w in writes.as_array().into_iter().flatten() {
        let doc = w["collection"].as_str().and_then(crate::lexicon::bundled);
        let main = doc.as_ref().map(|d| &d["defs"]["main"]);
        let props = main.map(|m| &m["record"]["properties"]);
        for (k, v) in w["record"].as_object().into_iter().flatten() {
            if let Some(p) = props.map(|p| &p[k]).filter(|_| *v == whole) {
                out.graphemes = narrow(out.graphemes, p["maxGraphemes"].as_u64());
                out.bytes = narrow(out.bytes, p["maxLength"].as_u64());
            }
        }
    }
    out
}

/// What is wrong with a composer's text and line fields' `max` against
/// what its `writes` limit them to (`limit`): one wider than a lexicon's
/// graphemes or bytes (a grapheme is a byte at least), or none where no
/// lexicon limits it. A view's `max` only narrows a lexicon's.
pub fn limit_problems(fields: &Value, writes: &Value) -> Vec<String> {
    let mut out = Vec::new();
    for (i, f) in fields.as_array().into_iter().flatten().enumerate() {
        let lex = limit(f["name"].as_str().unwrap_or_default(), writes);
        let max = f.get("max");
        let wider = |n: u64| max.and_then(Value::as_u64).is_some_and(|m| m > n);
        let problem = match (f["kind"].as_str(), lex.graphemes, lex.bytes) {
            (Some("text" | "line"), None, None) if max.is_none() => {
                "required: no lexicon of a record it is written into limits it".to_string()
            }
            (Some("text" | "line"), Some(g), _) if wider(g) => {
                format!("at most its record's lexicon's {g} graphemes")
            }
            (Some("text" | "line"), _, Some(b)) if wider(b) => {
                format!("at most its record's lexicon's {b} bytes")
            }
            _ => continue,
        };
        out.push(format!("fields[{i}].max: {problem}"));
    }
    out
}

/// A composer's field as the form asks it, a text's or line's limits read
/// from its `writes` (`limit`): `max`, its graphemes, the view's narrowed
/// by the lexicon's, and `maxBytes`, its UTF-8 bytes, the lexicon's.
pub fn limited(mut field: Value, writes: &Value) -> Value {
    if let (Some("text" | "line"), Some(name)) = (field["kind"].as_str(), field["name"].as_str()) {
        let lex = limit(name, writes);
        if let Some(g) = narrow(field["max"].as_u64(), lex.graphemes) {
            field["max"] = g.into();
        }
        if let Some(b) = lex.bytes {
            field["maxBytes"] = b.into();
        }
    }
    field
}

/// A text field's suggestions: `{ method, service?, param, params?, items,
/// did, handle, name?, avatar? }`, a query and where in its answer the
/// accounts are.
fn suggest_problems(v: &Value, bad: &mut dyn FnMut(&str, &str)) {
    const KEYS: &[&str] = &[
        "method", "service", "param", "params", "items", "did", "handle", "name", "avatar",
    ];
    let ok = v.as_object().is_some_and(|o| {
        o.keys().all(|k| KEYS.contains(&k.as_str()))
            && o.get("method")
                .and_then(Value::as_str)
                .is_some_and(atproto::syntax::is_nsid)
            && o.get("service").is_none_or(|s| {
                s.as_str()
                    .is_some_and(|s| crate::xrpc::Service::parse(s).is_ok())
            })
            && o.get("param").and_then(Value::as_str).is_some_and(is_name)
            && o.get("params").is_none_or(|p| {
                p.as_object().is_some_and(|p| {
                    p.len() <= 8 && p.values().all(|v| !v.is_object() && !v.is_array())
                })
            })
            && ["items", "did", "handle"]
                .iter()
                .all(|k| o.get(*k).and_then(Value::as_str).is_some_and(is_path))
            && ["name", "avatar"]
                .iter()
                .all(|k| o.get(*k).is_none_or(|p| p.as_str().is_some_and(is_path)))
    });
    if !ok {
        bad(
            "suggest",
            "{ method, service?, param, params? (literals), items, did, handle, name?, avatar? }, paths into its answer",
        );
    }
}

/// What a value or element holds at `path` ("." itself; an array's
/// element by its index), if anything.
fn at<'a>(v: &'a Value, path: &str) -> Option<&'a Value> {
    if path == "." {
        return Some(v).filter(|v| !v.is_null());
    }
    path.split('.')
        .try_fold(v, |v, k| match v {
            Value::Array(a) => k.parse::<usize>().ok().and_then(|i| a.get(i)),
            _ => v.get(k),
        })
        .filter(|v| !v.is_null())
}

/// What `values` holds at `path`, its first key a value's name.
fn value_at<'a>(values: &'a Map<String, Value>, path: &str) -> Option<&'a Value> {
    let (name, rest) = path.split_once('.').unwrap_or((path, "."));
    values.get(name).and_then(|v| at(v, rest))
}

/// The record key the `i`th write updates, if it is an update: its own,
/// or what the value it names holds (a gallery's, given), which must be
/// a record key.
fn update_key(w: &Value, values: &Map<String, Value>, i: usize) -> Result<Option<String>, String> {
    let key = match &w["update"] {
        Value::Null => return Ok(None),
        Value::String(k) => Some(k.as_str()),
        named => {
            value_at(values, named["$value"].as_str().unwrap_or_default()).and_then(Value::as_str)
        }
    };
    match key.filter(|k| atproto::syntax::is_record_key(k)) {
        Some(k) => Ok(Some(k.to_string())),
        None => Err(format!(
            "writes[{i}].update: the value it names holds no record key"
        )),
    }
}

/// The record each write updates, where it is an update: its collection
/// and record key (its own, or read from `values`), for `apply_writes` to
/// read as it is stored before `expand`; a template with a problem, or an
/// update whose value holds no record key, refused, by the first.
pub fn updated(
    writes: &Value,
    values: &Map<String, Value>,
) -> Result<Vec<Option<(String, String)>>, String> {
    if let Some(p) = problems(writes, None).into_iter().next() {
        return Err(p);
    }
    let mut out = Vec::new();
    for (i, w) in writes.as_array().into_iter().flatten().enumerate() {
        let collection = w["collection"].as_str().unwrap_or_default();
        out.push(update_key(w, values, i)?.map(|k| (collection.to_string(), k)));
    }
    Ok(out)
}

/// The writes a template makes with `values`, their record keys from `tid`
/// (or their own), their at-uris in `did`'s repository, `now` the time,
/// `stored` the record each update replaces as `updated` found it (by its
/// write's index; none where there is none yet): every record made.
pub fn expand(
    writes: &Value,
    values: &Map<String, Value>,
    stored: &[Option<Value>],
    did: &str,
    now: &str,
    mut tid: impl FnMut() -> String,
) -> Result<Vec<Made>, String> {
    let problems = problems(writes, None);
    if let Some(p) = problems.first() {
        return Err(p.clone());
    }
    let list = writes.as_array().expect("checked");
    let mut updates = Vec::new();
    for (i, w) in list.iter().enumerate() {
        updates.push(update_key(w, values, i)?);
    }
    let values = Value::Object(values.clone());
    let stored_at = |i: usize| stored.get(i).and_then(Option::as_ref);
    // Each write's instances: the element of its `each` each stands for
    // (None for one made once), those `when` and `whenItem` leave.
    let mut instances: Vec<Vec<Option<usize>>> = Vec::new();
    for w in list {
        let made = w["when"].as_array().is_none_or(|ns| {
            ns.iter()
                .all(|n| at(&values, n.as_str().unwrap_or("")).is_some())
        });
        let these = match (made, w["each"].as_str()) {
            (false, _) => vec![],
            (true, None) => vec![None],
            (true, Some(e)) => {
                let elements = at(&values, e)
                    .and_then(Value::as_array)
                    .cloned()
                    .unwrap_or_default();
                (0..elements.len())
                    .filter(|&i| {
                        w["whenItem"]
                            .as_str()
                            .is_none_or(|p| at(&elements[i], p).is_some())
                    })
                    .map(Some)
                    .collect()
            }
        };
        instances.push(these);
    }
    let total: usize = instances.iter().map(Vec::len).sum();
    if total > MAX_WRITES {
        return Err(format!(
            "{total} records, more than the {MAX_WRITES} one send makes"
        ));
    }
    let index_of = |a: &str| list.iter().position(|w| w["as"] == a);
    // Record keys first, so any write may name another's.
    let mut rkeys: Vec<Vec<String>> = updates
        .iter()
        .zip(&instances)
        .map(|(key, is)| {
            is.iter()
                .map(|_| key.clone().unwrap_or_else(&mut tid))
                .collect()
        })
        .collect();
    for (i, w) in list.iter().enumerate() {
        if let Some(other) = w["rkey"]["$rkey"].as_str().and_then(index_of) {
            for (n, element) in instances[i].clone().iter().enumerate() {
                let found = pick(&instances[other], *element).map(|k| rkeys[other][k].clone());
                let Some(found) = found else {
                    return Err(format!(
                        "writes[{i}].rkey: no record of writes[{other}] to share a key with"
                    ));
                };
                rkeys[i][n] = found;
            }
        }
    }
    let refs = Refs {
        list,
        instances: &instances,
        rkeys: &rkeys,
        did,
    };
    let mut made = Vec::new();
    for (i, w) in list.iter().enumerate() {
        let collection = w["collection"].as_str().unwrap_or_default();
        let elements = w["each"]
            .as_str()
            .and_then(|e| at(&values, e))
            .and_then(Value::as_array);
        let update = updates[i].is_some().then(|| Update {
            stored: stored_at(i).cloned(),
            names: w["record"]
                .as_object()
                .into_iter()
                .flatten()
                .map(|(k, _)| k.clone())
                .collect(),
        });
        for (n, element) in instances[i].iter().enumerate() {
            let scope = Scope {
                values: &values,
                item: element.and_then(|e| elements.map(|a| (&a[e], e))),
                stored: stored_at(i),
                now,
                refs: &refs,
            };
            let record = fill(&w["record"], &scope)?
                .filter(|r| r.as_object().is_some_and(|o| !o.is_empty()));
            let Some(record) = record else {
                return Err(format!("writes[{i}]: its record holds nothing"));
            };
            made.push(Made {
                collection: collection.to_string(),
                rkey: rkeys[i][n].clone(),
                record,
                update: update.clone(),
            });
        }
    }
    Ok(made)
}

/// Which of a write's instances goes with `element`: the same element's
/// where it is made per element, else its one.
fn pick(instances: &[Option<usize>], element: Option<usize>) -> Option<usize> {
    match instances {
        [None] => Some(0),
        _ => instances.iter().position(|i| i.is_some() && *i == element),
    }
}

struct Refs<'a> {
    list: &'a [Value],
    instances: &'a [Vec<Option<usize>>],
    rkeys: &'a [Vec<String>],
    did: &'a str,
}

struct Scope<'a> {
    values: &'a Value,
    /// The element read, and its index.
    item: Option<(&'a Value, usize)>,
    /// The record an update replaces, as stored.
    stored: Option<&'a Value>,
    now: &'a str,
    refs: &'a Refs<'a>,
}

/// A template filled: `None` where what it reads is not there.
fn fill(v: &Value, s: &Scope) -> Result<Option<Value>, String> {
    let Some(o) = v.as_object() else {
        return match v {
            Value::Array(a) => {
                let mut out = Vec::new();
                for x in a {
                    out.extend(fill(x, s)?);
                }
                Ok(Some(Value::Array(out)))
            }
            _ => Ok(Some(v.clone())),
        };
    };
    if let Some(p) = o.get("$value").and_then(Value::as_str) {
        return Ok(at(s.values, p).cloned());
    }
    if let Some(p) = o.get("$item").and_then(Value::as_str) {
        return Ok(s.item.and_then(|(e, _)| at(e, p)).cloned());
    }
    if let Some(p) = o.get("$stored").and_then(Value::as_str) {
        return Ok(s.stored.and_then(|r| at(r, p)).cloned());
    }
    if o.contains_key("$index") {
        return Ok(s.item.map(|(_, i)| json!(i)));
    }
    if o.contains_key("$now") {
        return Ok(Some(s.now.into()));
    }
    if o.contains_key("$facets") {
        return Ok(Some(v.clone()));
    }
    for k in ["$uri", "$rkey"] {
        if let Some(a) = o.get(k).and_then(Value::as_str) {
            let r = s.refs;
            // `problems` holds `a` to a write's `as`: what may be missing is
            // its instance for this element.
            let found = r.list.iter().position(|w| w["as"] == a).and_then(|w| {
                let n = pick(&r.instances[w], s.item.map(|(_, i)| i))?;
                Some((w, n))
            });
            let Some((w, n)) = found else {
                return Ok(None);
            };
            let rkey = &r.rkeys[w][n];
            return Ok(Some(if k == "$rkey" {
                rkey.as_str().into()
            } else {
                format!(
                    "at://{}/{}/{rkey}",
                    r.did,
                    r.list[w]["collection"].as_str().unwrap_or_default()
                )
                .into()
            }));
        }
    }
    if let Some(e) = o.get("$each").and_then(Value::as_str) {
        let Some(elements) = at(s.values, e).and_then(Value::as_array) else {
            return Ok(None);
        };
        let mut out = Vec::new();
        for (i, element) in elements.iter().enumerate() {
            let inner = Scope {
                values: s.values,
                item: Some((element, i)),
                stored: s.stored,
                now: s.now,
                refs: s.refs,
            };
            out.extend(fill(&o["value"], &inner)?);
        }
        return Ok(Some(Value::Array(out)));
    }
    if let Some(names) = o.get("$when").and_then(Value::as_array) {
        let there = names
            .iter()
            .all(|n| at(s.values, n.as_str().unwrap_or("")).is_some());
        return if there {
            fill(&o["value"], s)
        } else {
            Ok(None)
        };
    }
    if let Some(firsts) = o.get("$first").and_then(Value::as_array) {
        for x in firsts {
            if let Some(found) = fill(x, s)? {
                return Ok(Some(found));
            }
        }
        return Ok(None);
    }
    if let Some(parts) = o.get("$merge").and_then(Value::as_array) {
        let mut out = Map::new();
        for x in parts {
            if let Some(Value::Object(part)) = fill(x, s)? {
                out.extend(part);
            }
        }
        return Ok(Some(Value::Object(out)));
    }
    let mut out = Map::new();
    for (k, x) in o {
        if let Some(found) = fill(x, s)? {
            out.insert(k.clone(), found);
        }
    }
    Ok(Some(Value::Object(out)))
}

#[cfg(test)]
mod tests {
    use super::*;

    fn tids() -> impl FnMut() -> String {
        let mut n = 0;
        move || {
            n += 1;
            format!("3k{n:011}")
        }
    }

    /// A Grain gallery: a photo per photo, its camera's details where it has
    /// some, the gallery, an item per photo pointing at both; the absent left
    /// out.
    #[test]
    fn a_gallery_and_its_photos_at_once() {
        let writes = json!([
            { "as": "photo", "each": "photos", "collection": "social.grain.photo", "record": {
                "photo": { "$item": "blob" }, "alt": { "$item": "alt" }, "aspectRatio": { "$item": "aspectRatio" }, "createdAt": { "$now": true } } },
            { "each": "photos", "whenItem": "exif", "collection": "social.grain.photo.exif", "record": {
                "$merge": [{ "$item": "exif" }, { "photo": { "$uri": "photo" }, "createdAt": { "$now": true } }] } },
            { "as": "gallery", "collection": "social.grain.gallery", "record": {
                "title": { "$value": "title" }, "description": { "$value": "description" }, "facets": { "$facets": "description" },
                "location": { "$when": ["place"], "value": { "name": { "$value": "place.name" }, "value": { "$value": "place.value" } } },
                "createdAt": { "$now": true } } },
            { "each": "photos", "collection": "social.grain.gallery.item", "record": {
                "gallery": { "$uri": "gallery" }, "item": { "$uri": "photo" }, "position": { "$index": true }, "createdAt": { "$now": true } } },
        ]);
        assert_eq!(problems(&writes, None), Vec::<String>::new());
        let values = json!({ "title": "nyc", "photos": [
            { "blob": { "ref": "a" }, "alt": "skyline", "aspectRatio": { "width": 3, "height": 4 }, "exif": { "iSO": 400 } },
            { "blob": { "ref": "b" }, "alt": "", "aspectRatio": { "width": 4, "height": 3 } },
        ] });
        let made = expand(
            &writes,
            values.as_object().unwrap(),
            &[],
            "did:plc:me",
            "2026-11-18T00:00:00.000Z",
            tids(),
        )
        .unwrap();
        let kinds: Vec<&str> = made.iter().map(|m| m.collection.as_str()).collect();
        assert_eq!(
            kinds,
            [
                "social.grain.photo",
                "social.grain.photo",
                "social.grain.photo.exif",
                "social.grain.gallery",
                "social.grain.gallery.item",
                "social.grain.gallery.item"
            ]
        );
        let photo = |n: usize| format!("at://did:plc:me/social.grain.photo/{}", made[n].rkey);
        assert_eq!(
            made[2].record,
            json!({ "iSO": 400, "photo": photo(0), "createdAt": "2026-11-18T00:00:00.000Z" })
        );
        // No description, no place: left out; the facets left for create.
        assert_eq!(
            made[3].record,
            json!({ "title": "nyc", "facets": { "$facets": "description" }, "createdAt": "2026-11-18T00:00:00.000Z" })
        );
        let gallery = format!("at://did:plc:me/social.grain.gallery/{}", made[3].rkey);
        assert_eq!(made[5].record["item"], photo(1));
        assert_eq!(
            (&made[5].record["gallery"], &made[5].record["position"]),
            (&json!(gallery), &json!(1))
        );
    }

    /// A Bluesky post: its embed the first that is there, its threadgate
    /// made only when asked for, with the post's own record key.
    #[test]
    fn a_post_its_embed_and_its_threadgate() {
        let images = json!({ "$type": "app.bsky.embed.images", "images": { "$each": "photos", "value": {
            "image": { "$item": "blob" }, "alt": { "$item": "alt" } } } });
        let writes = json!([
            { "as": "post", "collection": "app.bsky.feed.post", "record": {
                "text": { "$value": "text" }, "langs": { "$value": "langs" }, "createdAt": { "$now": true },
                "embed": { "$first": [
                    { "$when": ["quote", "photos"], "value": { "$type": "app.bsky.embed.recordWithMedia", "record": { "record": { "$value": "quote" } }, "media": images } },
                    { "$when": ["quote"], "value": { "$type": "app.bsky.embed.record", "record": { "$value": "quote" } } },
                    { "$when": ["photos"], "value": images },
                ] } } },
            { "when": ["gate"], "rkey": { "$rkey": "post" }, "collection": "app.bsky.feed.threadgate", "record": {
                "post": { "$uri": "post" }, "allow": { "$value": "gate" }, "createdAt": { "$now": true } } },
        ]);
        assert!(problems(&writes, None).is_empty());
        let send = |values: Value| {
            expand(
                &writes,
                values.as_object().unwrap(),
                &[],
                "did:plc:me",
                "t",
                tids(),
            )
            .unwrap()
        };
        let plain = send(json!({ "text": "hi" }));
        assert_eq!(plain.len(), 1);
        assert_eq!(plain[0].record, json!({ "text": "hi", "createdAt": "t" }));
        let quote = json!({ "uri": "at://did:plc:a/app.bsky.feed.post/1", "cid": "bafy" });
        let both = send(
            json!({ "text": "look", "quote": quote, "photos": [{ "blob": { "ref": "a" }, "alt": "" }], "gate": [] }),
        );
        assert_eq!(
            both[0].record["embed"]["$type"],
            "app.bsky.embed.recordWithMedia"
        );
        assert_eq!(
            both[0].record["embed"]["media"]["images"][0]["image"],
            json!({ "ref": "a" })
        );
        // Nobody may reply (an empty allow is a value), the gate keyed as its post.
        assert_eq!(both[1].rkey, both[0].rkey);
        assert_eq!(both[1].record["allow"], json!([]));
        assert_eq!(
            both[1].record["post"],
            format!("at://did:plc:me/app.bsky.feed.post/{}", both[0].rkey)
        );
    }

    #[test]
    fn templates_checked() {
        let names = vec!["text".to_string()];
        let bad = json!([
            { "collection": "not an nsid", "record": { "a": { "$item": "x" }, "b": { "$value": "nope" }, "c": { "$uri": "gone" }, "d": { "$oops": 1 } }, "extra": 1 },
        ]);
        assert_eq!(
            problems(&bad, Some(&names)),
            [
                "writes[0].extra: a write has no extra",
                "writes[0].collection: required: an NSID",
                "writes[0].record.a: $item reads an element, within each or $each alone",
                "writes[0].record.b: {\"$value\": path} has the key alone, a path whose first key names a value",
                "writes[0].record.c: {\"$uri\": as} has the key alone, a write's as",
                "writes[0].record.d: $oops: a key starting with $ is $type, or $value's, $item's, $index's, $each's, $when's, $first's, $merge's, $uri's, $rkey's, $stored's, $now's or $facets' alone",
            ]
        );
        assert!(!problems(&json!([]), None).is_empty());
        let too_many: Vec<Value> = (0..=MAX_TEMPLATE)
            .map(|_| json!({ "collection": "a.b.c", "record": { "x": 1 } }))
            .collect();
        assert!(!problems(&Value::Array(too_many), None).is_empty());
        // A record of nothing is refused as sent.
        let empty = json!([{ "collection": "a.b.c", "record": { "x": { "$value": "text" } } }]);
        assert_eq!(
            expand(&empty, &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
            "writes[0]: its record holds nothing"
        );
    }

    /// Each way a write and its record's operators can be wrong, named
    /// where it is.
    #[test]
    fn every_template_problem_named() {
        let names = vec!["text".to_string(), "photos".to_string()];
        let mut deep = json!(1);
        for _ in 0..12 {
            deep = json!({ "a": deep });
        }
        let writes = json!([
            "a write",
            { "collection": "a.b.c", "as": "Bad Name", "each": "nope", "when": [],
              "rkey": { "$rkey": "zzz" }, "record": 1 },
            { "collection": "a.b.c", "whenItem": "x", "record": {
                "$type": 5, "list": [1, "two"], "deep": deep, "i": { "$index": true },
                "n": { "$now": 1 }, "f": { "$facets": 1 }, "e": { "$each": "nope", "value": 1 },
                "w": { "$when": [], "value": 1 }, "fi": { "$first": [1] } } },
            { "collection": "a.b.c", "each": "photos", "record": { "x": { "$item": "a..b" } } },
        ]);
        let mut got = problems(&writes, Some(&names));
        let mut want = vec![
            "writes[0]: must be an object".to_string(),
            "writes[1].as: a name, once among the writes".into(),
            "writes[1].each: names a value given or written".into(),
            "writes[1].when: 1 to 4 names of values".into(),
            "writes[1].rkey: {\"$rkey\": as}, another write's".into(),
            "writes[1].record: required: an object".into(),
            "writes[2].whenItem: a path within each element, with each".into(),
            "writes[2].record.$type: must be a string".into(),
            format!(
                "writes[2].record.deep{}: a template nests at most 12 deep",
                ".a".repeat(11)
            ),
            "writes[2].record.i: {\"$index\": true} alone, within each or $each".into(),
            "writes[2].record.n: {\"$now\": true} has the key $now alone, true".into(),
            "writes[2].record.f: {\"$facets\": key} has the key alone, the field holding the text"
                .into(),
            "writes[2].record.e: {\"$each\": name, \"value\": template}, a value's name".into(),
            "writes[2].record.w: {\"$when\": [names], \"value\": template}, 1 to 4 values' names"
                .into(),
            "writes[2].record.fi: {\"$first\": [templates]} has the key alone, 2 to 4 templates"
                .into(),
            "writes[3].record.x: {\"$item\": path} has the key alone, a path or \".\"".into(),
        ];
        got.sort();
        want.sort();
        assert_eq!(got, want);
        // expand refuses a template with a problem, by its first.
        assert_eq!(
            expand(&json!([1]), &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
            "writes[0]: must be an object"
        );
    }

    /// What is not there left out: an array's elements, a merge's parts
    /// that are not objects, an `$each` of nothing, the at-uri of a write
    /// not made; another write's record key, where one is.
    #[test]
    fn what_is_not_there_left_out() {
        let writes = json!([
            { "as": "post", "collection": "a.b.c", "record": { "x": 1 } },
            { "as": "gate", "when": ["gate"], "collection": "a.b.d", "record": { "x": 1 } },
            { "collection": "a.b.e", "record": {
                "list": [{ "$value": "text" }, { "$value": "missing" }, 3],
                "merged": { "$merge": [{ "$value": "text" }, { "a": 1 }] },
                "each": { "$each": "missing", "value": 1 },
                "gate": { "$uri": "gate" },
                "key": { "$rkey": "post" } } },
            { "each": "tags", "whenItem": ".", "collection": "a.b.f", "record": { "tag": { "$item": "." } } },
        ]);
        assert!(problems(&writes, None).is_empty());
        // An element that is null is no element: none made for it.
        let values = json!({ "text": "hi", "tags": ["a", null] });
        let made = expand(
            &writes,
            values.as_object().unwrap(),
            &[],
            "did:plc:me",
            "t",
            tids(),
        )
        .unwrap();
        assert_eq!(made.len(), 3);
        assert_eq!(
            made[1].record,
            json!({ "list": ["hi", 3], "merged": { "a": 1 }, "key": made[0].rkey })
        );
        assert_eq!(made[2].record, json!({ "tag": "a" }));
    }

    #[test]
    fn sends_held_to_their_bounds() {
        // More records than one send makes.
        let writes = json!([{ "each": "photos", "collection": "a.b.c", "record": { "i": { "$index": true } } }]);
        let photos: Vec<Value> = (0..=MAX_WRITES).map(|i| json!(i)).collect();
        let values = json!({ "photos": photos });
        assert_eq!(
            expand(
                &writes,
                values.as_object().unwrap(),
                &[],
                "did:plc:me",
                "t",
                tids()
            )
            .unwrap_err(),
            "33 records, more than the 32 one send makes"
        );
        // A key shared with a write not made.
        let writes = json!([
            { "as": "post", "when": ["gate"], "collection": "a.b.c", "record": { "x": 1 } },
            { "rkey": { "$rkey": "post" }, "collection": "a.b.d", "record": { "y": 1 } },
        ]);
        assert_eq!(
            expand(&writes, &Map::new(), &[], "did:plc:me", "t", tids()).unwrap_err(),
            "writes[1].rkey: no record of writes[0] to share a key with"
        );
    }

    /// Grain's profile, edited: one record of its own key, `self`,
    /// replacing the one stored; its picture kept where no new one is
    /// picked, its description taken out where it was cleared, what the
    /// form does not name kept; created where there is none yet.
    #[test]
    fn a_profile_updated_over_its_stored_record() {
        let writes = json!([{ "collection": "social.grain.actor.profile", "update": "self", "record": {
            "displayName": { "$value": "name" },
            "description": { "$value": "description" },
            "avatar": { "$first": [{ "$value": "avatar.0.blob" }, { "$stored": "avatar" }] },
            "createdAt": { "$first": [{ "$stored": "createdAt" }, { "$now": true }] } } }]);
        let names = vec!["name".into(), "description".into(), "avatar".into()];
        assert_eq!(problems(&writes, Some(&names)), Vec::<String>::new());
        assert_eq!(
            updated(&writes, &Map::new()).unwrap(),
            [Some(("social.grain.actor.profile".into(), "self".into()))]
        );
        let old = json!({ "$type": "blob", "ref": { "$link": "old" }, "mimeType": "image/jpeg", "size": 9 });
        let stored = json!({ "$type": "social.grain.actor.profile", "displayName": "Ana",
            "description": "photos", "avatar": old, "createdAt": "2025-01-01T00:00:00.000Z", "pronouns": "she/her" });
        let send = |values: Value, stored: Option<Value>| {
            let made = expand(
                &writes,
                values.as_object().unwrap(),
                &[stored],
                "did:plc:me",
                "t",
                tids(),
            )
            .unwrap();
            assert_eq!((made.len(), made[0].rkey.as_str()), (1, "self"), "{made:?}");
            let update = made[0].update.clone().unwrap();
            let replaces = update.stored.is_some();
            (update.over(made[0].record.clone()), replaces)
        };
        // A new name, the description cleared, no new picture: the stored
        // one's blob ref kept, and what the form does not name.
        let (written, replaces) = send(json!({ "name": "Ana B" }), Some(stored.clone()));
        assert!(replaces);
        assert_eq!(
            written,
            json!({ "$type": "social.grain.actor.profile", "displayName": "Ana B", "avatar": old,
                "createdAt": "2025-01-01T00:00:00.000Z", "pronouns": "she/her" })
        );
        // A new picture replaces it.
        let new = json!({ "$type": "blob", "ref": { "$link": "new" }, "mimeType": "image/jpeg", "size": 7 });
        let (written, _) = send(
            json!({ "name": "Ana", "avatar": [{ "blob": new, "alt": "" }] }),
            Some(stored),
        );
        assert_eq!(written["avatar"], new);
        // None stored yet: created, now.
        let (written, replaces) = send(json!({ "description": "hi" }), None);
        assert!(!replaces);
        assert_eq!(written, json!({ "description": "hi", "createdAt": "t" }));
        // A write that is no update reads nothing; one with a problem is refused.
        let both = json!([
            { "collection": "a.b.c", "record": { "x": 1 } },
            { "collection": "a.b.d", "update": "self", "record": { "y": { "$stored": "y" } } },
        ]);
        assert_eq!(
            updated(&both, &Map::new()).unwrap(),
            [None, Some(("a.b.d".into(), "self".into()))]
        );
        assert_eq!(
            updated(&json!([1]), &Map::new()).unwrap_err(),
            "writes[0]: must be an object"
        );
    }

    /// Each way an update and `$stored` can be wrong.
    #[test]
    fn every_update_problem_named() {
        let names = vec!["photos".to_string()];
        let writes = json!([
            { "as": "a", "collection": "a.b.c", "update": true, "record": { "x": 1 } },
            { "collection": "a.b.c", "update": "a/b", "record": { "x": 1 } },
            { "collection": "a.b.c", "each": "photos", "update": "self", "record": { "x": 1 } },
            { "collection": "a.b.c", "rkey": { "$rkey": "a" }, "update": "self", "record": { "x": 1 } },
            { "collection": "a.b.c", "update": "self", "record": { "$merge": [{ "x": 1 }, { "y": 2 }] } },
            { "collection": "a.b.c", "record": { "x": { "$stored": "x" } } },
            { "collection": "a.b.c", "update": "self", "record": { "x": { "$stored": 1 } } },
        ]);
        let update = "the record key of the one record it replaces, or {\"$value\": name} holding it, with no each or rkey";
        assert_eq!(
            problems(&writes, Some(&names)),
            [
                format!("writes[0].update: {update}"),
                format!("writes[1].update: {update}"),
                format!("writes[2].update: {update}"),
                format!("writes[3].update: {update}"),
                "writes[4].record: an update's record names its fields, with no operator at its top".into(),
                "writes[5].record.x: $stored reads the record an update replaces, within an update alone".into(),
                "writes[6].record.x: {\"$stored\": path} has the key alone, a path or \".\"".into(),
            ]
        );
        // A key given: a value's name, alone.
        let given = json!([
            { "collection": "a.b.c", "update": { "$value": "nope" }, "record": { "x": 1 } },
            { "collection": "a.b.c", "update": { "$value": "photos", "x": 1 }, "record": { "x": 1 } },
        ]);
        assert_eq!(
            problems(&given, Some(&names)),
            [
                format!("writes[0].update: {update}"),
                format!("writes[1].update: {update}"),
            ]
        );
    }

    /// A gallery edited: the record key it updates given (`{"$value":
    /// "rkey"}`, the view's `$rkey` of the gallery's uri), read before it
    /// is sent; one that holds no record key, or none, refused.
    #[test]
    fn an_update_whose_key_is_given() {
        let writes = json!([{ "collection": "social.grain.gallery", "update": { "$value": "rkey" }, "record": {
            "title": { "$value": "title" }, "description": { "$value": "description" },
            "facets": { "$facets": "description" }, "updatedAt": { "$now": true } } }]);
        let names = vec!["rkey".into(), "title".into(), "description".into()];
        assert_eq!(problems(&writes, Some(&names)), Vec::<String>::new());
        let values = json!({ "rkey": "3kgallery", "title": "Lisbon" });
        let values = values.as_object().unwrap();
        assert_eq!(
            updated(&writes, values).unwrap(),
            [Some(("social.grain.gallery".into(), "3kgallery".into()))]
        );
        let stored = json!({ "title": "Old", "description": "was", "createdAt": "2025-01-01T00:00:00.000Z",
            "location": { "name": "Lisbon", "value": "8a2a1072b59ffff" } });
        let made = expand(&writes, values, &[Some(stored)], "did:plc:me", "t", tids()).unwrap();
        assert_eq!(made[0].rkey, "3kgallery");
        let update = made[0].update.clone().unwrap();
        // Its title set, its description cleared, its facets left for
        // create, its place and createdAt kept.
        assert_eq!(
            update.over(made[0].record.clone()),
            json!({ "title": "Lisbon", "facets": { "$facets": "description" }, "updatedAt": "t",
                "createdAt": "2025-01-01T00:00:00.000Z", "location": { "name": "Lisbon", "value": "8a2a1072b59ffff" } })
        );
        let refused = "writes[0].update: the value it names holds no record key";
        for values in [json!({ "rkey": "a/b" }), json!({ "rkey": 5 }), json!({})] {
            let values = values.as_object().unwrap();
            assert_eq!(updated(&writes, values).unwrap_err(), refused);
            assert_eq!(
                expand(&writes, values, &[], "did:plc:me", "t", tids()).unwrap_err(),
                refused
            );
        }
    }

    /// A field's `value`, what it opens holding, is a binding, on a text,
    /// a line or photos alone; photos drawn `round` (an avatar) say so with
    /// true or false.
    #[test]
    fn a_fields_value_is_a_binding() {
        let fields = json!([
            { "name": "a", "kind": "text", "max": 10, "value": { "$": "joins.profile.description" } },
            { "name": "b", "kind": "line", "max": 10, "value": { "$": ["x", "y"] } },
            { "name": "c", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "value": { "$": "avatar" }, "round": true },
            { "name": "d", "kind": "line", "max": 10, "value": "Ana" },
            { "name": "e", "kind": "text", "max": 10, "value": { "$": 1 } },
            { "name": "f", "kind": "langs", "value": { "$": "langs" } },
            { "name": "g", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "round": "yes" },
            { "name": "h", "kind": "line", "max": 10, "round": true },
        ]);
        let bad = "a binding {\"$\": path} (a text or line's also {\"$join\": [parts]}), what it opens holding";
        assert_eq!(
            fields_problems(&fields, "f").0,
            [
                format!("f[3].value: {bad}"),
                format!("f[4].value: {bad}"),
                "f[5].value: a langs field takes no value".into(),
                "f[6].round: true or false".into(),
                "f[7].round: a line field takes no round".into(),
            ]
        );
        // A text or line's words joined, strings and bindings; not a photo's.
        let joined = json!([
            { "name": "i", "kind": "text", "max": 10, "value": { "$join": ["@", { "$": "author.handle" }, " "] } },
            { "name": "j", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "value": { "$join": ["a"] } },
            { "name": "k", "kind": "line", "max": 10, "value": { "$join": [1] } },
        ]);
        assert_eq!(
            fields_problems(&joined, "f").0,
            [format!("f[1].value: {bad}"), format!("f[2].value: {bad}")]
        );
    }

    /// A photos field may offer the camera beside the library (`camera`,
    /// true or false, a story's); no other kind takes it.
    #[test]
    fn a_photos_field_offers_the_camera() {
        let fields = json!([
            { "name": "a", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "camera": true },
            { "name": "b", "kind": "photos", "max": 4, "maxBytes": 900000, "maxSide": 1000, "camera": false },
            { "name": "c", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "camera": "rear" },
            { "name": "d", "kind": "line", "max": 10, "camera": true },
        ]);
        assert_eq!(
            fields_problems(&fields, "f").0,
            [
                "f[2].camera: true or false",
                "f[3].camera: a line field takes no camera"
            ]
        );
    }

    /// A place fills itself from a photos field's first located photo
    /// (`from`), where `locate` is not false; `exif` and `locate` are true
    /// or false, or a binding (an account's preference).
    #[test]
    fn a_place_from_photos_and_preferences_bound() {
        let pref = json!({ "$": "joins.prefs.preferences.@photoMetadataPref.includeExif" });
        let fields = json!([
            { "name": "photos", "kind": "photos", "max": 4, "maxBytes": 900000, "maxSide": 1000, "exif": pref },
            { "name": "text", "kind": "text", "max": 10 },
            { "name": "place", "kind": "place", "from": "photos", "locate": { "$": "x" } },
            { "name": "here", "kind": "place", "from": "text", "locate": "yes" },
            { "name": "there", "kind": "place", "locate": true },
            { "name": "more", "kind": "photos", "max": 1, "maxBytes": 900000, "maxSide": 1000, "exif": 1 },
            { "name": "card", "kind": "card", "from": "photos" },
        ]);
        let on = "true or false, or a binding {\"$\": path}, on unless false";
        assert_eq!(
            fields_problems(&fields, "f").0,
            [
                "f[3].from: names a photos field".to_string(),
                format!("f[3].locate: {on}"),
                format!("f[5].exif: {on}"),
                "f[6].from: names a text field".into(),
            ]
        );
    }

    #[test]
    fn every_field_problem_named() {
        assert_eq!(
            fields_problems(&json!("x"), "f"),
            (
                vec!["f: must be an array of 1 to 10 fields".to_string()],
                vec![]
            )
        );
        let fields = json!([
            "x",
            { "name": "Bad", "kind": "text", "max": 10 },
            { "name": "t", "kind": "text", "facets": "yes" },
            { "name": "t", "kind": "line", "max": 5 },
            { "name": "c", "kind": "card", "from": "nope" },
            { "name": "d", "kind": "card" },
            { "name": "ch", "kind": "choice" },
            { "name": "l", "kind": "labels", "options": [] },
            { "name": "p", "kind": "photos", "min": 5, "max": 2 },
            { "name": "s", "kind": "text", "max": 10, "suggest": { "method": "x" } },
        ]);
        let (out, names) = fields_problems(&fields, "f");
        let name = "a name (lowercase letters and digits), once among the fields";
        assert_eq!(
            out,
            [
                "f[0]: must be an object".to_string(),
                format!("f[1].name: {name}"),
                "f[2].facets: true or false".into(),
                format!("f[3].name: {name}"),
                "f[4].from: names a text field".into(),
                "f[5].from: required: the text field whose link it shows".into(),
                "f[6].options: required".into(),
                "f[7].options: 1 to 8 options, each { label, value, only? }".into(),
                "f[8].min: at most max".into(),
                "f[8].maxBytes: required".into(),
                "f[8].maxSide: required".into(),
                "f[9].suggest: { method, service?, param, params? (literals), items, did, handle, name?, avatar? }, paths into its answer".into(),
            ]
        );
        assert_eq!(names, ["t", "c", "d", "ch", "l", "p", "s"]);
    }

    /// The writes of a gallery, a comment and a profile, and of a record
    /// with no bundled lexicon, each property a field's value whole.
    fn limited_writes() -> Value {
        json!([
            { "collection": "social.grain.gallery", "record": { "title": { "$value": "title" }, "description": { "$value": "description" }, "createdAt": { "$now": true } } },
            { "collection": "social.grain.comment", "record": { "text": { "$value": "text" }, "subject": { "$value": "title" } } },
            { "collection": "social.grain.actor.profile", "record": { "displayName": { "$value": "both" } } },
            { "collection": "social.grain.comment", "record": { "text": { "$value": "both" } } },
            { "collection": "com.example.note", "record": { "note": { "$value": "note" } } },
            { "collection": "social.grain.comment", "record": { "$merge": [] } },
        ])
    }

    /// A field's limit is its record's lexicon's: a gallery's title 100
    /// UTF-8 bytes (`maxLength`, no graphemes), a comment's text 300
    /// graphemes and 3000 bytes; written into two, the narrower of each;
    /// into a record with no bundled lexicon, or none, nothing.
    #[test]
    fn a_fields_limit_is_its_records_lexicons() {
        let writes = limited_writes();
        let of = |name: &str| limit(name, &writes);
        let limit = |graphemes, bytes| Limit { graphemes, bytes };
        assert_eq!(of("title"), limit(None, Some(100)));
        assert_eq!(of("description"), limit(None, Some(1000)));
        assert_eq!(of("text"), limit(Some(300), Some(3000)));
        assert_eq!(of("both"), limit(Some(64), Some(640)));
        assert_eq!(of("note"), Limit::default());
        assert_eq!(of("other"), Limit::default());
        assert_eq!(super::limit("text", &Value::Null), Limit::default());
    }

    /// A view's `max` only narrows its lexicon's: one wider than its
    /// graphemes, or than its bytes (a grapheme is a byte at least), is
    /// refused; and a text or line no lexicon limits needs its own.
    #[test]
    fn a_max_only_narrows_the_lexicons() {
        let fields = json!([
            { "name": "title", "kind": "line" },
            { "name": "description", "kind": "text", "max": 1001 },
            { "name": "text", "kind": "text", "max": 301 },
            { "name": "both", "kind": "line", "max": 64 },
            { "name": "note", "kind": "text" },
            { "name": "other", "kind": "text", "max": 50 },
            { "name": "photos", "kind": "photos", "max": 1 },
            { "name": "title", "kind": "line", "max": 100 },
            { "name": "note", "kind": "line" },
            { "name": "other", "kind": "line", "max": 20 },
        ]);
        assert_eq!(
            limit_problems(&fields, &limited_writes()),
            [
                "fields[1].max: at most its record's lexicon's 1000 bytes",
                "fields[2].max: at most its record's lexicon's 300 graphemes",
                "fields[4].max: required: no lexicon of a record it is written into limits it",
                "fields[8].max: required: no lexicon of a record it is written into limits it",
            ]
        );
        assert!(limit_problems(&json!("x"), &Value::Null).is_empty());
    }

    /// A field as the form asks it carries its limits: `max`, graphemes,
    /// the view's narrowed by the lexicon's, and `maxBytes`, the lexicon's
    /// UTF-8 bytes; a field of another kind as it was.
    #[test]
    fn a_field_carries_its_limits() {
        let writes = limited_writes();
        let made = |f: Value| limited(f, &writes);
        assert_eq!(
            made(json!({ "name": "title", "kind": "line" })),
            json!({ "name": "title", "kind": "line", "maxBytes": 100 })
        );
        assert_eq!(
            made(json!({ "name": "text", "kind": "text" })),
            json!({ "name": "text", "kind": "text", "max": 300, "maxBytes": 3000 })
        );
        assert_eq!(
            made(json!({ "name": "text", "kind": "text", "max": 200 })),
            json!({ "name": "text", "kind": "text", "max": 200, "maxBytes": 3000 })
        );
        assert_eq!(
            made(json!({ "name": "note", "kind": "text", "max": 10 })),
            json!({ "name": "note", "kind": "text", "max": 10 })
        );
        let photos = json!({ "name": "photos", "kind": "photos", "max": 4, "maxBytes": 900000 });
        assert_eq!(made(photos.clone()), photos);
    }
}