Shared concepts

For implementation responsibilities and service boundaries, read architecture for developers. This reference defines the shared vocabulary used by individual component pages.

Pond and host roots

POND or global --pond selects the local transactional storage directory, not a path inside its virtual filesystem. pond init --birthplace LABEL creates a new identity; the label is permanent provenance. Pond /sensors/readings paths are not host paths.

host+ selects host input without requiring a pond. Global -d DIRECTORY roots host URL paths at that directory; host+csv:///readings.csv then reads DIRECTORY/readings.csv. Host reads do not imply arbitrary factories support host execution or can mutate a pond. A host sitegen build explicitly writes the chosen output directory.

URL layers and entry types

URLs have empty authority: scheme:///path, not scheme://hostname/path. file and data address raw data; table and series select queryable entry types backed by Parquet/query providers. Entry-type casting does not magically parse a raw CSV: select its format, e.g. host+csv+series:///readings.csv. A physical series has versions read as a logical sequence; a dynamic table/series computes a view.

Formats compose with host+ and compression suffixes +gzip, +zstd, +bzip2, e.g. host+csv+gzip:///readings.csv.gz. Compression is explicit, not selected by extension. Query parameters belong to the format provider. Quote ?, &, and glob-containing URLs in the shell.

host+FACTORY:///config.yaml is the factory-hostmount interface. The YAML config is a host input; it is not a storage remote. Global --hostmount /mount=host+FACTORY:///config.yaml mounts supported dynamic factory output for host queries. Old host+remote examples are removed interfaces.

Patterns and effective roots

Patterns select virtual paths, with * captures and recursive ** where supported. Quotes keep the shell from expanding them first. $0 is the first capture in factories/sitegen, not a shell positional parameter; retain quotes around authored YAML replacement strings. Imported mounts use their effective root so absolute source paths remain within the imported tree. Exec inputs/outputs use exact paths or declared directory prefixes, not this pattern language.

Substitution and credentials

Use the documented configuration field names: most factory configurations reject unrecognized fields. Sections documented as maps accept their own keys; page frontmatter can also carry custom metadata. Example configurations use illustrative paths and inputs, which you must replace for your environment.

Factory configs can reference ${env:NAME} and ${env:NAME:-default}. Validation expands a copy; persisted raw config retains references, and materialization resolves against the current process environment. Missing required values fail. Do not assume YAML strings stand in for every typed scalar without the factory's expansion path.

Storage profile credentials require raw environment references. Attachment configuration is a separate typed surface: its URL may be expanded when applied, while credential references resolve per replica at use time. Do not persist literal secrets, put them in command history, or expose them through generated output. Email report _env fields are names, not templates.

Time, ordering, and evidence

Pond mutations are transactional. Physical versions, logical series content, control-table lifecycle history, and replicated content commits are different views of that history. A logical series can concatenate multiple versions; maintenance can repack physical storage without rewriting its logical rows. Do not use local transaction sequence numbers or cross-replica fsck roots as universal content identities. Use the replication content tip and verify each local structure independently.

Prefer explicit RFC 3339 UTC timestamps. Duration strings use each component's documented grammar (usually humantime, such as 1h30m); rate limits have their own amount/period grammar. Millisecond, microsecond, and nanosecond Arrow timestamps are distinct. Inclusive query filters are not the same as half-open aggregation buckets or version watermark comparisons.

offline-e2e means asserted artifacts/results with no live service; local-service-e2e requires a local service; live-service-e2e contacts the declared service. validation-only proves parsing/schema/semantic checks, not execution. unverified makes no runnable-evidence claim. Missing credentials and skips never become successful coverage. Generated fields describe deserialization, not all semantic acceptance or operational safety.