use ingraph_codegen::{
engine::{DeclaredLane, Engine, EngineKind, FieldEngines, Road},
extension::{self, ColumnExtension, Extension, ExtensionSource},
index::{
self, Dedup, Elected, ElectionBackend, ElectionLabel, Field, FieldNumbers, Fold, IndexBackend,
IndexGraphql, IndexModel, IndexRename, Labelled, Numbers, Projected, RenamePiece, Upstream,
},
model::{Conversion, GraphqlKind, borrowed_key},
prefix::EmissionPrefix,
prelude::*,
};
use quote::ToTokens as _;
use crate::{
alias,
attribute::{self, named, set_once},
column,
errors::Errors,
parse::owns_one_storage,
value,
};
#[cfg(test)]
mod artifacts;
#[cfg(test)]
mod artifacts_rider;
#[cfg(test)]
mod asked;
#[cfg(test)]
mod engine_types;
#[cfg(test)]
mod engines;
#[cfg(test)]
mod lanes;
#[cfg(test)]
mod leaderboard;
#[cfg(test)]
mod rename_seats;
#[cfg(test)]
mod renames;
#[cfg(test)]
mod roads;
#[cfg(test)]
mod searchable_road;
#[cfg(test)]
mod seats;
#[cfg(test)]
mod skin_prefix;
#[cfg(test)]
mod skins;
#[cfg(test)]
mod subscribe_word;
#[cfg(test)]
mod tests;
pub(crate) fn parse(
input: &syn::DeriveInput,
arguments: &[syn::Attribute],
kind: NodeKind,
) -> syn::Result<IndexModel> {
let index = &input.ident;
let mut errors = Errors::default();
crate::host::refuse_a_moved_option_block(&input.attrs, &mut errors);
let Head {
krate,
block,
dedup,
stores,
extension,
data,
graphql,
rename,
slot,
numbers,
keys,
subscribe,
} = options(arguments, kind, &mut errors);
concrete(&input.generics, kind, &mut errors);
let fields = match named_fields(input, kind) {
Ok(fields) => fields,
Err(terminal) => return Err(errors.seal(terminal)),
};
if fields.named.is_empty() {
errors.push(syn::Error::new_spanned(
index,
format!(
"{article} {noun} with no fields indexes nothing — it holds one document per upstream \
message, and a document with no field is that message's key repeated, which the upstream \
already answers",
article = kind.article(),
noun = kind.noun(),
),
));
}
let mut columns: Vec<Column> = Vec::new();
let mut roles: Vec<Role> = Vec::new();
for field in &fields.named {
let Some(name) = field.ident.clone() else {
continue;
};
if name == borrowed_key(&EmissionPrefix::default()) {
errors.push(syn::Error::new_spanned(
&name,
format!(
"this declaration already carries a storage macro's injected key, so a second storage \
macro is being asked to index a document that has one. {}",
owns_one_storage(kind),
),
));
continue;
}
column::refuse_framework_namespace(&alias::Fence::default(), &name, &mut errors);
if name == "node" {
errors.push(syn::Error::new_spanned(
&name,
format!(
"`node` cannot be {article} {noun}'s field — inside `upstream(…)` it names the UPSTREAM, \
so `node = \"…\"` there is already spoken for and this field has no entry left to be \
read out of. Rename the field",
article = kind.article(),
noun = kind.noun(),
),
));
}
let (project, mut role) = markers(&field.attrs, &name, kind, &mut errors);
engines_of(&name, &mut role, kind, &mut errors);
columns.push(Column {
project,
ty: field.ty.clone(),
source: name.clone(),
name,
});
roles.push(role);
}
let Some(block) = block else {
return Err(errors.seal(syn::Error::new_spanned(
index,
format!(
"{article} {noun} draws its documents from an upstream, and `upstream(…)` is where it names \
one — `upstream(node = \"path::To::Upstream\", <field> = \"<upstream field>\", …)`. It is \
not optional: a derived index mints no id of its own, so without an upstream it has no key \
to be addressed by either",
article = kind.article(),
noun = kind.noun(),
),
)));
};
let projections = projections(&block, &columns, kind, index, &mut errors);
let Some(node) = block.node else {
return Err(errors.seal(syn::Error::new_spanned(
&block.at,
"`upstream(…)` needs `node = \"path::To::Upstream\"` — the projections beside it say which of \
the upstream's fields this declaration reads, and without the upstream there is nothing for \
them to be read out of",
)));
};
let Elections {
embeddings,
labelled,
searchable,
engines,
numbers: field_numbers,
} = elect(&columns, &roles, kind, index, &mut errors);
let model = IndexModel {
prefix: EmissionPrefix::default(),
index: index.clone(),
kind,
vis: input.vis.clone(),
krate,
source: Upstream { node, projections },
embeddings,
labelled,
searchable,
engines,
stores,
extension,
data,
graphql,
numbers,
field_numbers,
rename,
slot,
keys,
subscribe,
dedup: dedup.unwrap_or_else(|| {
if matches!(kind, NodeKind::Fulltext | NodeKind::Vector) {
errors.push(syn::Error::new_spanned(index, DEDUP_IS_MANDATORY));
}
Dedup::Hash
}),
fields: columns,
};
emitted_methods(&model, &mut errors);
emitted_types(&model, &mut errors);
named_mints(&model, &mut errors);
written_seats(&model, &mut errors);
spent_guards(&model, &mut errors);
errors.into_result(model)
}
fn spent_guards(model: &IndexModel, errors: &mut Errors) {
if model.numbers.streams.is_none()
|| model
.embeddings
.iter()
.any(|elected| elected.label.is_set())
{
return;
}
let index = &model.index;
errors.push(syn::Error::new_spanned(
index,
format!(
"`{index}` writes `{STREAMS} = N` at its head and elects no `list(embedding)` field — the \
guard bounds how many query vectors one request may ask a SET election's `_with` road with, \
and this declaration has no such road for it to stand on. Label the election that carries \
several embeddings `list(embedding)`, or take the word off. What bounds every road a \
declaration does have is `{CEILING} = N`, which caps the DEPTH a request may ask for"
),
));
}
fn written_seats(model: &IndexModel, errors: &mut Errors) {
for written in &model.field_numbers {
let Some(skin) = written.skin(GraphqlKind::AsyncGraphql) else {
continue;
};
for road in Field::ALL {
let (Some(word), Some(why)) = (skin.road(road), model.unmounted(&written.field, road)) else {
continue;
};
errors.push(syn::Error::new_spanned(
word,
format!(
"`{road}` names {what} for `{field}`, and this election publishes none: {why}",
road = road.as_str(),
what = road.what(),
field = written.field,
),
));
}
if let (Some(word), Some(why)) = (
skin.engines.as_ref(),
model.unminted_engines(&written.field),
) {
errors.push(syn::Error::new_spanned(
word,
format!(
"`{ENGINES}` names the per-leg product `{field}` would state one floor in, and this \
election mints none: {why}",
field = written.field,
),
));
}
}
}
struct Head {
krate: syn::Path,
block: Option<UpstreamBlock>,
dedup: Option<Dedup>,
stores: Vec<Engine>,
extension: Option<Extension>,
data: bool,
graphql: Option<IndexGraphql>,
rename: Option<IndexRename>,
slot: Option<syn::LitStr>,
numbers: Numbers,
keys: bool,
subscribe: bool,
}
const STORES_NO_ROWS: &str = "a derived index stores no rows — a store word names the DATABASE rows \
land in, and a node whose messages land in one is a `record`. This \
node's own storage is its ENGINES, and they are per FIELD";
fn options(attrs: &[syn::Attribute], kind: NodeKind, errors: &mut Errors) -> Head {
const CLAIMED: [(&str, &str); 10] = [
(
"key",
"a derived index does not name its key type, because it declares none — its key is the \
upstream's, carried whole",
),
(
"lineage",
"a derived index does not declare a lineage — a document descends from the message it was \
derived from, so the path to the root is the upstream's and is bound from it",
),
(
"persist",
"a derived index stores no rows — `persist(…)` was the ROW storage's old wrapper, and it is \
gone besides: a node whose messages land in a database is a `record`, and a record names its \
stores BARE",
),
("sqlite", STORES_NO_ROWS),
("postgres", STORES_NO_ROWS),
("mysql", STORES_NO_ROWS),
("mongo", STORES_NO_ROWS),
("table", STORES_NO_ROWS),
(
"derived",
"a derived index declares no reverse positions — a reverse position is another record \
pointing back at this one's rows, and this node has none",
),
(
"implements",
"an interface's members are NODES WITH ROWS — a membership is proved by a stored row \
answering the contract's columns, and a derived index has no row of its own to answer with",
),
];
let mut krate = None;
let mut block: Option<UpstreamBlock> = None;
let mut dedup: Option<Dedup> = None;
let mut stores: Vec<Engine> = Vec::new();
let mut extension: Option<Extension> = None;
let mut graphql: Option<IndexGraphql> = None;
let mut numbers = Numbers::default();
let mut graphql_at: Option<syn::Path> = None;
let mut rename: Option<IndexRename> = None;
let mut rename_at: Option<syn::Path> = None;
let mut slot: Option<syn::LitStr> = None;
let mut data = false;
let mut keys = false;
let mut subscribe = false;
attribute::walk(attrs, errors, |meta, errors| {
if meta.path.is_ident("crate") {
match value::parse_literal::<syn::Path>(
&meta,
"`#[ingraph(crate = \"…\")]` must be a path to the `ingraph` crate, in a string literal",
) {
Ok(path) => set_once(
&mut krate,
path,
&meta.path,
"`crate` is declared more than once — one declaration names one crate",
errors,
),
Err(e) => errors.push(e),
}
return Ok(());
}
if meta.path.is_ident("upstream") {
let at = meta.path.clone();
if block.is_some() {
errors.push(named(
&meta,
format!(
"a second `upstream(…)` is the MULTI-UPSTREAM shape and that grammar has not arrived — with \
two upstreams a document came from one or the other, so the key this {noun} carries \
becomes an enum over both upstreams' keys and the field holding it changes type. One \
upstream is one `upstream(…)`",
noun = kind.noun(),
),
));
return Ok(());
}
let mut node = None;
let mut entries: Vec<UpstreamEntry> = Vec::new();
let walked = attribute::options(&meta, |inner| {
source_entry(&inner, &mut node, &mut entries, errors)
});
block = Some(UpstreamBlock { node, entries, at });
return walked;
}
if meta.path.is_ident("dedup") {
if !matches!(kind, NodeKind::Fulltext | NodeKind::Vector) {
errors.push(named(
&meta,
format!(
"`dedup(…)` is a RETRIEVE's word and {article} {noun} does not retrieve — dedup \
collapses an engine's hit stream by key, and this node answers an address rather than \
a ranking",
article = kind.article(),
noun = kind.noun(),
),
));
return Ok(());
}
if dedup.is_some() {
errors.push(syn::Error::new_spanned(
&meta.path,
"`dedup` is declared more than once — one index dedupes one way",
));
return Ok(());
}
return attribute::options(&meta, |inner| {
dedup_word(&inner, &mut dedup, errors);
Ok(())
});
}
if meta.path.is_ident(SLOT) {
if kind != NodeKind::Blob {
errors.push(named(&meta, slot_wrong_grain(kind)));
return Ok(());
}
if slot.is_some() {
errors.push(syn::Error::new_spanned(
&meta.path,
"`slot` is declared more than once — one family's objects live in ONE place, and a second \
name would be a second answer to a question with one",
));
attribute::skip_entry(&meta);
return Ok(());
}
match value::literal(&meta, SLOT_SHAPE) {
Ok(name) => {
refuse_a_malformed_slot(&name, errors);
slot = Some(name);
}
Err(e) => errors.push(e),
}
return Ok(());
}
if meta.path.is_ident(RENAME) {
if kind == NodeKind::Blob {
errors.push(named(&meta, BLOB_MINTS_NO_TYPE.to_owned()));
return Ok(());
}
if rename_at.is_some() {
errors.push(named(
&meta,
"`rename` is declared more than once — the two forms are ONE word: `rename = \"…\"` \
re-bases the whole minted family and `rename(<piece> = \"…\")` names individual mints, \
so writing both says the family is called two things"
.to_owned(),
));
return Ok(());
}
rename_at = Some(meta.path.clone());
return rename_word(&meta, &mut rename, kind, errors);
}
if meta.path.is_ident(FIRST) {
errors.push(named(&meta, first_is_the_skins_word(kind)));
return Ok(());
}
if let Some(walked) = numbers_word(&meta, &mut numbers, "this declaration's head", errors) {
if kind == NodeKind::Blob {
numbers = Numbers::default();
errors.push(named(
&meta,
blob_takes_no_number(&meta.path.to_token_stream().to_string()),
));
}
return walked;
}
if meta.path.is_ident(GRAPHQL) {
if kind == NodeKind::Blob {
errors.push(named(&meta, BLOB_MINTS_NO_WIRE.to_owned()));
return Ok(());
}
if graphql_at.is_some() {
errors.push(syn::Error::new_spanned(
&meta.path,
"`graphql(…)` is declared more than once — one block holds every backend, and a second \
one could only repeat or contradict the first. Two skins are two WORDS inside one block: \
`graphql(async_graphql, …)`",
));
attribute::skip_entry(&meta);
return Ok(());
}
graphql_at = Some(meta.path.clone());
return graphql_word(&meta, &mut graphql, errors);
}
if meta.path.is_ident("embedding") {
errors.push(named(&meta, retired_head_word(kind)));
return Ok(());
}
if meta.path.is_ident(KEYS_TIER) {
if kind == NodeKind::Blob {
errors.push(named(
&meta,
format!(
"{article} {noun} answers an ADDRESS rather than a ranking, so it mounts no tier pair \
for `{KEYS_TIER}` to narrow — the word says a dressed election publishes addresses \
and not hydrated entities, and every answer here is an address already",
article = kind.article(),
noun = kind.noun(),
),
));
attribute::skip_entry(&meta);
return Ok(());
}
if attribute::has_value(&meta) || attribute::has_block(&meta) {
errors.push(named(
&meta,
format!(
"`{KEYS_TIER}` is a BARE word — it states which RUNG this declaration's upstream is \
on, and a rung has no knob. What it would carry is already decided elsewhere: WHICH \
fields are elected is each field's own marker, and WHAT a key looks like is the \
upstream's key type"
),
));
return Ok(());
}
if keys {
errors.push(syn::Error::new_spanned(
&meta.path,
format!(
"`{KEYS_TIER}` is declared more than once — the word is PRESENCE, so the second one \
says exactly what the first already said"
),
));
attribute::skip_entry(&meta);
return Ok(());
}
keys = true;
return Ok(());
}
if meta.path.is_ident(SUBSCRIBE) {
if kind != NodeKind::Fulltext {
errors.push(named(&meta, subscribe_wrong_kind(kind)));
attribute::skip_entry(&meta);
return Ok(());
}
if attribute::has_value(&meta) {
errors.push(named(
&meta,
format!(
"`{SUBSCRIBE}` is a BARE word here, and the difference from every other kind's is the \
one thing worth knowing about it: an operator's and a record's `{SUBSCRIBE} = \"…\"` \
NAMES the upstream, and {article} {noun} already named one in `upstream(…)` — where \
the edge and the projection are ONE entry, because every field of a document is read \
out of the message it was derived from. So there is no edge left for a value to name, \
and what the bare word says is the half `upstream(…)` does not: that this declaration \
LAUNCHES",
article = kind.article(),
noun = kind.noun(),
),
));
return Ok(());
}
if attribute::has_block(&meta) {
errors.push(named(
&meta,
format!(
"`{SUBSCRIBE}` carries no block here — the per-upstream words an operator writes inside \
one (`channel`, `changes(<db>)`, `out`, `key`, `notify`) all describe an edge, and \
this declaration's edge is `upstream(…)`'s. They are recorded and not built: a \
subscribing index takes its edge at the framework's own depth and receives the \
upstream's message whole, which is what its projections read"
),
));
return Ok(());
}
if subscribe {
errors.push(syn::Error::new_spanned(
&meta.path,
format!(
"`{SUBSCRIBE}` is declared more than once — the word is PRESENCE, so the second one \
says exactly what the first already said"
),
));
attribute::skip_entry(&meta);
return Ok(());
}
subscribe = true;
return Ok(());
}
if meta.path.is_ident(extension::EXTENSION) {
if kind != NodeKind::Blob {
errors.push(named(&meta, extension::wrong_kind(kind)));
return Ok(());
}
if extension.is_some() {
errors.push(syn::Error::new_spanned(
&meta.path,
"`extension` is declared more than once — one family ends its addresses ONE way, and a \
second word would be a second answer to a question with one",
));
attribute::skip_entry(&meta);
return Ok(());
}
extension_word(&meta, &mut extension, errors);
return Ok(());
}
if meta.path.is_ident(index::DATA) {
if kind != NodeKind::Blob {
errors.push(named(&meta, index::data_wrong_kind(kind)));
return Ok(());
}
if data {
errors.push(syn::Error::new_spanned(
&meta.path,
"`data` is declared more than once — the word is PRESENCE, so the second one says exactly \
what the first already said. There is no stronger form of it to reach for: whether this \
family's bytes may ride beside its address is one fact, and it is either declared or it \
is not",
));
attribute::skip_entry(&meta);
return Ok(());
}
if attribute::has_value(&meta) || attribute::has_block(&meta) {
errors.push(named(
&meta,
"`data` is a BARE word — write it and this family's object may be served inline beside \
its address, leave it out and the address is the whole of the answer. There is nothing \
for it to carry: what an address ENDS with is `extension`'s question and WHERE the \
object is stored is the store word's, so *the bytes may ride along* has no knob left \
inside it"
.to_owned(),
));
return Ok(());
}
data = true;
return Ok(());
}
if kind == NodeKind::Blob && meta.path.is_ident(FANOUT) {
errors.push(named(
&meta,
"`fanout` writes one document to EVERY declared engine at once so that each engine's \
ranking enters fusion as separate evidence — and an artifact family answers an ADDRESS \
rather than a ranking, so there is no second ranking for a second copy to contribute. \
Storing one artifact in two places is a real want and a different feature; it is recorded \
and not built. Several engines here are declared PORTABILITY, and the deployment picks one"
.to_owned(),
));
attribute::skip_entry(&meta);
return Ok(());
}
if kind
.storage_block()
.is_some_and(|own| meta.path.is_ident(own))
{
errors.push(named(
&meta,
format!(
"`{block}(…)` is not where {article} {noun} names its ENGINES — a slot is one FIELD in \
one engine, so the engines are written on the field beside its election: \
`#[ingraph({marker}, <engine>, <engine>(<knob> = …))]`. A block here could only name \
them for the whole declaration, which is a grain coarser than the storage actually is",
block = kind.as_str(),
article = kind.article(),
noun = kind.noun(),
marker = kind.election().unwrap_or("…"),
),
));
return Ok(());
}
for other in [NodeKind::Fulltext, NodeKind::Vector, NodeKind::Blob] {
if other != kind && meta.path.is_ident(other.as_str()) {
errors.push(named(
&meta,
format!(
"{article} {noun} owns no {held} — one is its OWN node, declared with the `{other}` \
macro over the same upstream. {law}",
article = kind.article(),
noun = kind.noun(),
held = other.noun(),
other = other.as_str(),
law = owns_one_storage(kind),
),
));
return Ok(());
}
}
for (family, why) in CLAIMED {
if meta.path.is_ident(family) {
errors.push(named(&meta, format!("{why}. {}", owns_one_storage(kind))));
return Ok(());
}
}
for word in [
ingraph_codegen::aggregate::GROUP,
ingraph_codegen::aggregate::MEASURE,
] {
if meta.path.is_ident(word) {
errors.push(named(
&meta,
crate::aggregate::wrong_kind(word, kind, crate::aggregate::Written::AtTheHead),
));
return Ok(());
}
}
if kind == NodeKind::Blob {
match meta.path.get_ident().cloned() {
Some(word) => blob_engine(&meta, word, &mut stores, errors),
None => errors.push(attribute::unknown(
&meta,
"an engine is named by ONE word — `fs`, `s3` — and a path with several segments names no \
engine. The word is bare because it is a NAME the deployment binds: a path written on a \
declaration would bind it here, where the store a build actually compiled is not knowable",
&[],
)),
}
return Ok(());
}
errors.push(attribute::unknown(
&meta,
&format!(
"unknown entry on {article} {noun} — it takes `upstream(…)`{retrieves} and `crate = \"…\"`, \
every other block naming something a node with no rows and no id of its own does not have. \
WHICH of its fields it indexes is not written here at all, and neither is WHERE they are \
stored: both are markers on the field itself{elects}",
article = kind.article(),
noun = kind.noun(),
retrieves = match kind {
NodeKind::Fulltext =>
", `dedup(…)`, `graphql(<backend>)`, `keys`, `subscribe`, `limit = N`, `depth = N`, \
`ceiling = N`, `streams = N`",
NodeKind::Vector =>
", `dedup(…)`, `graphql(<backend>)`, `keys`, `limit = N`, `depth = N`, `ceiling = N`, \
`streams = N`",
_ => "",
},
elects = match kind.election() {
Some(marker) => format!(", `#[ingraph({marker}, <engine>)]`"),
None => String::new(),
},
),
&match kind {
NodeKind::Fulltext => {
let mut words = vec!["upstream", "dedup", GRAPHQL, KEYS_TIER, SUBSCRIBE, "crate"];
words.extend(NUMBER_WORDS);
words
}
NodeKind::Vector => {
let mut words = vec!["upstream", "dedup", GRAPHQL, KEYS_TIER, "crate"];
words.extend(NUMBER_WORDS);
words
}
_ => vec!["upstream", "crate"],
},
));
Ok(())
});
if let Some(Extension::Column(column)) = &extension {
extension_fences(column, errors);
}
Head {
numbers,
krate: krate.unwrap_or_else(|| syn::parse_quote!(::ingraph)),
block,
dedup,
stores,
extension,
data,
graphql,
rename,
slot,
keys,
subscribe,
}
}
pub(crate) const NUMBER_WORDS: [&str; 4] = [LIMIT, DEPTH, CEILING, STREAMS];
pub(crate) const LIMIT: &str = "limit";
pub(crate) const DEPTH: &str = "depth";
const CEILING: &str = "ceiling";
const STREAMS: &str = "streams";
const FIRST: &str = "first";
const KEYS_TIER: &str = "keys";
const SUBSCRIBE: &str = "subscribe";
fn subscribe_wrong_kind(kind: NodeKind) -> String {
format!(
"`{SUBSCRIBE}` makes a declaration a LAUNCHABLE NODE — one that receives its upstream's \
messages over an edge and fills its own corpora — and {article} {noun} does not have that road \
yet. It is deferred rather than absent: the road is one `FulltextLane`-shaped seam per storage \
family, and the full-text one landed first because it is the family with a live engine behind \
it. Until this kind has its own, the corpora are filled by a hand that holds the mount",
article = kind.article(),
noun = kind.noun(),
)
}
const FIELD_NOUN: &str = "field";
fn road_block(
meta: &syn::meta::ParseNestedMeta<'_>,
slot: &mut Option<syn::LitStr>,
road: Field,
field: &syn::Ident,
errors: &mut Errors,
) -> syn::Result<()> {
let word = road.as_str();
let walked = attribute::named_block(meta, slot, word, FIELD_NOUN, errors, |option| {
value::literal(
option,
&format!(
"`{word}(rename = \"…\")` is what this backend calls {what} for `{field}`, in a string \
literal — `{word}(rename = \"clipNeighbours\")`. It names a field in the ROOT's namespace \
and nothing in Rust, so it is carried verbatim",
what = road.what(),
),
)
});
if let Some(written) = slot.as_ref() {
crate::wire::refuse_invalid_name(&written.value(), written, errors);
}
walked
}
pub(crate) fn number(
meta: &syn::meta::ParseNestedMeta<'_>,
slot: &mut Option<core::num::NonZeroU32>,
word: &str,
scope: &str,
errors: &mut Errors,
) -> syn::Result<()> {
let written = match value::integer(meta, &number_shape(word)) {
Ok(written) => written,
Err(refusal) => {
errors.push(refusal);
return Ok(());
}
};
let Ok(count) = written.base10_parse::<u32>() else {
errors.push(syn::Error::new_spanned(
&written,
format!(
"`{word}` is past what this grammar carries a declared number at — the width is `u32`, \
which is the width `route_depth` already takes a wall at, and a number a person types is \
not an address space"
),
));
return Ok(());
};
let Some(count) = core::num::NonZeroU32::new(count) else {
errors.push(syn::Error::new_spanned(&written, number_zero(word)));
return Ok(());
};
set_once(
slot,
count,
&meta.path,
&format!("`{word}` is declared more than once in {scope} — one number"),
errors,
);
Ok(())
}
fn number_shape(word: &str) -> String {
format!("`{word}` is a COUNT, as a plain integer — `{word} = 20`")
}
fn number_zero(word: &str) -> String {
match word {
CEILING => format!(
"`{CEILING} = 0` is a wall no request can get through — a ceiling CAPS a fetch, so zero would \
refuse every read this declaration has rather than protect them. A deployment that wants no \
reads removes the doors; leaving the word out is the author's informed openness"
),
STREAMS => format!(
"`{STREAMS} = 0` admits no query vectors at all, which refuses every question the `_with` \
road has rather than bounding them: a set query with no query vectors asks nothing, so a \
guard of zero is a road that answers nobody. The smallest guard that admits a question is \
`{STREAMS} = 1`; leaving the word out is the author's informed openness"
),
FIRST => format!(
"`{FIRST} = 0` would publish an SDL default of nothing — a schema whose page size promises no \
rows. The wire's `first: 0` is a REQUEST and answers `[]` without touching a door; a DEFAULT \
of zero is a declaration saying every unasked query is empty"
),
_ => format!(
"`{word} = 0` asks for an answer with no rows, which this family made unrepresentable rather \
than forkable — every door's number is a `NonZeroUsize`. What a caller who wants nothing \
does is not ask"
),
}
}
fn numbers_word(
meta: &syn::meta::ParseNestedMeta<'_>,
numbers: &mut Numbers,
scope: &str,
errors: &mut Errors,
) -> Option<syn::Result<()>> {
for (word, slot) in [
(LIMIT, &mut numbers.limit),
(DEPTH, &mut numbers.depth),
(CEILING, &mut numbers.ceiling),
(STREAMS, &mut numbers.streams),
] {
if meta.path.is_ident(word) {
return Some(number(meta, slot, word, scope, errors));
}
}
None
}
fn first_is_the_skins_word(kind: NodeKind) -> String {
match kind {
NodeKind::Blob => blob_takes_no_number(FIRST),
_ => format!(
"`{FIRST}` is GRAPHQL's word for how many, so it is written inside the skin that publishes \
it — `{GRAPHQL}(<backend>({FIRST} = N))`, at this head or on an election. What the head \
takes in Rust vocabulary is `{limit}`, which is the same number a door is called with, and \
`{depth}` beside it",
limit = NUMBER_WORDS[0],
depth = NUMBER_WORDS[1],
),
}
}
fn blob_takes_no_number(word: &str) -> String {
format!(
"`{word}` is a number about RETRIEVAL — how many rows a door answers, how deep a fold fetches, \
and how much of either a request may ask for. An artifact family retrieves nothing: it answers \
the ADDRESS of the object stored under a key it was handed, so there is no ranking for a \
number to cut. The word opens on `vector` and `fulltext` declarations, at the head and on an \
election"
)
}
fn election_skins(
meta: &syn::meta::ParseNestedMeta<'_>,
skins: &mut Vec<ElectionBackend>,
field: &syn::Ident,
errors: &mut Errors,
) -> syn::Result<()> {
let walked = attribute::options(meta, |inner| {
let Some(kind) = crate::parse::graphql_kind(&inner.path) else {
errors.push(attribute::unknown(
&inner,
&format!(
"unknown backend in `{GRAPHQL}(…)` on `{field}` — this framework renders through {list}, \
and a word naming none of them names no skin. The block holds WORDS rather than knobs \
for the head block's reason: each one adds one backend's own description over the same \
Rust election",
list = backend_list(),
),
&GraphqlKind::ALL.map(GraphqlKind::as_str),
));
return Ok(());
};
if skins.iter().any(|backend| backend.kind == kind) {
errors.push(syn::Error::new_spanned(
&inner.path,
format!(
"`{kind}` is declared more than once in `{GRAPHQL}(…)` on `{field}` — one block per \
backend, because a backend has ONE skin and a second word could only re-describe it",
kind = kind.as_str(),
),
));
attribute::skip_entry(&inner);
return Ok(());
}
let mut backend = ElectionBackend::of(kind);
let walked = attribute::options(&inner, |entry| {
if entry.path.is_ident(FIRST) {
return number(
&entry,
&mut backend.first,
FIRST,
&format!("`{field}`'s backend block"),
errors,
);
}
for (word, seat) in [
(QUESTION, &mut backend.question),
(ENGINES, &mut backend.engines),
(SIGHTING, &mut backend.sighting),
(FUSED_KEY_MATCH, &mut backend.fused_key_match),
] {
if entry.path.is_ident(word) {
let walked = attribute::sdl_name_block(&entry, seat, word, errors);
if let Some(name) = seat.as_ref() {
crate::wire::refuse_invalid_name(&name.value(), name, errors);
}
return walked;
}
}
for (road, seat) in [
(Field::Keys, &mut backend.keys),
(Field::Hydrated, &mut backend.hydrated),
(Field::Fused, &mut backend.fused),
(Field::Similar, &mut backend.similar),
(Field::SimilarHydrated, &mut backend.similar_hydrated),
] {
if entry.path.is_ident(road.as_str()) {
return road_block(&entry, seat, road, field, errors);
}
}
if let Some(floor) = floor_word(&entry.path) {
errors.push(named(&entry, floor_is_the_frameworks(floor)));
return Ok(());
}
errors.push(attribute::unknown(
&entry,
&format!(
"unknown entry in a backend block on `{field}` — an ELECTION's skin sets the SDL default \
its query arguments publish, `{FIRST} = N`; names the two types a request builds, \
`{QUESTION}(rename = \"…\")` and `{ENGINES}(rename = \"…\")`; names the two a fused \
answer is read through, `{SIGHTING}(rename = \"…\")` and \
`{FUSED_KEY_MATCH}(rename = \"…\")`; and names the query fields it mounts, one block \
per road: {roads}. The Rust-vocabulary numbers beside `{FIRST}` are `{limit}` and \
`{depth}`, written BARE on the field: a schema's word and a door's word are the same \
number at two tiers, and neither is spelled in the other's block",
roads = road_list(),
limit = NUMBER_WORDS[0],
depth = NUMBER_WORDS[1],
),
&election_words(),
));
Ok(())
});
skins.push(backend);
walked
});
if skins.is_empty() {
errors.push(syn::Error::new_spanned(
&meta.path,
format!(
"`{GRAPHQL}` on `{field}` names no backend, and a skin is one backend's description — write \
`{GRAPHQL}({first})`. Without the word this election still publishes every field it would \
otherwise publish; what the block sets is what THIS backend calls their defaults",
first = GraphqlKind::ALL[0].as_str(),
),
));
}
walked
}
const GRAPHQL: &str = "graphql";
const SLOT: &str = "slot";
const SLOT_SHAPE: &str = "`slot` is the DURABLE name this family's objects are stored under, in a \
string literal — `slot = \"poster_frames\"`. The default is \
`snake_case(<declaration name>)`, so the word is only written where that \
is not what the store already holds";
fn slot_wrong_grain(kind: NodeKind) -> String {
format!(
"`slot` names ONE corpus and {article} {noun} owns one per `(field × engine)` PAIRING, so a \
word at the head has no way to say which. The durable names here are built from the three \
parts and joined with `__` — `<declaration>__<field>__<engine>` — which is what keeps two \
pairings apart where a camel-case type name could not. An ARTIFACT FAMILY holds one object per \
message and has exactly one corpus, which is why the word is that kind's",
article = kind.article(),
noun = kind.noun(),
)
}
fn refuse_a_malformed_slot(name: &syn::LitStr, errors: &mut Errors) {
let spelled = name.value();
let legal = !spelled.is_empty()
&& !spelled.starts_with(|c: char| c.is_ascii_digit())
&& spelled
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '_');
if !legal {
errors.push(syn::Error::new_spanned(
name,
format!(
"`{spelled}` is not a slot name — it must be non-empty ASCII `[A-Za-z0-9_]` and must not \
start with a digit. The name reaches a STORE, where it is a directory or a table, so the \
alphabet is the narrow one every backend agrees on"
),
));
}
}
const BLOB_MINTS_NO_WIRE: &str = "an artifact family mints no wire type of its own, so there is \
nothing here for a backend word to dress. Its wire presence is \
the RECORD's: `locate(<name> = \"path::to::ThisFamily\")` puts \
the address on that record's object, and the position's `data` \
ask puts the bytes beside it — both written into the `#[Object]` \
block the record owns, because a second one on the same type is \
`E0119`. The block opens here the day this kind mints wire of its \
own";
fn graphql_word(
meta: &syn::meta::ParseNestedMeta<'_>,
graphql: &mut Option<IndexGraphql>,
errors: &mut Errors,
) -> syn::Result<()> {
let mut backends: Vec<IndexBackend> = Vec::new();
let walked = attribute::options(meta, |inner| {
let Some(kind) = crate::parse::graphql_kind(&inner.path) else {
errors.push(attribute::unknown(
&inner,
&format!(
"unknown backend in `graphql(…)` — this framework renders through {list}, and a word \
naming none of them names no skin. The types are backend-NEUTRAL: each word adds one \
backend's impls over the same Rust family, which is why the block holds WORDS rather \
than a bare `graphql`",
list = backend_list(),
),
&GraphqlKind::ALL.map(GraphqlKind::as_str),
));
return Ok(());
};
if backends.iter().any(|backend| backend.kind == kind) {
errors.push(syn::Error::new_spanned(
&inner.path,
format!(
"`{kind}` is declared more than once in `graphql(…)` — one block per backend, because a \
backend has ONE skin and a second word could only re-describe it",
kind = kind.as_str(),
),
));
attribute::skip_entry(&inner);
return Ok(());
}
let mut backend = IndexBackend::of(kind);
let walked = index_backend(&inner, &mut backend, errors);
backends.push(backend);
walked
});
if backends.is_empty() {
errors.push(syn::Error::new_spanned(
&meta.path,
format!(
"`graphql` names no backend, and a wire face is one backend's impls — write \
`graphql({first})`. Without the word this declaration still emits its WHOLE Rust surface: \
the doors, the packages, the evidence and the selector are all there, and what the block \
adds is a schema over them",
first = GraphqlKind::ALL[0].as_str(),
),
));
return walked;
}
*graphql = Some(IndexGraphql { backends });
walked
}
fn index_backend(
inner: &syn::meta::ParseNestedMeta<'_>,
backend: &mut IndexBackend,
errors: &mut Errors,
) -> syn::Result<()> {
let scope = format!("`{}(…)`", backend.kind.as_str());
attribute::options(inner, |option| {
if option.path.is_ident(PREFIX) {
match value::literal(&option, SKIN_PREFIX) {
Ok(base) => {
crate::wire::refuse_invalid_name(&base.value(), &base, errors);
set_once(
&mut backend.prefix,
base,
&option.path,
&format!("`{PREFIX}` is declared more than once in {scope} — one option, one value"),
errors,
);
}
Err(e) => errors.push(e),
}
return Ok(());
}
if option.path.is_ident(RENAME) {
errors.push(named(&option, base_is_a_prefix(&scope)));
return Ok(());
}
if option.path.is_ident(FUSED) {
errors.push(named(&option, EVIDENCE_HAS_NO_SKIN.to_owned()));
return Ok(());
}
if option.path.is_ident(FIRST) {
return number(
&option,
&mut backend.first,
FIRST,
"a backend block",
errors,
);
}
for (face, slot) in [
(OPTIONS, &mut backend.options),
(QUESTION, &mut backend.question),
(ENGINE, &mut backend.engine),
] {
if option.path.is_ident(face) {
let walked = attribute::sdl_name_block(&option, slot, face, errors);
if let Some(name) = slot.as_ref() {
crate::wire::refuse_invalid_name(&name.value(), name, errors);
}
return walked;
}
}
if let Some(floor) = floor_word(&option.path) {
errors.push(named(&option, floor_is_the_frameworks(floor)));
return Ok(());
}
errors.push(attribute::unknown(
&option,
&format!(
"unknown entry in {scope} on a derived index — a backend block names what THIS SKIN calls \
things: `{PREFIX} = \"…\"` re-stems the whole SDL family, and `{OPTIONS}(…)`, \
`{QUESTION}(…)` and `{ENGINE}(…)` name one face each with a `{RENAME}` row, and \
`{FIRST} = N` is the SDL default every query argument this skin publishes carries. The \
RUST family is re-based by the top-level `{RENAME}`, outside this block — a name is the \
skin's fact, and the bones are one set however many skins dress them; the Rust-vocabulary \
numbers beside it are `{limit}` and `{depth}` at the head",
limit = NUMBER_WORDS[0],
depth = NUMBER_WORDS[1],
),
&[PREFIX, OPTIONS, QUESTION, ENGINE, FIRST],
));
Ok(())
})
}
const RENAME: &str = "rename";
const PREFIX: &str = "prefix";
fn base_is_a_prefix(scope: &str) -> String {
format!(
"`{RENAME}` names ONE thing verbatim and this position re-stems a FAMILY — `{PREFIX} = \
\"clips\"` mints `ClipsFuseOptions`, `ClipsFusedEvidence` and their siblings, and no emitted \
type is called `clips` at all. So the base takes `{PREFIX}` and the FACES take `{RENAME}`, \
each of those naming one type outright: `{OPTIONS}({RENAME} = \"…\")`, \
`{QUESTION}({RENAME} = \"…\")` and `{ENGINE}({RENAME} = \"…\")` in {scope}. The RUST family is \
re-based by the top-level `{RENAME}`, outside this block{suggestion}",
suggestion = crate::suggest::meant(PREFIX),
)
}
const BLOB_MINTS_NO_TYPE: &str = "an artifact family lands no type in your scope for a `rename` to \
move — its engines are at the HEAD, so it has no \
`(field × engine)` slot and no slot marker; it elects nothing, so \
it has no election marker; and it does not retrieve, so it mints \
no package, no vocabulary and no evidence. The name this kind \
does have is the DURABLE one — `slot = \"…\"`, the directory its \
objects live under. `rename` opens here the day the kind mints a \
type of its own";
const FUSED: &str = "fused";
const OPTIONS: &str = "options";
const QUESTION: &str = "question";
const ENGINE: &str = "engine";
const ENGINES: &str = "engines";
const SIGHTING: &str = "sighting";
const FUSED_KEY_MATCH: &str = "fused_key_match";
const FLOOR_WORDS: [&str; 8] = [
"score",
"rank",
"streams",
"ordinal",
"contribution",
"node",
"coordinates",
"key",
];
fn floor_word(path: &syn::Path) -> Option<&'static str> {
FLOOR_WORDS.into_iter().find(|word| path.is_ident(*word))
}
fn floor_is_the_frameworks(word: &'static str) -> String {
format!(
"`{word}` is the FRAMEWORK's own word and no declaration moves it. The request's arguments \
(`question`, `engine`, `engines`, `first`, `depth`, `key`), an answer's rows (`score`, `rank`, \
`evidence`, `streams`, `ordinal`, `contribution`, `node`) and the question's `coordinates` arm \
are ONE vocabulary across every declaration this \
framework generates, so a client written against one schema reads the next — which is the \
whole of what a uniform floor buys, and Relay's own precedent for buying it. What IS nameable \
here is the TYPE behind an argument or an answer, because those are minted per declaration and \
per election and no client could predict them: `{QUESTION}(rename = \"…\")`, \
`{ENGINES}(rename = \"…\")`, `{SIGHTING}(rename = \"…\")` and \
`{FUSED_KEY_MATCH}(rename = \"…\")` on an election, `{OPTIONS}(rename = \"…\")`, \
`{QUESTION}(rename = \"…\")` and `{ENGINE}(rename = \"…\")` at the head. The RUST type \
behind an answer row moves with the top-level `rename(…)`, which is the other axis entirely"
)
}
fn road_list() -> String {
Field::ALL
.iter()
.map(|road| format!("`{}(rename = \"…\")`", road.as_str()))
.collect::<Vec<_>>()
.join(", ")
}
fn election_words() -> Vec<&'static str> {
[FIRST, QUESTION, ENGINES, SIGHTING, FUSED_KEY_MATCH]
.into_iter()
.chain(Field::ALL.map(Field::as_str))
.collect()
}
const EVIDENCE_HAS_NO_SKIN: &str = "the evidence a fused door answers with has no schema name to \
move — `<Index>FusedEvidence<S>` is GENERIC in the score, \
because a door is generic over the engine it asked and two \
routes' scores are two currencies, and the tier's fused door \
mounts no query field at all, so nothing on its answer side \
reaches a schema. A FANNED election does publish its fused \
answer — `<Index><Field>Sighting` and its arms — but those are \
minted wire types at the ELECTION's grain, and this block names \
one type outright. What this block CAN name is the request \
side — `options(rename = \"…\")`, `question(rename = \"…\")` \
and `engine(rename = \"…\")`; the FUSED QUERY FIELD of one \
election is named by `fused(rename = \"…\")` in that field's \
own backend block. The word opens here the day the tier's fused \
door mounts a road of its own";
const SKIN_PREFIX: &str = "a backend block's `prefix` is the STEM its SDL family is built on, in a \
string literal — `prefix = \"shotSearch\"` mints \
`ShotSearchFuseOptions` and its siblings. It moves no Rust name: the \
bones are re-based by the top-level `rename`";
fn rename_word(
meta: &syn::meta::ParseNestedMeta<'_>,
rename: &mut Option<IndexRename>,
kind: NodeKind,
errors: &mut Errors,
) -> syn::Result<()> {
if attribute::has_value(meta) {
match value::parse_literal::<syn::Ident>(meta, attribute::TYPE_NAME) {
Ok(base) => *rename = Some(IndexRename::Base(base)),
Err(e) => errors.push(e),
}
return Ok(());
}
if !attribute::has_block(meta) || attribute::empty_group(meta) {
errors.push(named(meta, rename_says_nothing(kind)));
return Ok(());
}
let mut pieces: Vec<(RenamePiece, syn::Ident)> = Vec::new();
let mut written = false;
let walked = attribute::options(meta, |option| {
written = true;
let Some(piece) = RenamePiece::of(&option.path) else {
errors.push(attribute::unknown(
&option,
&rename_vocabulary(kind),
&RenamePiece::ALL.map(RenamePiece::as_str),
));
return Ok(());
};
if pieces.iter().any(|(named, _)| *named == piece) {
errors.push(syn::Error::new_spanned(
&option.path,
format!(
"`{piece}` is declared more than once in `rename(…)` — one mint, one name",
piece = piece.as_str(),
),
));
attribute::skip_entry(&option);
return Ok(());
}
match value::parse_literal::<syn::Ident>(&option, attribute::TYPE_NAME) {
Ok(spelled) => pieces.push((piece, spelled)),
Err(e) => errors.push(e),
}
Ok(())
});
if pieces.is_empty() {
if !written {
errors.push(syn::Error::new_spanned(
&meta.path,
rename_says_nothing(kind),
));
}
return walked;
}
*rename = Some(IndexRename::Pieces(pieces));
walked
}
fn rename_says_nothing(kind: NodeKind) -> String {
format!(
"`rename` says nothing on its own — write `rename = \"NewBase\"` to re-base every type {article} \
{noun} mints, or `rename(<piece> = \"…\")` to name individual ones. It moves RUST names only: \
what a schema calls these types is `graphql(<backend>(prefix = \"…\"))`, and this \
declaration's own struct name is yours and is never touched",
article = kind.article(),
noun = kind.noun(),
)
}
fn rename_vocabulary(kind: NodeKind) -> String {
format!(
"unknown mint in `rename(…)` — the vocabulary is CLOSED and holds the types {article} {noun} \
has AT MOST ONE of: {list}. The PER-FIELD and PER-SLOT mints — a slot's own options and \
question, a leg's options, a fold vocabulary, an election marker, a slot marker — are named by \
no word here, because *which one* would need a field and an engine beside it; `rename = \
\"NewBase\"` re-bases all of them at once",
article = kind.article(),
noun = kind.noun(),
list = RenamePiece::ALL
.iter()
.map(|piece| format!("`{}`", piece.as_str()))
.collect::<Vec<_>>()
.join(", "),
)
}
fn named_mints(model: &IndexModel, errors: &mut Errors) {
let Some(IndexRename::Pieces(pieces)) = &model.rename else {
return;
};
let tier = model.tier();
for (piece, spelled) in pieces {
if let Some(why) = tier.unmintable(*piece) {
errors.push(syn::Error::new_spanned(
spelled,
format!(
"`{piece}` names {what}, and {article} {noun} like this one mints none: {why}",
piece = piece.as_str(),
what = piece.what(),
article = model.kind.article(),
noun = model.kind.noun(),
),
));
}
}
}
fn backend_list() -> String {
GraphqlKind::ALL
.iter()
.map(|kind| format!("`{}`", kind.as_str()))
.collect::<Vec<_>>()
.join(", ")
}
fn retired_head_word(kind: NodeKind) -> String {
let successor = match kind {
NodeKind::Vector => {
"an embedding index elects a column by writing `#[ingraph(knn)]` on the field itself, and how \
that column's answer is DECIDED rides the marker as `#[ingraph(knn(semantics(fold = \
\"…\")))]`"
}
NodeKind::Fulltext => {
"a full-text index elects a field by writing `#[ingraph(searchable)]` on it — and `knn` was \
never this kind's word either: coordinates are the `vector` kind's"
}
_ => {
"an artifact family elects nothing under any spelling — it answers an address rather than a \
ranking, so no field of one is ever run over"
}
};
format!(
"`embedding(<field>)` has retired — an election is now a MARKER ON THE FIELD it elects: \
{successor}. The head word named a field from outside it, so every refusal about an election \
landed on the head rather than on the field; the marker's land on the field's own tokens, and \
a mis-typed election is reported at the TYPE its author wrote"
)
}
#[derive(Default)]
pub(crate) struct Role {
pub(crate) elected: bool,
pub(crate) engines: Vec<Engine>,
pub(crate) label: Option<ElectionLabel>,
pub(crate) fold: Option<Fold>,
pub(crate) tower_road: Option<syn::Type>,
pub(crate) fanout: Option<syn::Path>,
pub(crate) numbers: Numbers,
pub(crate) skins: Vec<ElectionBackend>,
}
const DEDUP_IS_MANDATORY: &str = "this declaration retrieves and does not say HOW it tells two of \
its keys apart — write `dedup(hash)` or `dedup(eq)` beside \
`upstream(…)`. The word is a BOUND on the key this index carries: \
`dedup(hash)` compares keys by hashing them — key: `Hash + Eq` — \
and `dedup(eq)` walks a seen-list comparing every field — key: \
`PartialEq` alone, which is the escape for a key that cannot \
hash. There is no default, because a bounds choice a declaration \
did not make is one its author meets as an error inside an \
expansion";
fn road_word_retired(word: &str) -> String {
let opener = if word == "via" {
"`via` is not the word, and `ask` is no longer one either"
} else {
"`ask` has retired"
};
format!(
"{opener} — a question road is a TOWER's now. Declare the chain with `#[ingraph::tower]`, which \
mints a `walk` over its steps and a `<Tower>Error` naming which step refused WITH THAT STEP'S \
OWN error type, then reach a column through it: bind the tower in a `#[ingraph::search]` \
recipe's `tower(<arm>(type = \"…\"))` arm, or walk it by hand and hand the coordinates to \
`retrieve_keys_by_<field>`. The SHORT spelling of that first road is written here, one word \
over: `knn(searchable(tower = \"path::to::Tower\"))` forges the one-member recipe for you, \
seat and arm and wire field included. What this word did was ERASE every hop's refusal into \
one boxed name, so a road could say which hop refused and never in what type — which is the \
whole of what it was replaced for. The RAW road is untouched either way: a caller holding \
coordinates always called `retrieve_keys_by_<field>` and still does"
)
}
fn road_word(inner: &syn::meta::ParseNestedMeta<'_>, errors: &mut Errors) {
for retired in ["ask", "via"] {
if inner.path.is_ident(retired) {
errors.push(named(inner, road_word_retired(retired)));
attribute::skip_entry(inner);
return;
}
}
errors.push(attribute::unknown(
inner,
"unknown entry in `knn(…)` — the marker's own block takes `semantics(<kind> = \"…\")`, which is \
how this election's answer is DECIDED, and `searchable(tower = \"…\")`, which is the TOWER a \
question is walked through to reach this column. WHICH field the election is over is not \
written in either: it is the field this marker is on",
&[SEMANTICS, SEARCHABLE],
));
}
fn searchable_word(
inner: &syn::meta::ParseNestedMeta<'_>,
road: &mut Option<syn::Type>,
errors: &mut Errors,
) {
if !attribute::has_block(inner) || attribute::empty_group(inner) {
errors.push(named(inner, SEARCHABLE_NAMES_A_TOWER.to_owned()));
return;
}
let walked = inner.parse_nested_meta(|word| {
if word.path.is_ident(TOWER) {
match value::parse_literal::<syn::Type>(&word, TOWER_IS_A_QUOTED_TYPE) {
Ok(tower) => set_once(road, tower, &word.path, ONE_TOWER_ROAD, errors),
Err(e) => errors.push(e),
}
return Ok(());
}
errors.push(attribute::unknown(
&word,
UNKNOWN_SEARCHABLE_ENTRY,
&[TOWER],
));
Ok(())
});
if let Err(e) = walked {
errors.push(e);
}
}
struct Elections {
embeddings: Vec<Elected>,
labelled: Vec<Labelled>,
searchable: Vec<syn::Ident>,
engines: Vec<FieldEngines>,
numbers: Vec<FieldNumbers>,
}
fn elect(
columns: &[Column],
roles: &[Role],
kind: NodeKind,
index: &syn::Ident,
errors: &mut Errors,
) -> Elections {
let mut elections = Elections {
embeddings: Vec::new(),
labelled: Vec::new(),
searchable: Vec::new(),
engines: Vec::new(),
numbers: Vec::new(),
};
let Some(marker) = kind.election() else {
return elections;
};
let stored = |field: &syn::Ident, role: &Role, elections: &mut Elections| {
let engines = if role.engines.is_empty() {
vec![Engine::bare(field.clone())]
} else {
role.engines.clone()
};
elections.engines.push(FieldEngines {
field: field.clone(),
engines,
fanout: role.fanout.is_some(),
});
if !role.numbers.is_empty() || !role.skins.is_empty() {
elections.numbers.push(FieldNumbers {
field: field.clone(),
numbers: role.numbers,
skins: role.skins.clone(),
});
}
};
for (column, role) in columns.iter().zip(roles) {
if !role.elected {
continue;
}
if kind == NodeKind::Fulltext {
elections.searchable.push(column.name.clone());
stored(&column.name, role, &mut elections);
continue;
}
let name = &column.name;
let ty = &column.ty;
let Some(label) = role.label else {
errors.push(syn::Error::new_spanned(
name,
format!(
"`{name}` is marked `{marker}` and carries no LABEL — an elected field states how many \
embeddings it holds, as `#[ingraph(embedding, {marker})]` for one and \
`#[ingraph(list(embedding), {marker})]` for a set of them. The label is what decides \
which faces this declaration emits and which doors it grows, and a macro cannot resolve \
a type to find out; there is no default, because a guessed multiplicity is a door \
emitted or withheld on a coin toss"
),
));
continue;
};
if role.fold.is_some() && !label.is_set() {
errors.push(syn::Error::new_spanned(name, fold_is_a_sets_word(name)));
}
if role.numbers.streams.is_some() && !label.is_set() {
errors.push(syn::Error::new_spanned(name, streams_is_a_sets_word(name)));
}
let mut election = Elected::new(name.clone(), label, ty.clone(), role.fold.clone());
if let Some(tower) = role.tower_road.clone() {
election = election.asked_through(tower);
}
elections.embeddings.push(election);
stored(name, role, &mut elections);
}
for (column, role) in columns.iter().zip(roles) {
if let Some(label) = role.label
&& !role.elected
{
elections
.labelled
.push(Labelled::new(column.name.clone(), label, column.ty.clone()));
}
}
if elections.embeddings.is_empty() && elections.searchable.is_empty() && !columns.is_empty() {
errors.push(syn::Error::new_spanned(
index,
format!(
"`{index}` does not say WHICH of its fields it indexes — {noun} elects at least one, by \
writing `#[ingraph({marker})]` on the field, and may mark several to elect several. \
Mandatory even where exactly one field could possibly be the subject: a field's TYPE states \
its shape, and *this is what the index is over* is a ROLE, which is declared rather than \
inferred. What no marker elects is ordinary payload — stored, hydrated, and reached by no \
query. `{index}` declares {fields}",
noun = match kind {
NodeKind::Fulltext => "a full-text index",
_ => "an embedding index",
},
fields = declared(columns),
),
));
}
elections
}
fn declared(columns: &[Column]) -> String {
if columns.is_empty() {
return "no fields at all".to_owned();
}
columns
.iter()
.map(|column| format!("`{}`", column.name))
.collect::<Vec<_>>()
.join(", ")
}
fn dedup_word(
inner: &syn::meta::ParseNestedMeta<'_>,
dedup: &mut Option<Dedup>,
errors: &mut Errors,
) {
let Some(word) = inner.path.get_ident() else {
errors.push(attribute::unknown(
inner,
&format!(
"`dedup(…)` takes ONE word — {words} — and a path with several segments is not one",
words = list(&Dedup::WORDS),
),
&[],
));
return;
};
let chosen = if word == Dedup::Hash.as_str() {
Dedup::Hash
} else if word == Dedup::Eq.as_str() {
Dedup::Eq
} else {
errors.push(syn::Error::new_spanned(
word,
format!(
"`{word}` is not a dedup mechanism — the words are {words}. `hash` compares keys by \
hashing them and asks the key for `Hash + Eq`; `eq` walks a seen-list comparing every \
field and asks only for `PartialEq`, which is the escape for a key that cannot hash. The \
vocabulary is the framework's, so a mechanism it does not implement is not a word here{near}",
words = list(&Dedup::WORDS),
near = crate::suggest::did_you_mean(&word.to_string(), Dedup::WORDS),
),
));
return;
};
if let Some(first) = dedup {
errors.push(syn::Error::new_spanned(
word,
format!(
"`dedup(…)` names ONE mechanism and `{first}` was already named — the word is a BOUND on \
this index's key, and a declaration that asks for both is asking for neither",
first = first.as_str(),
),
));
return;
}
*dedup = Some(chosen);
}
pub(crate) fn list(words: &[&str]) -> String {
words
.iter()
.map(|word| format!("`{word}`"))
.collect::<Vec<_>>()
.join(" or ")
}
fn source_entry(
inner: &syn::meta::ParseNestedMeta<'_>,
node: &mut Option<syn::Path>,
entries: &mut Vec<UpstreamEntry>,
errors: &mut Errors,
) -> syn::Result<()> {
if inner.path.is_ident("node") {
match value::parse_literal::<syn::Path>(
inner,
"`node = \"…\"` names the upstream node, as a type path in a string literal",
) {
Ok(path) => set_once(
node,
path,
&inner.path,
"`node` is declared more than once in `upstream(…)` — one entry names one upstream",
errors,
),
Err(e) => errors.push(e),
}
return Ok(());
}
let Some(field) = inner.path.get_ident().cloned() else {
errors.push(attribute::unknown(
inner,
"a projection names ONE of this declaration's fields, so the entry is that field's name — a \
path with several segments names no field of anything",
&[],
));
return Ok(());
};
if inner.input.peek(syn::Token![=]) && inner.input.peek2(syn::token::Bracket) {
errors.push(named(
inner,
format!(
"`{field} = [\"…\", \"…\"]` reads SEVERAL of the upstream's fields into one of this \
declaration's, and how they combine is not declared anywhere — one goes in as a list, \
another joined on a separator, and the two are different documents. That grammar has not \
arrived; one upstream field is `{field} = \"…\"`"
),
));
return Ok(());
}
let from = match value::literal(
inner,
&format!(
"`{field} = \"…\"` names the upstream field this one is read out of, in a string literal"
),
) {
Ok(literal) => match literal.parse::<syn::Ident>() {
Ok(from) => from,
Err(_) => {
errors.push(syn::Error::new_spanned(
&literal,
format!(
"`{field} = \"…\"` names ONE field of the upstream, so its value is a field name — a \
path, an expression or an empty string is not one"
),
));
return Ok(());
}
},
Err(e) => {
errors.push(e);
return Ok(());
}
};
if entries.iter().any(|entry| entry.field == field) {
errors.push(syn::Error::new_spanned(
&inner.path,
format!(
"`{field}` is projected more than once — one of this declaration's fields is read out of \
one of the upstream's"
),
));
return Ok(());
}
entries.push(UpstreamEntry { field, from });
Ok(())
}
fn projections(
block: &UpstreamBlock,
columns: &[Column],
kind: NodeKind,
index: &syn::Ident,
errors: &mut Errors,
) -> Vec<Projected> {
for entry in &block.entries {
if !columns.iter().any(|column| column.name == entry.field) {
errors.push(syn::Error::new_spanned(
&entry.field,
format!(
"`upstream(…)`'s entries name THIS declaration's fields, and `{}` is not one of \
`{index}`'s — the entry's own name is the field being filled, and its value is the \
upstream field it is read out of",
entry.field,
),
));
}
}
for column in columns.iter().filter(|column| column.name != "node") {
if !block.entries.iter().any(|entry| entry.field == column.name) {
errors.push(syn::Error::new_spanned(
&column.name,
format!(
"`{}` is read out of nothing — every field of {article} {noun} comes from the upstream \
message the document was derived from, so each one needs its own `upstream(…)` entry: \
`{} = \"<upstream field>\"`",
column.name,
column.name,
article = kind.article(),
noun = kind.noun(),
),
));
}
}
columns
.iter()
.filter_map(|column| {
let entry = block
.entries
.iter()
.find(|entry| entry.field == column.name)?;
Some(Projected {
field: column.name.clone(),
from: entry.from.clone(),
ty: column.ty.clone(),
})
})
.collect()
}
struct UpstreamBlock {
node: Option<syn::Path>,
entries: Vec<UpstreamEntry>,
at: syn::Path,
}
struct UpstreamEntry {
field: syn::Ident,
from: syn::Ident,
}
fn markers(
attrs: &[syn::Attribute],
field: &syn::Ident,
kind: NodeKind,
errors: &mut Errors,
) -> (Projection, Role) {
let mut role = Role::default();
let project = column::projection_markers(attrs, field, errors, |meta, errors| {
if meta.path.is_ident("id") {
return column::Claim::Refused(syn::Error::new_spanned(
&meta.path,
format!(
"`{field}` cannot be {article} {noun}'s id, because it mints none — a document is one \
upstream message indexed, so it is addressed by THAT message's key, which the expansion \
carries for it. A node that mints an id of its own is an `operator` or a `record`",
article = kind.article(),
noun = kind.noun(),
),
));
}
for owner in [NodeKind::Vector, NodeKind::Fulltext] {
let Some(word) = owner.election() else {
continue;
};
if !meta.path.is_ident(word) {
continue;
}
if kind != owner {
return column::Claim::Refused(syn::Error::new_spanned(
&meta.path,
wrong_kind(word, owner, kind, field),
));
}
if role.elected {
errors.push(syn::Error::new_spanned(
&meta.path,
format!("`{word}` is declared more than once on `{field}` — one marker, one field"),
));
attribute::skip_entry(meta);
return column::Claim::Taken;
}
role.elected = true;
if owner == NodeKind::Fulltext {
if attribute::has_block(meta) || attribute::has_value(meta) {
errors.push(named(
meta,
format!(
"`{word}` is a BARE marker — it says `{field}` is searched, which is the whole of \
what a full-text election declares. WHICH ENGINE holds it is written BESIDE the \
marker, each engine its own block: `#[ingraph({word}, <engine>, <engine>(<knob> = \
…))]`. What a search is SCOPED by is not this grammar's yet, and a word parsed into a \
model nothing spends is a promise rather than a rule"
),
));
}
return column::Claim::Taken;
}
if let Err(e) = attribute::options(meta, |inner| {
if inner.path.is_ident(SEMANTICS) {
semantics_word(&inner, &mut role.fold, errors);
return Ok(());
}
if inner.path.is_ident(SEARCHABLE) {
searchable_word(&inner, &mut role.tower_road, errors);
return Ok(());
}
road_word(&inner, errors);
Ok(())
}) {
errors.push(e);
}
return column::Claim::Taken;
}
if begins_an_election_label(&meta.path) {
if kind != NodeKind::Vector {
return column::Claim::Refused(named(
meta,
format!(
"`{field}` is labelled as an embedding field and {article} {noun} elects none — the \
label says how many embeddings a knn's column holds, and this node runs no knn. The \
label is the `vector` kind's own",
article = kind.article(),
noun = kind.noun(),
),
));
}
if let Some(read) = one_label(meta, field, errors) {
set_once(
&mut role.label,
read,
&meta.path,
&format!(
"`{field}` is labelled more than once — one label, one field. A field holds one \
embedding or a set of them, and the two are different labels rather than two halves of \
one"
),
errors,
);
}
return column::Claim::Taken;
}
if meta.path.is_ident(FANOUT) {
if kind.election().is_none() {
return column::Claim::Refused(syn::Error::new_spanned(
&meta.path,
format!(
"`{FANOUT}` says every engine `{field}` declared is live at once, and {article} {noun} \
declares none — it elects nothing, so no field of one is written to an engine at all",
article = kind.article(),
noun = kind.noun(),
),
));
}
if attribute::has_block(meta) || attribute::has_value(meta) {
errors.push(named(
meta,
format!(
"`{FANOUT}` is a BARE marker — it says every engine `{field}` declared is live at once, \
and *all of them* has no knob inside it. What ONE engine is tuned by is that engine's \
own block, written beside this word"
),
));
return column::Claim::Taken;
}
if role.fanout.is_some() {
errors.push(syn::Error::new_spanned(
&meta.path,
format!("`{FANOUT}` is declared more than once on `{field}` — one marker, one field"),
));
return column::Claim::Taken;
}
role.fanout = Some(meta.path.clone());
return column::Claim::Taken;
}
if let Some(walked) = numbers_word(meta, &mut role.numbers, &format!("`{field}`"), errors) {
if let Err(refusal) = walked {
return column::Claim::Refused(refusal);
}
return column::Claim::Taken;
}
if meta.path.is_ident(GRAPHQL) {
if let Err(refusal) = election_skins(meta, &mut role.skins, field, errors) {
return column::Claim::Refused(refusal);
}
return column::Claim::Taken;
}
for word in [
ingraph_codegen::aggregate::GROUP,
ingraph_codegen::aggregate::MEASURE,
] {
if meta.path.is_ident(word) {
return column::Claim::Refused(syn::Error::new_spanned(
&meta.path,
crate::aggregate::wrong_kind(word, kind, crate::aggregate::Written::OnAField),
));
}
}
if meta.path.is_ident("persist") {
return column::Claim::Refused(syn::Error::new_spanned(
&meta.path,
format!(
"`persist(…)` is the ROW storage's wrapper and an index field takes none — on a field of \
{article} {noun} the ENGINE IS THE STORE, so there is no second axis for a wrapper to \
namespace against and the engines are written BARE beside the marker: \
`#[ingraph({marker}, <engine>, <engine>(<knob> = …))]`. A node whose messages land in a \
database is a `record`",
article = kind.article(),
noun = kind.noun(),
marker = kind.election().unwrap_or("…"),
),
));
}
let Some(word) = meta.path.get_ident().cloned() else {
return column::Claim::Refused(attribute::unknown(
meta,
"an engine is named by ONE word — `lance`, `tantivy`, `hnsw` — and a path with several \
segments names no engine. The word is bare because it is a NAME the deployment binds: a \
path written on a declaration would bind it here, where the engine a build actually \
compiled is not knowable",
&[],
));
};
if kind.election().is_none() {
return column::Claim::Refused(syn::Error::new_spanned(
&word,
format!(
"`{word}` reads as an ENGINE, and {article} {noun} names none on its fields — it elects \
nothing, so it has no field-scoped index for an engine to hold. Where its artifacts are \
written is the store layer's{near}",
article = kind.article(),
noun = kind.noun(),
near = crate::suggest::did_you_mean(&word.to_string(), column::PROJECTIONS),
),
));
}
if let Some(shipped) = EngineKind::of(&word) {
return column::Claim::Refused(syn::Error::new_spanned(
&word,
format!(
"`{word}` is an engine `ingraph` ships, and an engine is not named at an election any \
more — kind is said ONCE, at the resource: `#[ingraph::resource({word})] pub struct \
Store;`. Here `{field}` writes a LABEL of its own and POINTS at that declaration — \
`{word}_of_mine(resource = \"crate::Store\")` — so the label names this leg in the fused \
road and the store's kind stays where it was declared. `{word}` holds {serves}",
serves = shipped.serves().plural(),
),
));
}
if let Some(first) = role.engines.iter().find(|engine| engine.word == word) {
errors.push(syn::Error::new_spanned(
&word,
format!(
"`{first}` is declared more than once on `{field}` — one block per engine, exactly as \
one `persist(…)` names a database once. TWO FIELDS sharing an engine repeat the word, \
each on its own field, and that is two slots rather than a repeat",
first = first.word,
),
));
attribute::skip_entry(meta);
return column::Claim::Taken;
}
if attribute::has_value(meta) {
errors.push(named(
meta,
format!(
"`{word}` is an ENGINE and an engine is declared as a BLOCK — write `{word}` for its \
defaults, or `{word}(…)` to tune it. `{word} = …` reads as an option of this grammar's, \
and what goes inside an engine's parentheses is the ENGINE's, bar the {claimed} this \
grammar claims",
claimed = BLOCK_WORDS.map(|word| format!("`{word}`")).join(", "),
),
));
role.engines.push(Engine::bare(word));
return column::Claim::Taken;
}
role
.engines
.push(engine_block(meta, word, field, kind, errors));
column::Claim::Taken
});
(project, role)
}
const STORED: &str = "stored";
const JOIN: &str = "join";
const MULTI: &str = "multi";
const RESOURCE: &str = "resource";
const RETIRED_TYPE: &str = "type";
const RRF: &str = "rrf";
const LANES: &str = "lanes";
const ACCEPTS: &str = "accepts";
const CATCH_ALL: &str = "catch_all";
const LANE_WORDS: [&str; 2] = [ACCEPTS, CATCH_ALL];
const BLOCK_WORDS: [&str; 7] = [MULTI, JOIN, "from", STORED, RESOURCE, RRF, LANES];
const CONVERSION_WORDS: [&str; 5] = [JOIN, MULTI, STORED, "from", "try_from"];
fn engine_block(
meta: &syn::meta::ParseNestedMeta<'_>,
word: syn::Ident,
field: &syn::Ident,
kind: NodeKind,
errors: &mut Errors,
) -> Engine {
let word = &word;
let scope = format!("`{word}(…)` on `{field}`");
let mut carried = proc_macro2::TokenStream::new();
let mut from = crate::parse::ConversionSpec::default();
let mut leaves = crate::parse::ConversionSpec::default();
let mut join: Option<syn::LitStr> = None;
let mut multi: Option<syn::Path> = None;
let mut stored: Option<syn::Path> = None;
let mut resource: Option<syn::Path> = None;
let mut rrf: Option<syn::LitBool> = None;
let mut lanes: Option<(syn::Path, Vec<DeclaredLane>)> = None;
let mut lane_options: Vec<(syn::Ident, proc_macro2::TokenStream)> = Vec::new();
if let Err(e) = attribute::options(meta, |inner| {
if kind != NodeKind::Fulltext
&& CONVERSION_WORDS
.iter()
.any(|conversion| inner.path.is_ident(conversion))
{
errors.push(named(
&inner,
format!(
"`{written}` is the FULL-TEXT conversion grammar's, and `{field}` is {article} {noun}'s \
— the words say how a value is read as the text an engine indexes, and this kind indexes \
no text. A `knn` column is a coordinate: nothing joins it, nothing renders it, and what \
it is stored as is the engine's own",
written = inner.path.to_token_stream(),
article = kind.article(),
noun = kind.noun(),
),
));
return Ok(());
}
if inner.path.is_ident(LANES) {
lanes_block(
&inner,
&mut lanes,
&mut lane_options,
word,
field,
kind,
&scope,
errors,
);
return Ok(());
}
if inner.path.is_ident(RETIRED_TYPE) {
errors.push(named(
&inner,
format!(
"`{RETIRED_TYPE} = …` retired — write `{RESOURCE} = \"path::To::Resource\"` instead. The \
old word named an ENGINE here, which said the KIND of a store twice: once on this \
declaration and once on whatever the deployment opened. Kind is said ONCE, at the \
resource — `#[ingraph::resource(tantivy)] pub struct Ft;` — and `{word}` POINTS at that \
declaration"
),
));
return Ok(());
}
if inner.path.is_ident(RESOURCE) {
match value::parse_literal::<syn::Path>(
&inner,
&format!(
"`{RESOURCE} = \"path::To::Resource\"` names the RESOURCE `{word}` is written to, as a \
path in a string literal. It is what lets this slot's package publish a floor in that \
store's own `Score` — there is no blanket currency for one, so a package pointing at \
nothing has no `engine` seat at all"
),
) {
Ok(path) => set_once(
&mut resource,
path,
&inner.path,
&format!("`{RESOURCE}` is declared more than once in {scope} — one leg, one store"),
errors,
),
Err(e) => {
errors.push(e);
attribute::skip_entry(&inner);
}
}
return Ok(());
}
if inner.path.is_ident(RRF) {
match value::boolean(
&inner,
&format!(
"`{RRF}` takes a BOOLEAN written bare — `{RRF} = false`. It says whether `{word}` enters \
the fused road of `{field}`'s fan: TRUE (the default, and what saying nothing means) \
puts this leg's ranking into the fold as its own evidence, FALSE writes the leg and \
leaves it out of the leaderboard — a fan for REDUNDANCY rather than for a leaderboard. \
There is no bare form, because the default is already the `true` one"
),
) {
Ok(flag) => set_once(
&mut rrf,
flag,
&inner.path,
&format!("`{RRF}` is declared more than once in {scope} — one leg, one membership"),
errors,
),
Err(e) => {
errors.push(e);
attribute::skip_entry(&inner);
}
}
return Ok(());
}
if inner.path.is_ident(STORED) {
if attribute::has_block(&inner) || attribute::has_value(&inner) {
errors.push(named(
&inner,
format!(
"`{STORED}` is a BARE marker — it says `{word}` keeps `{field}`'s value beside what it \
indexed, and *keep it* has no knob inside it. HOW an engine stores what it keeps is \
that engine's own, written as its own knob in this block"
),
));
return Ok(());
}
set_once(
&mut stored,
inner.path.clone(),
&inner.path,
&format!("`{STORED}` is declared more than once in {scope} — one marker, one block"),
errors,
);
return Ok(());
}
if inner.path.is_ident(JOIN) {
match value::literal(
&inner,
&format!(
"`{JOIN}` takes the SEPARATOR it joins with, in a string literal — `{JOIN} = \", \"`. It \
is a value rather than a bare word because the separator is the declaration's own \
choice, and rather than a block because there is nothing else inside it to name"
),
) {
Ok(separator) => set_once(
&mut join,
separator,
&inner.path,
&format!("`{JOIN}` is declared more than once in {scope} — one road, one block"),
errors,
),
Err(e) => {
errors.push(e);
attribute::skip_entry(&inner);
}
}
return Ok(());
}
if inner.path.is_ident(MULTI) {
if attribute::has_block(&inner) || attribute::has_value(&inner) {
errors.push(named(
&inner,
format!(
"`{MULTI}` is a BARE marker — it says each of `{field}`'s values reaches `{word}` as its \
own segment, and *each of them* has no knob inside it. The road that DOES take a value \
is `{JOIN} = \"<separator>\"`, which puts them in one segment instead"
),
));
return Ok(());
}
set_once(
&mut multi,
inner.path.clone(),
&inner.path,
&format!("`{MULTI}` is declared more than once in {scope} — one road, one block"),
errors,
);
return Ok(());
}
for leg in ["into", "try_into"] {
if inner.path.is_ident(leg) {
errors.push(named(
&inner,
format!(
"`{leg}` LEAVES the projection a block is about, and a full-text document is never \
left: it is written and searched, and what a hit hands back is the ADDRESS its key was \
encoded into, not the text. So this block has one direction and `from` is it — \
`from = \"path::to::fn\"`, or `try_from = \"…\"` where the conversion can fail"
),
));
return Ok(());
}
}
if crate::parse::conversion(
&inner,
&mut from,
&mut leaves,
&scope,
crate::parse::Cells::Elsewhere,
errors,
) {
return Ok(());
}
attribute::carry(&inner, &mut carried);
Ok(())
}) {
errors.push(e);
}
let declared = from.resolve(&scope, crate::parse::BUILDS, errors);
let road = settle_road(join, multi, declared, word, field, &scope, errors);
carry_lane_options(&mut carried, &lane_options);
Engine {
word: word.clone(),
road,
stored: stored.is_some(),
resource,
options: carried,
rrf: rrf.is_none_or(|flag| flag.value()),
lanes: lanes.map(|(_, declared)| declared).unwrap_or_default(),
}
}
#[expect(
clippy::too_many_arguments,
reason = "the refusals name the word, the field, the kind and the scope, and each of the four \
says something the others do not"
)]
fn lanes_block(
meta: &syn::meta::ParseNestedMeta<'_>,
lanes: &mut Option<(syn::Path, Vec<DeclaredLane>)>,
lane_options: &mut Vec<(syn::Ident, proc_macro2::TokenStream)>,
word: &syn::Ident,
field: &syn::Ident,
kind: NodeKind,
scope: &str,
errors: &mut Errors,
) {
if kind != NodeKind::Fulltext {
errors.push(named(
meta,
format!(
"`{LANES}(…)` is the FULL-TEXT kind's, and `{field}` is {article} {noun}'s — a lane exists \
because a searched field has ONE tokenizer and a schema that cannot change, so a corpus \
holding several languages is several indexes. {Noun} indexes no text and has no analyzer \
to vary, so there is nothing here for a partition to be a partition OF",
article = kind.article(),
noun = kind.noun(),
Noun = {
let noun = kind.noun();
let mut titled = noun.to_owned();
titled[..1].make_ascii_uppercase();
format!("A {titled}")
},
),
));
return;
}
if let Some((_, _)) = lanes.as_ref() {
errors.push(named(
meta,
format!(
"`{LANES}` is declared more than once in {scope} — one corpus, one set of partitions"
),
));
return;
}
if attribute::has_value(meta) {
errors.push(named(
meta,
format!(
"`{LANES}` is a BLOCK and not a value — `{LANES}(en, zh(accepts(cmn)), rest(catch_all))`. \
Each entry is one PARTITION of `{field}`'s corpus, keyed by a bare word, so there is \
nothing for a single `{LANES} = …` to name"
),
));
return;
}
if !attribute::has_block(meta) || attribute::empty_group(meta) {
errors.push(named(
meta,
format!(
"`{LANES}(…)` names at least one lane — `{LANES}(en, zh(accepts(cmn)))`. An EMPTY fan is a \
corpus no document can reach, and the corpus with one partition is what saying nothing \
already means: leave `{LANES}` off and `{word}` holds the single undetermined lane it \
always did"
),
));
return;
}
let at = meta.path.clone();
let mut roster: Vec<DeclaredLane> = Vec::new();
if let Err(e) = meta.parse_nested_meta(|entry| {
let Some(key) = entry.path.get_ident().cloned() else {
errors.push(named(
&entry,
format!(
"a lane is keyed by a BARE WORD, and `{written}` is a path — `{LANES}(zh, zh_hant)`. The \
key is compared through this crate's one fold, which drops `_` and `-` and ignores case, \
so the tag `zh-Hant` reaches the lane written `zh_hant` without a second spelling \
anywhere",
written = entry.path.to_token_stream(),
),
));
return Ok(());
};
if attribute::has_value(&entry) {
errors.push(named(
&entry,
format!(
"`{key}` is a LANE and a lane is a WORD, optionally with a block — `{key}` for a lane \
that answers only its own key, or `{key}(…)` to say more. `{key} = …` reads as an option \
of this grammar's, and a lane is not one. What goes inside a lane's parentheses is \
`{word}`'s, bar the {claimed} this grammar claims",
claimed = LANE_WORDS.map(|claimed| format!("`{claimed}`")).join(" and "),
),
));
return Ok(());
}
let mut lane = DeclaredLane::of(key.clone());
let mut accepts: Option<syn::Path> = None;
let mut residue = proc_macro2::TokenStream::new();
if let Err(e) = attribute::options(&entry, |option| {
if option.path.is_ident(CATCH_ALL) {
if attribute::has_block(&option) || attribute::has_value(&option) {
errors.push(named(
&option,
format!(
"`{CATCH_ALL}` is a BARE marker — it says lane `{key}` answers every tag no other \
lane has a home for, and *every one of them* has no knob inside it"
),
));
return Ok(());
}
if lane.catch_all.is_some() {
errors.push(named(
&option,
format!("`{CATCH_ALL}` is declared more than once on lane `{key}` — one lane, one role"),
));
return Ok(());
}
lane.catch_all = option.path.get_ident().cloned();
return Ok(());
}
if option.path.is_ident(ACCEPTS) {
if attribute::has_value(&option) || !attribute::has_block(&option) {
errors.push(named(
&option,
format!(
"`{ACCEPTS}` takes the tags lane `{key}` answers, as bare words in a block — \
`{ACCEPTS}(zh_hans, zh_hant, cmn)`. A block rather than a value because a lane may \
accept several, and a list of one is still a list"
),
));
return Ok(());
}
if attribute::empty_group(&option) {
errors.push(named(
&option,
format!(
"`{ACCEPTS}()` on lane `{key}` names no tag at all, and a lane already answers its \
own key — so an empty list is a word with nothing to add. Name the tags, or leave \
`{ACCEPTS}` off"
),
));
return Ok(());
}
if let Some(first) = accepts.as_ref() {
errors.push(syn::Error::new_spanned(
&option.path,
format!(
"`{ACCEPTS}` is declared more than once on lane `{key}` — one lane, one list. The \
tags of the second belong in the first"
),
));
let _ = first;
attribute::skip_entry(&option);
return Ok(());
}
accepts = Some(option.path.clone());
return option.parse_nested_meta(|tag| {
let Some(accepted) = tag.path.get_ident().cloned() else {
errors.push(named(
&tag,
format!(
"an accepted tag is a BARE WORD, and `{written}` is a path — \
`{ACCEPTS}(zh_hans, cmn)`",
written = tag.path.to_token_stream(),
),
));
return Ok(());
};
if attribute::has_value(&tag) || attribute::has_block(&tag) {
errors.push(named(
&tag,
format!(
"`{accepted}` is an accepted TAG and a tag is a bare word — it says which spellings \
reach lane `{key}`, and there is nothing inside one to configure"
),
));
return Ok(());
}
lane.accepts.push(accepted);
Ok(())
});
}
attribute::carry(&option, &mut residue);
Ok(())
}) {
errors.push(e);
}
if !residue.is_empty() {
lane_options.push((key, residue));
}
roster.push(lane);
Ok(())
}) {
errors.push(e);
}
*lanes = Some((at, roster));
}
fn carry_lane_options(
carried: &mut proc_macro2::TokenStream,
per_lane: &[(syn::Ident, proc_macro2::TokenStream)],
) {
use proc_macro2::{Delimiter, Group, Punct, Spacing, TokenTree};
if per_lane.is_empty() {
return;
}
let mut inside = proc_macro2::TokenStream::new();
for (at, (key, residue)) in per_lane.iter().enumerate() {
if at > 0 {
inside.extend(core::iter::once(TokenTree::Punct(Punct::new(
',',
Spacing::Alone,
))));
}
key.to_tokens(&mut inside);
inside.extend(core::iter::once(TokenTree::Group(Group::new(
Delimiter::Parenthesis,
residue.clone(),
))));
}
if !carried.is_empty() {
carried.extend(core::iter::once(TokenTree::Punct(Punct::new(
',',
Spacing::Alone,
))));
}
carried.extend(core::iter::once(TokenTree::Ident(proc_macro2::Ident::new(
LANES,
proc_macro2::Span::call_site(),
))));
carried.extend(core::iter::once(TokenTree::Group(Group::new(
Delimiter::Parenthesis,
inside,
))));
}
fn settle_road(
join: Option<syn::LitStr>,
multi: Option<syn::Path>,
declared: Conversion,
word: &syn::Ident,
field: &syn::Ident,
scope: &str,
errors: &mut Errors,
) -> Road {
let shorthand = match (join, multi) {
(Some(separator), None) => Some(Road::Join(separator)),
(None, Some(_)) => Some(Road::Multi),
(Some(separator), Some(at)) => {
errors.push(syn::Error::new_spanned(
&at,
format!(
"`{JOIN}` and `{MULTI}` are both declared in {scope} — they are the two answers to ONE \
question, and the question is whether a phrase may match ACROSS two of `{field}`'s \
values. `{JOIN} = {separator:?}` says it may, `{MULTI}` says it may not, and there is no \
third answer for a road to take",
separator = separator.value(),
),
));
Some(Road::Multi)
}
(None, None) => None,
};
match (shorthand, declared) {
(None, Conversion::Default) => Road::Identity,
(Some(shorthand), Conversion::Default) => shorthand,
(None, declared) => Road::Declared(declared),
(Some(shorthand), declared) => {
errors.push(syn::Error::new_spanned(
word,
format!(
"`{shorthand}` and a declared conversion are both written in {scope} — a slot takes ONE \
road into its document, and these are two. A shorthand IS a conversion the framework \
wrote out; keep it where it says what you mean, and keep `from` where it does not",
shorthand = shorthand.word(),
),
));
Road::Declared(declared)
}
}
}
fn blob_engine(
meta: &syn::meta::ParseNestedMeta<'_>,
word: syn::Ident,
stores: &mut Vec<Engine>,
errors: &mut Errors,
) {
if let Some(shipped) = EngineKind::of(&word)
&& shipped.serves() != NodeKind::Blob
{
errors.push(syn::Error::new_spanned(
&word,
format!(
"`{word}` is the engine `ingraph` ships for {theirs}, and this declaration is an artifact \
family — the two seams are different traits, so no build binds this word to a store that \
could hold an object. A store of THIS kind is named by its own word, bound at the graph \
root with `engines({word}_of_mine = \"path::To::Store\")` unless the framework ships it",
theirs = shipped.serves().plural(),
),
));
attribute::skip_entry(meta);
return;
}
if let Some(first) = stores.iter().find(|engine| engine.word == word) {
errors.push(syn::Error::new_spanned(
&word,
format!(
"`{first}` is declared more than once — one block per store, exactly as one `persist(…)` \
names a database once. SEVERAL stores are declared PORTABILITY and the deployment picks \
one; a repeat names the same store twice and picks nothing",
first = first.word,
),
));
attribute::skip_entry(meta);
return;
}
let options = if attribute::has_value(meta) {
errors.push(named(
meta,
format!(
"`{word}` is a STORE and a store is declared as a BLOCK — write `{word}` for its defaults, \
or `{word}(…)` to tune it. `{word} = …` reads as an option of this grammar's, and what \
goes inside a store's parentheses belongs to the store"
),
));
proc_macro2::TokenStream::new()
} else if attribute::has_block(meta) {
match attribute::verbatim(meta) {
Ok(options) => options,
Err(e) => {
errors.push(e);
proc_macro2::TokenStream::new()
}
}
} else {
proc_macro2::TokenStream::new()
};
stores.push(Engine {
options,
..Engine::bare(word)
});
}
fn extension_word(
meta: &syn::meta::ParseNestedMeta<'_>,
extension: &mut Option<Extension>,
errors: &mut Errors,
) {
if attribute::has_value(meta) {
if meta.input.peek(syn::Token![=]) && meta.input.peek2(syn::token::Bracket) {
errors.push(named(
meta,
"`extension = [\"…\", \"…\"]` lists suffixes and says nothing about which one an entry \
takes — a set is not a decision, and a family whose addresses end differently has to name \
what decides. That is the block form: `extension(from = \"<column>\", any_of = [\"…\"])` \
for a string column, or `extension(from(field = \"<column>\", type = \"path::To::Enum\"))` \
for an enum one"
.to_owned(),
));
attribute::skip_entry(meta);
return;
}
match value::literal(
meta,
"`extension = \"png\"` is ONE suffix for the whole family, in a string literal",
) {
Ok(suffix) => {
if extension::admissible_suffix(&suffix.value()) {
*extension = Some(Extension::Static(suffix));
} else {
errors.push(inadmissible_suffix(&suffix));
}
}
Err(e) => errors.push(e),
}
return;
}
if !attribute::has_block(meta) {
errors.push(named(
meta,
"`extension` says nothing on its own — write `extension = \"png\"` for a family whose \
addresses all end alike, LEAVE IT OUT for extensionless storage, or `extension(from = …)` \
to decide the suffix per entry off a column"
.to_owned(),
));
return;
}
if starts_with_literal(meta) {
errors.push(named(
meta,
"`extension(\"png\")` is a single fact written as a block — this grammar writes one of those \
as a key-value: `extension = \"png\"`. The parentheses are for the form that has structure, \
where a column decides the suffix per entry"
.to_owned(),
));
attribute::skip_entry(meta);
return;
}
let mut source = None;
let mut variants: Vec<syn::LitStr> = Vec::new();
let mut any_of: Vec<syn::LitStr> = Vec::new();
let mut with = None;
let walked = attribute::options(meta, |inner| {
extension_entry(
&inner,
&mut source,
&mut variants,
&mut any_of,
&mut with,
errors,
)
});
if let Err(e) = walked {
errors.push(e);
return;
}
let Some(source) = source else {
errors.push(syn::Error::new_spanned(
&meta.path,
"`extension(…)` decides a suffix off a COLUMN and `from` is where it names one — \
`from = \"<column>\"` for a string column, or `from(field = \"<column>\", type = \
\"path::To::Enum\")` for an enum one. A block with no column has nothing to decide by",
));
return;
};
*extension = Some(Extension::Column(ColumnExtension {
source,
variants,
any_of,
with,
}));
}
fn extension_entry(
inner: &syn::meta::ParseNestedMeta<'_>,
source: &mut Option<ExtensionSource>,
variants: &mut Vec<syn::LitStr>,
any_of: &mut Vec<syn::LitStr>,
with: &mut Option<syn::Path>,
errors: &mut Errors,
) -> syn::Result<()> {
if inner.path.is_ident("from") {
let read = if attribute::has_block(inner) {
enum_road(inner, errors)
} else {
value::literal(
inner,
"`from = \"<column>\"` names the entity's own STRING column, in a string literal — an enum \
column is `from(field = \"<column>\", type = \"path::To::Enum\")`, its type written out",
)
.and_then(|literal| {
value::named_field(&literal, FROM_NAMES_A_FIELD).map(|field| ExtensionSource::Text { field })
})
.map_err(|e| syn::Error::new(e.span(), FROM_NAMES_A_FIELD))
.map_or_else(
|e| {
errors.push(e);
None
},
Some,
)
};
if let Some(read) = read {
set_once(
source,
read,
&inner.path,
"`from` is declared more than once — one suffix is decided by one column",
errors,
);
}
return Ok(());
}
if inner.path.is_ident("variants") {
return fence(inner, variants, "variants", errors);
}
if inner.path.is_ident("any_of") {
return fence(inner, any_of, "any_of", errors);
}
if inner.path.is_ident("with") {
match value::parse_literal::<syn::Path>(
inner,
"`with = \"path::to::fn\"` names the function that renders a suffix, as a path in a string \
literal — it takes the COLUMN VALUE and answers the suffix, which is what lets ONE function \
serve the write lane and the read resolver alike",
) {
Ok(path) => set_once(
with,
path,
&inner.path,
"`with` is declared more than once — one column is rendered one way",
errors,
),
Err(e) => errors.push(e),
}
return Ok(());
}
errors.push(attribute::unknown(
inner,
"unknown entry in `extension(…)` — it takes `from` (the column), `variants` (which of the \
column's values are admitted), `any_of` (which suffixes may come out) and `with` (the \
author's own render). Four keys, each one meaning",
&["from", "variants", "any_of", "with"],
));
Ok(())
}
const FROM_NAMES_A_FIELD: &str =
"`from = \"<column>\"` names ONE of the entity's fields, so the string holds a field name";
const FIELD_NAMES_A_FIELD: &str =
"`field = \"<column>\"` names ONE of the entity's fields, so the string holds a field name";
fn enum_road(
inner: &syn::meta::ParseNestedMeta<'_>,
errors: &mut Errors,
) -> Option<ExtensionSource> {
let mut field = None;
let mut ty = None;
let walked = attribute::options(inner, |entry| {
if entry.path.is_ident("field") {
match value::literal(
&entry,
"`field = \"<column>\"` names the entity's own column, in a string literal",
)
.and_then(|literal| value::named_field(&literal, FIELD_NAMES_A_FIELD))
{
Ok(read) => set_once(
&mut field,
read,
&entry.path,
"`field` is declared more than once in `from(…)` — one suffix is decided by one column",
errors,
),
Err(e) => errors.push(syn::Error::new(e.span(), FIELD_NAMES_A_FIELD)),
}
return Ok(());
}
if entry.path.is_ident("type") {
match value::parse_literal::<syn::Path>(
&entry,
"`type = \"path::To::Enum\"` names the column's own type, as a path in a string literal — \
it is written out rather than inferred, so the same spelling never means two things",
) {
Ok(path) => set_once(
&mut ty,
path,
&entry.path,
"`type` is declared more than once in `from(…)` — one column has one type",
errors,
),
Err(e) => errors.push(e),
}
return Ok(());
}
errors.push(attribute::unknown(
&entry,
"unknown entry in `from(…)` — the enum road takes `field` (the column) and `type` (its own \
type), and nothing else. A STRING column is the shorter spelling, `from = \"<column>\"`",
&["field", "type"],
));
Ok(())
});
if let Err(e) = walked {
errors.push(e);
return None;
}
match (field, ty) {
(Some(field), Some(ty)) => Some(ExtensionSource::Enumerated { field, ty }),
(field, ty) => {
let missing = if field.is_none() { "field" } else { "type" };
errors.push(syn::Error::new_spanned(
&inner.path,
format!(
"`from(…)` is the ENUM road and it needs both halves — `{missing}` is not written. The \
column is `field = \"<column>\"` and its type is `type = \"path::To::Enum\"`; a string \
column takes the shorter spelling `from = \"<column>\"` instead"
),
));
let _ = ty;
None
}
}
}
fn fence(
inner: &syn::meta::ParseNestedMeta<'_>,
into: &mut Vec<syn::LitStr>,
word: &str,
errors: &mut Errors,
) -> syn::Result<()> {
if !into.is_empty() {
errors.push(syn::Error::new_spanned(
&inner.path,
format!("`{word}` is declared more than once — one fence is one set"),
));
attribute::skip_entry(inner);
return Ok(());
}
match value::literals(
inner,
&format!("`{word} = [\"…\", \"…\"]` is a list of string literals"),
) {
Ok(read) if read.is_empty() => errors.push(syn::Error::new_spanned(
&inner.path,
format!(
"`{word} = []` fences nothing in — an empty set admits no value at all, which is a family \
that can store nothing. Leave the word out to say there is no fence"
),
)),
Ok(read) => *into = read,
Err(e) => errors.push(e),
}
Ok(())
}
fn extension_fences(column: &ColumnExtension, errors: &mut Errors) {
match &column.source {
ExtensionSource::Text { field } => {
if column.any_of.is_empty() {
errors.push(syn::Error::new_spanned(
field,
"a STRING column needs `any_of` — nothing about a `String` bounds what it holds, so the \
set of suffixes this family can produce is otherwise unstated, and an address ending in \
whatever a row happened to contain is not an address anybody can fence. An ENUM column \
needs no such word: its own variants are the set",
));
}
if let Some(first) = column.variants.first() {
errors.push(syn::Error::new_spanned(
first,
"`variants` fences the INPUT by naming a type's variants, and a string column has none — \
what a `String` may hold is not a list this grammar can write. The output fence is \
`any_of`, which a string column already carries",
));
}
}
ExtensionSource::Enumerated { ty, .. } => {
let prefix = quote::quote!(#ty).to_string().replace(' ', "");
for variant in &column.variants {
let written = variant.value().replace(' ', "");
if !written.starts_with(&format!("{prefix}::")) {
errors.push(syn::Error::new_spanned(
variant,
format!(
"`{written}` is not a variant of `{prefix}` — `variants` fences the column `from` \
named, so every entry is a FULL path under that type. A variant of some other enum \
is not a value this column can hold"
),
));
}
}
}
}
for suffix in &column.any_of {
if !extension::admissible_suffix(&suffix.value()) {
errors.push(inadmissible_suffix(suffix));
}
}
}
fn inadmissible_suffix(suffix: &syn::LitStr) -> syn::Error {
syn::Error::new_spanned(
suffix,
format!(
"`{written}` cannot end an address — a suffix is the tail of ONE name, so it is not empty, \
holds no path separator, and is neither `.` nor `..`. Each of those would invent a directory \
level the key never declared",
written = suffix.value(),
),
)
}
fn starts_with_literal(meta: &syn::meta::ParseNestedMeta<'_>) -> bool {
let fork = meta.input.fork();
let content = match (|| {
let content;
syn::parenthesized!(content in fork);
syn::Result::Ok(content)
})() {
Ok(content) => content,
Err(_) => return false,
};
content.peek(syn::Lit)
}
const FANOUT: &str = "fanout";
fn engines_of(field: &syn::Ident, role: &mut Role, kind: NodeKind, errors: &mut Errors) {
if !role.elected {
for engine in &role.engines {
errors.push(syn::Error::new_spanned(
&engine.word,
format!(
"`{field}` names `{word}` and is not elected, so there is no index for that engine to \
hold — an unmarked field is payload: stored, hydrated, and reached by no query. Mark it \
`#[ingraph({marker})]` to give it an index, or drop `{word}` and the field stays exactly \
where it is",
word = engine.word,
marker = kind.election().unwrap_or("…"),
),
));
}
if let Some(at) = &role.fanout {
errors.push(syn::Error::new_spanned(
at,
format!(
"`{field}` is marked `{FANOUT}` and is not elected — the marker says every engine this \
field declared is live at once, and a field the index does not index declares none. \
`#[ingraph({marker})]` is what elects it",
marker = kind.election().unwrap_or("…"),
),
));
}
role.engines.clear();
role.fanout = None;
return;
}
if let Some(at) = &role.fanout
&& role.engines.len() < 2
{
errors.push(syn::Error::new_spanned(
at,
match role.engines.first() {
Some(only) => format!(
"`{field}` declares ONE engine — `{only}` — and `{FANOUT}` has nothing to fan between. \
The marker makes every declared engine live AT ONCE; with one engine that is what \
already happens, and the word would be a promise rather than a rule. Name a second \
engine beside `{only}`, or drop the marker",
only = only.word,
),
None => format!(
"`{field}` declares NO engine, so `{FANOUT}` has nothing to fan — the marker makes every \
engine a field declared live at once, and this field named none. Engines are written \
BARE beside the election: `#[ingraph({marker}, <engine>, <engine>)]`",
marker = kind.election().unwrap_or("…"),
),
},
));
role.fanout = None;
}
}
fn wrong_kind(word: &str, owner: NodeKind, kind: NodeKind, field: &syn::Ident) -> String {
let runs = match word {
"knn" => "a knn over coordinates",
_ => "a search over text",
};
let instead = match kind {
NodeKind::Fulltext => {
"it searches the TEXT its `searchable` fields hold, which is a different question from \
nearness"
}
NodeKind::Vector => {
"it runs a knn over the coordinates its `knn` fields hold, and coordinates are not text"
}
_ => "it answers an address rather than a ranking, so no field of one is run over at all",
};
format!(
"`{word}` elects `{field}` into {runs}, and {article} {noun} runs none — {instead}. The marker \
is the `{owner}` kind's own",
article = kind.article(),
noun = kind.noun(),
owner = owner.as_str(),
)
}
const LIST: &str = "list";
const SET: &str = "set";
const EMBEDDING: &str = "embedding";
fn begins_an_election_label(path: &syn::Path) -> bool {
path.is_ident(EMBEDDING) || path.is_ident(LIST) || path.is_ident(SET)
}
fn fold_is_a_sets_word(field: &syn::Ident) -> String {
format!(
"`{field}` is labelled `embedding` and `semantics(fold = …)` is the SET election's word — a \
single embedding has ONE best per query vector, so there is nothing for a fold to fold. The \
`_with` door that spends a fold is emitted for `list(embedding)` alone, which is why the two \
facts are one label apart: label the field `list(embedding)` if it carries several, or take \
the word off"
)
}
fn streams_is_a_sets_word(field: &syn::Ident) -> String {
format!(
"`{field}` is labelled `embedding` and `{STREAMS} = N` guards the SET election's `_with` road — \
it bounds how many query vectors ONE REQUEST may ask with, and a single embedding's question \
is one point, which is a count nothing can inflate. There is no `_with` road here for the \
guard to stand on: label the field `list(embedding)` if it carries several, or take the word \
off. What bounds a single-vector road is `{CEILING} = N`, which caps the DEPTH a request may \
ask for rather than the number of questions"
)
}
fn semantics_word(
inner: &syn::meta::ParseNestedMeta<'_>,
fold: &mut Option<Fold>,
errors: &mut Errors,
) {
if attribute::has_value(inner) || !attribute::has_block(inner) || attribute::empty_group(inner) {
errors.push(named(inner, SEMANTICS_IS_KEYED.to_owned()));
attribute::skip_entry(inner);
return;
}
if let Err(e) = inner.parse_nested_meta(|kind| {
semantics_kind(&kind, fold, errors);
Ok(())
}) {
errors.push(e);
}
}
fn semantics_kind(
kind: &syn::meta::ParseNestedMeta<'_>,
fold: &mut Option<Fold>,
errors: &mut Errors,
) {
if !kind.path.is_ident(FOLD) {
errors.push(attribute::unknown(kind, UNKNOWN_SEMANTIC_KIND, &[FOLD]));
attribute::skip_entry(kind);
return;
}
if attribute::has_block(kind) {
let walked = kind.parse_nested_meta(|word| {
shipped_fold(&word, fold, errors);
Ok(())
});
if let Err(e) = walked {
errors.push(e);
}
return;
}
match value::parse_literal::<syn::Path>(kind, FOLD_IS_A_QUOTED_PATH) {
Ok(path) => set_once(fold, Fold::Custom(path), &kind.path, ONE_FOLD, errors),
Err(e) => errors.push(e),
}
}
fn shipped_fold(
word: &syn::meta::ParseNestedMeta<'_>,
fold: &mut Option<Fold>,
errors: &mut Errors,
) {
let Some(spelled) = word.path.get_ident() else {
errors.push(attribute::unknown(word, &unknown_citizen(), &[]));
attribute::skip_entry(word);
return;
};
if attribute::has_value(word) || attribute::has_block(word) {
errors.push(named(word, CITIZEN_IS_A_BARE_WORD.to_owned()));
attribute::skip_entry(word);
return;
}
attribute::skip_entry(word);
let spelled = spelled.to_string();
if spelled == MEAN {
errors.push(syn::Error::new_spanned(&word.path, MEAN_IS_WITHDRAWN));
return;
}
if spelled == WEIGHTED {
errors.push(syn::Error::new_spanned(&word.path, WEIGHTED_IS_CONSTRUCTED));
return;
}
let Some(shipped) = Fold::shipped(&spelled) else {
errors.push(attribute::unknown(word, &unknown_citizen(), &Fold::WORDS));
return;
};
set_once(fold, shipped, &word.path, ONE_FOLD, errors);
}
const ONE_FOLD: &str = "`fold` is declared more than once on one election — a column has ONE \
declaration-level fold, and a caller that wants another passes it at the \
query";
const MEAN: &str = "mean";
const WEIGHTED: &str = "weighted";
const MEAN_IS_WITHDRAWN: &str = "`mean` is WITHDRAWN and is not a shipped fold — dividing by `m` \
and dividing by how many query vectors this entity actually \
answered are different semantics, and v1 does not bake a \
contestable one. A fold that divides is one you write: it is \
handed every slot INCLUDING the empty ones, so it can see which \
questions went unanswered and own its own divisor. Write it and \
name it here as `fold = \"app::MyMean\"`";
const WEIGHTED_IS_CONSTRUCTED: &str = "`weighted` ships and cannot be named here — its weights are \
checked AT CONSTRUCTION against the query they weight \
(`Weighted::for_query(&query, weights)`), and a declaration \
has no query to check them against. A shorthand names a \
fold this expansion can build from nothing, which is what \
`Default` means; pass a `Weighted` at the query instead, \
where its arity is a fact somebody can state";
fn unknown_citizen() -> String {
format!(
"unknown fold in `fold(…)` — the shorthand names one of the framework's own, and the words are \
{words}. A fold this framework does not ship is named by PATH instead, as \
`fold = \"app::MyFold\"`, which is the same mint-bare/refer-quoted split every word in this \
grammar is under",
words = list(&Fold::WORDS),
)
}
const CITIZEN_IS_A_BARE_WORD: &str = "a shipped fold is named by a BARE WORD — `fold(sum)` — \
because it is a member of a closed framework vocabulary, and \
a word with a value or a block is not one. A fold that takes \
arguments is a type you construct and pass at the query";
const SEMANTICS: &str = "semantics";
const SEARCHABLE: &str = "searchable";
const TOWER: &str = "tower";
const SEARCHABLE_NAMES_A_TOWER: &str = "`searchable` inside `knn(…)` names the TOWER a question is walked through to reach this column — \
write `knn(searchable(tower = \"path::to::Tower\"))`. It is BARE on a full-text election \
because a question is already text there and the crossing is the identity; coordinates are not \
text, so this position has one thing to say and the word says it. What the tower is asked and \
what it answers are its own `#[ingraph::tower]` declaration's, read through it rather than \
restated here";
const UNKNOWN_SEARCHABLE_ENTRY: &str = "unknown entry in `searchable(…)` — it takes `tower = \"path::to::Tower\"` and nothing else. \
Every other knob a search has is the RECIPE's, and this word's whole expansion is a \
`#[ingraph::search]` one: write that recipe by hand the moment a second knob is wanted, and this \
word stops being the shorter spelling of it";
const ONE_TOWER_ROAD: &str = "`tower` is declared more than once — one election is reached by one \
road. A column a SECOND tower also answers is a second \
`#[ingraph::search]` recipe, written by hand, because two roads into \
one column are two members and two arms rather than two words here";
const TOWER_IS_A_QUOTED_TYPE: &str = "`tower = \"path::to::Tower\"` names the tower that walks a question into this column's \
coordinates. It is QUOTED because the word names a type this declaration did not mint, which is \
the law `fold` and `node` are written under; whether that type IS a tower, and whether what it \
answers meets these coordinates, are rustc's at the binding the expansion writes";
const FOLD: &str = "fold";
const SEMANTICS_IS_KEYED: &str = "`semantics(…)` takes a semantic KIND and the type implementing \
it — `semantics(fold = \"app::MyFold\")`. The key is the kind, \
because a query makes more than one kind of decision and each \
names its own contract; the value is a type, because what \
implements one is not this framework's to enumerate";
const UNKNOWN_SEMANTIC_KIND: &str = "unknown entry in `semantics(…)` — the kinds are `fold`, and \
that is the whole vocabulary today: it names HOW the `m` \
per-query bests of a set query become one score. A second kind \
arrives as a second key beside it";
const FOLD_IS_A_QUOTED_PATH: &str = "`fold = \"app::MyFold\"` names the type that folds this \
election's set queries. It is QUOTED because it refers to a \
type this declaration did not mint, which is the same law \
`ask` and `node` are written under. The type implements \
`FoldSemantics<Score>` and `Default`, and a type that does \
neither is refused by rustc at the path written here";
fn one_label(
meta: &syn::meta::ParseNestedMeta<'_>,
field: &syn::Ident,
errors: &mut Errors,
) -> Option<ElectionLabel> {
if meta.path.is_ident(SET) {
errors.push(named(meta, set_is_reserved(field)));
attribute::skip_entry(meta);
return None;
}
if meta.path.is_ident(EMBEDDING) {
if attribute::has_block(meta) && !attribute::empty_group(meta) {
errors.push(named(
meta,
format!(
"`{EMBEDDING}` names ONE embedding and one embedding has no elements — an element label \
belongs to the container word, as in `{LIST}({EMBEDDING})`"
),
));
attribute::skip_entry(meta);
return None;
}
if attribute::has_value(meta) {
errors.push(named(meta, BARE_LABEL.to_owned()));
attribute::skip_entry(meta);
return None;
}
attribute::skip_entry(meta);
return Some(ElectionLabel::Embedding);
}
if attribute::has_value(meta) {
errors.push(named(meta, BARE_LABEL.to_owned()));
attribute::skip_entry(meta);
return None;
}
if !attribute::has_block(meta) || attribute::empty_group(meta) {
errors.push(named(
meta,
format!(
"`{LIST}` names a COLLECTION and a collection has elements — write the element's own label \
inside it, as in `{LIST}({EMBEDDING})`. Every level of a label names its family"
),
));
attribute::skip_entry(meta);
return None;
}
let mut held: Option<ElectionLabel> = None;
let mut extra = false;
let walked = meta.parse_nested_meta(|inner| {
let read = if inner.path.is_ident(LIST) || inner.path.is_ident(SET) {
errors.push(named(&inner, NESTED_CONTAINER.to_owned()));
attribute::skip_entry(&inner);
None
} else if inner.path.is_ident(EMBEDDING) {
one_label(&inner, field, errors)
} else {
errors.push(attribute::unknown(
&inner,
ELEMENT_IS_AN_EMBEDDING,
&[EMBEDDING],
));
attribute::skip_entry(&inner);
None
};
match (read, &held) {
(Some(read), None) => held = Some(read),
(Some(_), Some(_)) => extra = true,
(None, _) => {}
}
Ok(())
});
if let Err(e) = walked {
errors.push(e);
}
if extra {
errors.push(named(
meta,
format!("`{LIST}(…)` holds ONE element label — a container of two families is not a column"),
));
}
held.map(|_| ElectionLabel::List)
}
const BARE_LABEL: &str = "an election's label is a WORD rather than an assignment — write `embedding` or `list(embedding)`, which is the same spelling a record's field uses for its own kind";
const NESTED_CONTAINER: &str = "no backend carries a collection of collections — an election's members are stored one row apiece under `(owner, ordinal)`, and a set of sets has no second ordinal to be stored under. The element of `list(…)` is `embedding`";
const ELEMENT_IS_AN_EMBEDDING: &str = "the element of an election's container is `embedding` — the vocabulary here has two words, `embedding` and `list(embedding)`, because a knn runs over coordinates and the only question left is how many of them one entity holds";
fn set_is_reserved(field: &syn::Ident) -> String {
format!(
"`{SET}` is not the container word — `{field}` holds an ORDERED, duplicate-bearing collection, \
because its members are stored under ORDINALS minted by walking the field itself, and \
`{SET}(…)` in this grammar promises unordered and deduplicated. Write `{LIST}({EMBEDDING})`. \
The word `{SET}` stays reserved for a true unordered container"
)
}
fn emitted_methods(model: &IndexModel, errors: &mut Errors) {
let mut taken: Vec<&Emitted> = Vec::new();
for emitted in &model.emitted_methods() {
if let Some(first) = taken
.iter()
.find(|seen| seen.owner_name == emitted.owner_name && seen.name == emitted.name)
{
let why = format!(
"`{owner}` would declare `{name}` twice — {this}, and {that} already reaches it. rustc \
reports that duplicate inside the expansion, where nothing names the field that caused it",
owner = emitted.owner_name,
name = emitted.name,
this = emitted.origin,
that = first.origin,
);
errors.push(
match emitted.origin.column().or_else(|| first.origin.column()) {
Some(at) => syn::Error::new_spanned(at, why),
None => syn::Error::new_spanned(&emitted.owner_name, why),
},
);
}
taken.push(emitted);
}
}
fn emitted_types(model: &IndexModel, errors: &mut Errors) {
let mut taken: Vec<Declared> = Vec::new();
for declared in model.emitted_types() {
if let Some(first) = taken.iter().find(|seen| seen.name == declared.name) {
let why = format!(
"`{name}` would be {this}, and it is already {that} — a marker joins its parts in upper \
camel case, which keeps no boundary between them, so two different pairings can mint one \
name. The durable slot names stay apart (`__`-joined) and the TYPES cannot, so rename the \
field",
name = declared.name,
this = declared.role,
that = first.role,
);
let at = declared
.role
.at()
.or_else(|| first.role.at())
.unwrap_or(&model.index);
errors.push(syn::Error::new_spanned(at, why));
}
taken.push(declared);
}
}
fn concrete(generics: &syn::Generics, kind: NodeKind, errors: &mut Errors) {
let why = format!(
"generic {plural} are not supported — the declaration must be concrete, because a field's type \
is read straight off it and is what the projection audit checks against",
plural = kind.plural(),
);
if !generics.params.is_empty() {
errors.push(syn::Error::new_spanned(generics, why));
} else if let Some(clause) = &generics.where_clause {
errors.push(syn::Error::new_spanned(clause, why));
}
}
fn named_fields(input: &syn::DeriveInput, kind: NodeKind) -> syn::Result<&syn::FieldsNamed> {
match &input.data {
syn::Data::Struct(data) => match &data.fields {
syn::Fields::Named(named) => Ok(named),
syn::Fields::Unnamed(_) | syn::Fields::Unit => Err(syn::Error::new_spanned(
&input.ident,
format!(
"{article} {noun} must be a struct with named fields — `upstream(…)` fills a field BY NAME, \
and a positional one has none to be filled by",
article = kind.article(),
noun = kind.noun(),
),
)),
},
syn::Data::Enum(_) | syn::Data::Union(_) => Err(syn::Error::new_spanned(
&input.ident,
format!(
"`#[ingraph::{macro}]` supports structs only",
r#macro = kind.as_str(),
),
)),
}
}