Cultifolio Example ⟳ +
An example collection, so you can see what this page does. Nothing added here is kept: leaving deletes it.
About

Formats

Your data is readable without this app: the change log, the backup file, and what sync puts on the server, all plain.

In brief

  • Your collection is a log of changes, each setting one field of one record. Read them in order and you have the collection.
  • A backup is an ordinary zip: the whole log as JSON, your photographs as JPEGs, and spreadsheets for reading.
  • Sync stores the same log on the server, sealed with a key only you hold.
  • This page is for anyone who wants to read their data without the app, or check what the app does with it. The words it uses are in the glossary.

The change log

A collection is a list of changes, each setting one field of one record. To read it, apply the changes in order of their stamps, the latest winning each field. The result is the same whatever order they arrived in.

The format in full: the change log

Each change sets one field of one record:

{ "t": "1789520000000-0001-a7f3c2c9d1e4x0z9", "kind": "accession", "id": "rmu3e054w01a7f3c2c9d1e4x0z9", "field": "notes", "value": "sulked all summer" }

The stamp

  • t is a hybrid logical clock in three parts. First the wall time: 13 digits of milliseconds.
  • Then a hex counter of four digits, or six: past 65,535 changes in one millisecond, or for an edit placed past another stamp, which sets the bit 0x800000 (below).
  • Then the writer: the 12-character id of the device that made the change, followed by a 4-character tag for the browser tab, 16 characters in all. Each tab of one device is its own clock. A change written by the app's own number repair has a writer starting zz.
  • Stamps order by wall time, then counter value, then writer.
  • To find one device's changes, match the first 12 characters of the writer against the backup manifest's device, not the whole.
  • A device follows a peer's clock only up to five minutes ahead of its own, so one phone set to the wrong year cannot become every device's clock.
  • kind is one of accession, event, location, sowing, photo, taxon and setting. A sowing is what the app calls a propagation batch, and a location is a space.
  • A delete is a change setting _deleted to true. A later change to any other field of that record revives it.
  • The fields id, kind and _t belong to the record and cannot be set by a change, nor can the names * and _deleted=.
  • A change this version writes also carries its own w, beside t: the writing device's corrected clock when it wrote the change, in milliseconds since the epoch. It is not a field, so it is not a photograph's width w.
  • w is information only. No merge, hold or park reads it, and a log reads the same with it or without it.
  • A stamp read from a clock already says when its change was made. A marked stamp says only where its change sits in the order. So wherever the app shows a change's time, a marked change is dated by its w.
  • That covers the dates of a plant's earlier notes, the date of the number repair's note, and the time a photograph's removal is sent to the server with.
  • A photograph's removal is dated by the earlier of its w and when this device first saw it, so a removal written by a clock running ahead is not held until that clock's time.
  • A change written by an older version has no w, and is dated by its stamp.
  • A w that is not a whole number of milliseconds from 2020-01-01 to the last date a Date can hold, or that is more than a day past its stamp's wall time, is left off and the change kept. Of two copies of one change, the earlier w is kept.

Reading the log

  • To read a collection, sort the changes by t and apply them in order, keeping for each record and field the value with the greatest t. The app calls this folding the log.
  • The result is the same whatever order the changes arrived in, and applying a change twice changes nothing.
  • That is the merge rule; backup restore and sync both use it. A reader who wants the same collection must follow four refinements too.
  • Two changes under one stamp, which a correct writer never makes, keep the one whose value sorts greater, and for a removal the removal.
  • A record is live only while it has its required fields (a plant its name and status, a batch its count), so a record arriving field by field is shown only once whole.
  • A record is removed if its latest removal is later than its latest edit to any other field, so an edit after a removal brings it back.
  • The hold and park rules (below) keep a change from a wrong clock out of the reading for a while, or for good.

Records and numbers

  • Records are plain JSON with flat fields, keyed by an opaque identity, id, minted once on the device that made the record and never shown.
  • An id is a kind prefix (r a plant, s a batch, l a space, p a photograph, e an event), then the minting stamp's wall time as exactly 8 base-36 digits, its counter in two or more base-36 digits, and the writer: rmu3e054w01a7f3c2c9d1e4x0z9.
  • The app reads the time as the 8 characters after the prefix.
  • A photograph made since October 2026 has 16 random base-36 characters after the time, in place of the counter and the writer, so its id cannot be guessed from the vault's listing.
  • The number repair's note is the exception: its id is e_ and a tag made from the record, the number it had and the number it gets. So two devices that renumber the same record write one note.
  • The number a plant is known by is a field, acc, unique among live and dead plants and never reused. Two devices that make the same number offline end up with two plants under one number, never one plant made of both, until the grower renumbers one.
  • A merge (a restore from a file, a sync pull) writes what arrived and nothing more, and never renumbers anything.
  • Two records it leaves under one number are both listed. Each record's page names the other and says which would keep the number: the one recorded first, by its first stamp. Nothing is renumbered until the grower presses Renumber.
  • The number Renumber gives is past every number the log has ever given a plant or batch, not only the numbers records hold now.
  • Of two notes for one number renumbered two ways on two devices, the one whose new number the record holds is shown and the other hidden. A later renumbering that went on from it keeps it shown.
  • Two notes an older version wrote for one renumbering (the same words) are shown as one line, the earliest dated. Removing it removes both, and Undo brings both back.
  • While a number is shared, every link the app makes to either record is by its record id, not by the number. An address by the bare number (a typed one, an old bookmark) opens a chooser listing both.
  • So does a number a renumbering moved a plant off, read from the renumbering's note ("Renumbered from 2026-0012 to 2026-0019"): links to the plant holding it are by record id, and an address by that number with no label tag lists both.
  • An item (2026-0012/A) renumbered takes the next free letter of its accession, 2026-0012/B, its acc and item written together. A plant holding an accession's bare number, renumbered, takes its items to the new number in the same commit, each keeping its letter while that number was never given, each with a note. Restore does the same.
  • A removed plant or batch brought back (Undo, or Restore on its page) yields its number only to a record that reached this device while it was removed, judged by the order in which changes arrived here and never by two devices' clocks, whenever that record was made; the one coming back then takes the next free number.
  • It takes it with a note saying so, and the other keeps its number and its printed label.
  • A change stored before this device kept that order (an older version did not) has no place in it, and a removal of that age comes before anything that has one.
  • When neither the removal nor the other record has a place, which came first is not known: the record that stayed keeps the number, since its label is the one likely printed, and the one coming back takes the next free number, with a note and a message saying the order is not known.
  • A replace from a backup is the same: the file carries no order of arrival, so the changes it wrote have no place in it, and a change that arrives after the replace comes after them all.
  • A Replace writes into the new log, as one setting record, the numbers this device had given that the file does not carry (below), so a number given once is never given again.
  • Opening the collection, or a sync run that brings nothing, reads the log and never writes to it.
  • Nor does a page that reads the reference. A plant whose GBIF key the reference does not file its name under says so, and the key changes only when the grower takes the reference's.
  • A change in the log that no version can read (a field the record owns, a kind it does not know) is skipped and counted, and the Backup page says how many. While there are any, no snapshot is written. Nothing that reaches the log by sync, a backup, a merge or an edit can be one.
  • It stays in the log. A backup carries it apart, as it is, in unreadable.json. The restore preview, the sheets and sync's push leave it out, so every batch a device sends holds every change that can be read.
  • A browser that refuses the collection's storage is said, not left opening.
  • Sowings carry their batch number in no, as plants carry theirs in acc.
  • Joins are by id, never by number. An event's acc and a photo's acc hold the plant's record id (the rmu3e…, not the 2026-0001). A sowing's own events (germinate, potup, loss) hold the sowing's record id; a photo of a batch carries it in sowing.
  • To list a plant's events, take the plant's id and select the events whose acc equals it.

The fields, by kind

Each kind of record has a fixed set of fields. Dates are written YYYY-MM-DD, temperatures in °C and sizes in millimetres, whatever the display. A field a record has never been given is absent.

The format in full: the fields, by kind

accession (a plant)

  • acc: the plant number. taxonName, and taxonKey, the GBIF key. nameAsReceived: the name as it came, where the name filed differs.
  • cultivar, nameKind (species, cultivar or hybrid), and parentage: a cross's parents.
  • A cultivar named under a genus alone ("Echeveria 'Lola'") is filed as a cultivar, its genus as the name and no reference key, and shown as "a cultivar, species not stated". A plant an older version filed that way, as a hybrid with no parentage, is read as written; its page offers to file it as a cultivar, species not stated, which writes the change and a note to the log.
  • fieldNumber, provenance (wild, f1, fn, veg, unknown), status (growing, archived, dead), and locationId, the space.
  • acquired: YYYY-MM-DD, or YYYY-MM or YYYY when an import read only a month or a year.
  • sourceFrom, sourceRef, sourceForm, price and notes.
  • notesBase: the stamp of the notes change the latest notes edit was made from. So an edit made in sight of a text is told from one made blind to it.
  • A text an edit replaced blind stays in the log. The record's page reads it from there and shows it under the notes, on every device, writing nothing.
  • sowingId, and cover, a photo id.
  • waterDays: the plant's own watering rhythm, 1 to 365 days, over its space's. It does not take the plant out of its space's dry months.
  • importKey: the sheet line an import filed the plant from, as a 53-bit hash in base 36 after an "i". Nothing of the line's text is kept, and a plant not imported has none.
  • The hash is of the line's fields as the import reads them through the column mapping: the name as read, Genus and Species joined; a date as read, or its text when not read; a number with its leading zeros dropped; a column no field takes left out.
  • "Taken from" and "taken as" are in the hash only on a line that gives either, so a sheet without them keys its lines as before.
  • Each run of spaces is made one and the case folded, then "#" and the plant's place among the plants that line and its identical lines make.
  • importKeyBare: on a plant whose line had columns no field takes, the same key read without them, so a run of the sheet that has lost those columns finds the plant.
  • olderOf: the name of the species page the add form or an import found this plant's name to be an older name of, when you kept the name as typed. The plant's page then shows that species. A change of name clears it.
  • olderKind (gbif, older): beside olderOf, which kind of name the add form, the photo walk or the import read it to be when the plant was filed. "gbif" is GBIF's name for that page's own key, and "older" one of the page's older names. It is absent where they could not tell, and on a plant filed before it was kept. The plant's page asks the reference again when it opens, and says what the record holds only when the reference is not reached. Any other word is read as not known. A change of name clears it.
  • motherAcc: the plant this one was taken from, by its record id, when it was added from one of yours without a batch. motherHow (offset, cutting, division, leaf, bulbil): how. A plant potted up from a batch knows its parent through the batch instead.
  • A link to another plant stays when that plant is removed. A value that is not a record id (not text, longer than 64 characters, or the plant's own) is read as none, and a word for how that this version does not know is shown as it is.
  • season (winter, summer, none): the plant's growing season, as you set or confirmed it on its page. restMonths: the months, 1 to 12, it rests in, at most eleven; none for a plant with no rest.
  • seasonFrom (rain, cool, spread, grower): what you confirmed the season from. That is the species page's rain rule, its temperature rule or its spread rain, or your own setting.
  • A season of another word, or months that are not whole numbers from 1 to 12, or all twelve, is read as no season set, and the plant follows its space. Absent on a plant never given one.
  • olderKindOf: the olderOf that olderKind was read for, filed with it. The kind is read only while olderOf is still that name: an older version of the app moves olderOf on a change of name and leaves the kind, so a kind filed for another name, or with no name beside it, is read as not known. A change of name clears it with the kind.
  • item and itemOf: an offset, division or bulb split of an accession, filed as a plant of its own. Its number is the accession's and a letter, "2026-0012/A". item is the letter, A to ZZ, and itemOf the record id of the plant that holds the bare number.
  • The plants of one accession share their name, identification and provenance: an edit of any of these on one of them is written to each in the same commit. Each keeps its own space, status, notes, log and photographs.
  • deacc (died, given, lost, failed, stolen, reaccessioned): why the plant is no longer held; failed is a propagation that failed. deaccOn is the day, YYYY-MM-DD, YYYY-MM or YYYY, and deaccNote a note of up to 1,000 characters. The status is set with it: dead for died and failed, archived otherwise. A plant whose status is growing is held whatever reason it still carries (a version before this one set the status alone when marking it growing), and its next edit writes the three fields empty.
  • provType (W, Z, G, U) and propHistory (I, S, SA, SB, SC, V, VA, VB, U) are fields E.1 and E.2 of ITF2, the International Transfer Format for Botanic Garden Plant Records, version 2 (BGCI and TDWG). Provenance Type and Propagation History, in ITF2's codes.
  • collector: the collector's name (ITF2 F.24). collected: the collection date (F.27), YYYY-MM-DD, YYYY-MM or YYYY. The collector's own number is fieldNumber, kept as typed.
  • idLevel (U, 0, 1, 2, 3, 4): ITF2's Verification Level (D.1). idBy: who identified the plant (D.2). idOn: when (D.3), a day, a month or a year.
  • exChain: an array of the plant's earlier holders, the most recent first, at most 12, each up to 80 characters. clone: a clone's name, apart from a cultivar.
  • idHistory: an array of the names the plant had before, the oldest first, at most 30. Each entry is an object with "name", "until" (the day it stopped being the plant's name), and the "idLevel", "idBy" and "idOn" it had then.
  • A rename line on the plant ("Renamed from Copiapoa cinerea to Copiapoa gigantea", with " to " once in it) whose earlier name the array lacks is shown as an entry, its "until" the line's day, and written into the array by the plant's next edit. A version before this one wrote the line alone.
  • Each of these is read and checked when it is read. A value of another type, a word or code this version does not know, or a day that is not one, is shown as not stated and kept in the log as it is.

event

  • acc: a record id, as above. d: YYYY-MM-DD; a plant's acquire line carries its date as read, so YYYY-MM or YYYY after an import.
  • t (acquire, repot, water, feed, treat, prune, flower, pollinate, fruit, seed, graft, measure, move, note, death, propagate, audit, germinate, potup, loss), and as the type needs: note, cause, used, and followUp in days.
  • measures: an object of named finite numbers: diam, h, spread, caudex and, on a repot line, pot, in millimetres whatever the display. Heads and leaves are counts.
  • n: a count: seedlings up so far, plants potted, plants lost. plants: on a potup line, the ids of the plants it made, so the line names them by their current numbers.
  • pollen: on a pollinate line, the pollen parent's record id. The line's own plant is the seed parent, so the line is a cross, dated by its d, and the seed lot a batch can be sown from.
  • scion and stock: on a graft line, the record ids of the plants the scion and the stock came from, either of which may be absent. The line's own plant is the grafted plant.
  • The three are read on their own kinds of line only. One that names the line's own plant, or no record id, is read as none.
  • auto: true on a line the app wrote by itself, a rename's note or a move when a space is removed, which never counts as the plant being seen. A watering the grower started for a whole space, from Today or the space's page, is the grower's and counts.

photo

  • acc or sowing, d, dFrom (exif or added), caption, w, h, bytes, and sha, the SHA-256 of the full-size JPEG, in hex.
  • Its pixels are stored separately under the same id, as the browser's own files. A browser that will not keep a file in its own database (Safari in a Private Browsing window) keeps the two JPEGs as plain bytes with their type instead. A backup carries them the same way.
  • A paper kept with a plant is a photo record too, with acc, d (the day it was added), bytes (the file's size), sha and caption.
  • It has three fields a photograph never has. mime is the file's type (application/pdf, image/jpeg or image/png), read from its first bytes. fileName is its name as added, at most 120 characters. doc (cites, phyto, invoice, other) is what it is.
  • A paper has no w or h. So a version made before papers keeps it as a record waiting for fields, never shows it as a photograph, and still syncs and backs up its bytes.
  • Its file is stored under the record's id behind a JPEG of one grey pixel, 159 bytes, and the thumbnail is that JPEG alone. Every version's backup reader takes both for JPEGs, and this one reads the file whole after the first 159 bytes. Its sha is of the stored bytes.

location (a space)

  • name, parentId, type, indoor, floorC, and floorHeld: true when the floor is a heater's set-point rather than what the space bottoms out at.
  • ppfd, lightHours, lat, lon and altM.
  • waterDays: water about every this many days, 1 to 365, which is what "due" means for the plants here. It is 21 when neither the plant nor any space above it sets one.
  • dryMonths: an array of months, 1 to 12, the plants here are kept dry and not due.
  • Both are inherited down the tree when null, the nearest space that sets one deciding. So an empty list sets no dry months over a parent's.
  • notes and sort. Temperatures are stored in °C whatever the display.

sowing (a batch)

  • no, taxonName, taxonKey, cultivar, nameKind, parentage, method, and parentAcc, a plant's record id.
  • sown (YYYY-MM-DD), count, sourceFrom, and sourceRef, the seller's lot.
  • fieldNumber: the collector's number, which the plants potted up inherit.
  • provenance, medium, container, treatment, bottomHeatC, covered, locationId, status, notes and notesBase.
  • cross: the id of the pollinate line the seed came from. stockAcc: for a graft batch, the stock's plant, by its record id; parentAcc is the scion's.
  • Every link between plants is a field on a kind every version reads, never a kind of its own: an older version folds them as fields it does not know, and shows a fruit line by its word.

taxon (a species you note or follow)

  • Keyed by the species' address, its name without a hybrid's sign, as the reference's addresses are: aloe-nobilis for Aloe × nobilis.
  • name: the species' name with a hybrid's sign. A record an older version wrote without it ("Aloe nobilis" for plants of Aloe × nobilis) is read as the plants' name, and is not written again.
  • gbifKey, myNotes, and myNotesBase: the base of the species' own notes, as a plant's notes have one; a text replaced blind is read from the log and shown under them. followed.

setting

  • One record, id numbering, with scheme: the numbering scheme every device shares.
  • And one record for each Replace, its id beginning numbers-kept, with accession and sowing: the plant and batch numbers this device had given that the file did not carry. So a number given once is never given again, and the log alone says so.
  • And one record for each pinned view, its id pin- and sixteen hex digits of a hash of its query, so a view pinned on two devices is one record. Unpinning removes the record.
  • A pin holds href (the page pinned), view (its browse query, such as ?r=NAM&f=apocynaceae), label, made and seen (days), n (its species when last seen) and keys (their page ids, written short; null for a view of more than 3,000 species).
  • The page ids are written as Kew's numbers in order, each as its distance from the one before in base-32 digits of a 64-letter alphabet, the last digit of each without its high bit; then ~ and GBIF's keys the same way.
  • A pin is a setting record, a kind every version reads, because a version refuses a batch that holds a kind it does not know, whole. A version made before pins folds them as setting records and shows none of them, but for its backup page, which calls a file's pins "the numbering scheme" when it merges the file. Each pin is checked when it is read; one whose fields are not a pin's is not shown, and stays in the log as it is. A field this version does not know is passed over.

The backup file

A backup is an ordinary zip you can open anywhere. It holds the whole log, your photographs and three spreadsheets. Restoring it merges by the log's rule, so restoring an old file over a newer collection loses nothing.

The format in full: the backup file

cultifolio-YYYY-MM-DD.cultifolio.zip, an ordinary zip:

manifest.json        { format: "cultifolio-backup", v: 1, exported: <ISO time>, device, app,
                       counts: { changes, accessions, events, locations, sowings, taxa, photos, photoBytes },
                       photosMissing: [ids of photo records whose pixels were not on the exporting device; absent when none],
                       parked: [stamps of the changes the exporting device had parked; absent when none] }
                       (photos counts the photographs actually in the file; the numbering scheme is a setting record in the log)
changes.json         a JSON array of changes, the whole log, as above
unreadable.json      the changes in the log this version cannot fold (a kind it does not know, a broken stamp, a field the record owns), as they are; absent when none
photos/<id>.jpg      full-size JPEG, long edge 1600 px
photos/<id>.t.jpg    320 px thumbnail
plants.csv           one row per plant, for a spreadsheet, with its record id in the last column; the import reads it back (the id and sowing columns are listed apart, and a line whose id names a plant here is that plant, left out)
batches.csv          one row per propagation batch, with its record id, its latest count, potted and lost figures (not for import)
events.csv           one row per timeline entry, oldest first, with the plant's or batch's record id, number and species (not for import)
device.json          the exporting device's settings { site: { lat, lon, name? } (as entered, not rounded), units, labels, prefs }; a restore applies each only where the device has none
  • The manifest's v is 3 when any change carries its recorded time (w), 2 when none does and the log holds a marked stamp, and 1 otherwise.
  • A version that reads 1 and 2 would restore a version-3 file without those times, and one that reads only 1 would park what every later version shows. So each refuses a newer file with a sentence ("This backup was written by a newer Cultifolio") rather than restore it. This version reads all three.
  • A change in either file that this version cannot read is named.
  • A change in unreadable.json that this version reads is read as any other change.
  • One it cannot read, but with a stamp, is kept as it is, appended to the log on a merge or a replace. The reading skips it and a later backup carries it again.
  • Sync does not send such a change, since a device that cannot read it would set aside the bundle it came in, until a version that reads it opens here and sends it.
  • One with no stamp, or with a value its field never takes, is left out, and a replace is refused, since it would lose it.
  • A replace is refused too while this device holds a change this version cannot read that the file does not carry, since a replacement clears the device's log. A merge keeps it.
  • A file none of whose changes can be read is refused.
  • Restoring merges by the log rule, so restoring an old file over a newer collection loses nothing, and restoring twice changes nothing.
  • The changes the file names as parked are parked here too, before anything is read. A replace takes the file's parked set in place of the device's.
  • While a replacement whose switch has begun is unfinished, nothing can be saved on the device, and Replace cannot start again, since it would delete the staged copy, the only one. The page that ran it says so and reloads.
  • A copy that cannot finish when the collection opens (the device still full) leaves the collection open on what was copied so far, says why, and finishes at a later load when there is room. The other open tabs are then told, and reload onto it.
  • One tab copies at a time. A Replace holds the browser's lock cultifolio-replace from its staging to the end of its switch. The other open tabs are told as the switch wipes the old log, and reload onto the new one.
  • A tab that opens the collection while a switch is under way waits for it, says so, and opens on the finished copy.
  • The switch replaces the log in one write, and deletes only the photographs the file does not hold before it copies the file's. So even two tabs running it at once, in a browser without Web Locks, lose nothing.
  • A Replace, and a Merge into a device that held nothing, count as a backup taken that day, at once, and the backup page says it was a restore.
  • A file names the app that wrote it. This version writes cultifolio 3 (stored parks) and lists only the parks its device stored.
  • A version-1 file naming cultifolio 3, or no app, came from an older version, which also listed parks of its clock alone. Its list is read as parks all the same: that version judged by its clock alone only changes that reached it by sync, whose clock and arrival verdicts agree. Each is offered with Apply, which undoes a wrong one.
  • In device.json, a site's name is read as Settings keeps one: control characters and runs of spaces become one space, and a name over 120 characters is cut at a word and marked.
  • Only the zip is read.

Sync on the wire

Sync uploads your log in sealed batches, and your photographs sealed one by one. Only a device with your key can open them. The server sees names, sizes and times, never what is inside.

The format in full: sync on the wire

The key, the token and the vault id

  • One vault key per person: 30 symbols from an alphabet without I, L, O, U, 0 or 1, in six groups of five.
  • From it, HKDF-SHA-256 with salt cultifolio-vault-v1 derives three 32-byte keys.
  • The input is the 30 symbols upper-cased, with every character outside A–Z and 0–9 removed. Dashes, spaces, a line break, and the cultifolio://vault?k= prefix of the pairing link are all dropped, as the app does to whatever is typed or scanned. It is the UTF-8 bytes of that 30-character string, not a decoding of it.
  • The three keys: an AES-256-GCM key (info enc); a 256-bit auth token (info auth, sent as 64 hex digits in a bearer header); and an HMAC-SHA-256 key for naming log batches (info name).
  • A log batch here is what the sync page calls a sync bundle: one device's sealed bundle of changes.
  • The vault id is 26 symbols made from SHA-256 of the string id: plus the token's 64 hex digits. Take the first 26 bytes of the digest and map each byte b to ALPHABET[b mod 30], where the alphabet is ABCDEFGHJKMNPQRSTVWXYZ23456789, the key's 30 symbols in that order.
  • It is not a base-32 encoding of the digest.
  • The server stores SHA-256 of token: plus the token, and compares. At creation, the one moment it sees the token itself, it checks that the id is the one that token derives, so a vault cannot be made under a name its key would not produce.

Sealed blobs

  • A photograph the server did not hand over in a run (an error answer) is asked for again at the next sync, and the sync page's status says how many were not received, never "everything is here".
  • A sealed blob is one version byte (1), a 12-byte IV, then AES-GCM ciphertext with its 128-bit tag appended, as WebCrypto does.
  • Its associated data is the UTF-8 bytes of vaultId|kind, where kind is log or photo, so a blob cannot be replayed into another vault or as another kind.
  • A photo's data also carries its id (vaultId|photo|photoId), so it cannot be handed out under another photo's id.
  • A log batch's data carries its name on the server (vaultId|log|batchName, without .bin), so a log batch cannot be posted again under a fresh name and opened there. A blob opens under its own binding and no other.
  • A log batch decrypts to { "v": 1, "device": "...", "changes": [...] }. It is "v": 2, the same shape, when any of its changes carries the mark, or when it carries "parked": [stamps]: the stamps among its changes its sender holds as parked. This version reads both.
  • An older version that writes log batches only as version 1 sets aside any log batch whose version is not 1, whole and under its name, for a later version to read. So a version that would read the mark as an ordinary counter, or would not read parked, waits rather than reading those changes differently.
  • A log batch of a version this build does not know is set aside the same way.
  • A change's w travels in the log batch as it is, with no new version: older versions keep a change's fields as they are, on the wire and in their own log.
  • A log batch is stored at vault/<id>/log/<hour>-0000-<device>-<fingerprint>.bin. <hour> is the hour, in ms padded to 13 digits, of the log batch's last change; <device> the pushing device's 12-character id.
  • <fingerprint> is the first twelve hex digits of HMAC-SHA-256, under the naming key, of exactly the bytes JSON.stringify(changes) gives in JavaScript: no spaces, keys in the order each change carries them. A serialiser that adds spaces or sorts keys gives a different fingerprint.
  • Every seal uses a fresh IV, so the same log batch pushed twice is different bytes under the same name.
  • The pushing device sends the full fingerprint (X-Batch-Plain) and its id (X-Device), both required. When both match what the server kept with the first copy, it answers that the log batch is already there and stores nothing.
  • Different bytes under a held name without that match are refused (409), so a name never stands for two contents.
  • The fingerprint is keyed, so the server holds nothing it could test a guessed plaintext against.
  • A log batch the device cannot open or check is set aside by name and reported, and does not stop the ones behind it.
  • A log batch that cannot be stored on the device (a full phone) is not set aside: the sync stops with an error and fetches it again next time.
  • Log batches are handed out in the order they arrived at the server, not in key order. A device that edited offline, and uploads after another device has pulled past that time, must still be found.
  • So a client asks for everything since a server arrival time, re-reads a minute of overlap, and skips log batches it already holds. Within one sync it pages on the pair (arrival, key), so many log batches arriving in the same second cannot repeat.
  • The changes inside carry the stamps that settle merges; arrival order only decides discovery.
  • A photo decrypts to a 4-byte big-endian length, the full JPEG, then the thumbnail. It is stored at vault/<vaultId>/photo/<photoId>.bin, or, stored again after a removal, at a later generation of that name (below).
  • No log batch or photograph is ever written over; a photograph's pointer is. Nothing is deleted but a removed photograph's bytes, at a device's request, and bytes an upload cut off left unnamed.

Clocks: held and parked changes

A device with a wrong clock could win every field it touches. So a change from the future waits until its time comes, and one from a clock that was badly wrong is parked until you apply it. A device also corrects its own clock by the sync server's.

  • A change stamped more than five minutes ahead of the receiving device's clock (a peer's, or one in a restored file) is stored but held out of the merge until that clock reaches it, and the plants list and Today say how many are waiting. Otherwise one fast phone would win every field it touched on every device.
  • That clock is the device's corrected by the server's: every sync answer carries a Date header, and a device whose clock disagrees with it by more than half a minute stamps its changes, dates its events and judges its holds by the server's time instead.
  • A correction of two days or more is taken only when two readings from two sync runs, a minute or more apart, agree. So one wrong answer cannot move a clock by years.
  • The correction is kept in the browser's storage (localStorage, under cultifolio.clockOffsetMs), is shared with the device's other tabs, and is cleared by Stop syncing.
  • No amount of time passing drops it: a slow clock does not catch up by waiting.
  • Within an open page the device clock is read against the browser's monotonic clock. A move of more than half a minute between the two is a move of the device clock.
  • A move back (the clock set back, by hand or by a time sync) first undoes the moves forward kept since the last reading, as far as they go: the clock set forward by mistake and put back.
  • Beyond that, it is followed only as far as a negative correction says the clock was fast. The correction shrinks by the move, so a fast clock set right needs no reading.
  • A move back further still is kept, not followed. Nothing says the clock was that far fast, and a clock left slow stamps behind, which parks nothing.
  • A move forward by about a positive correction is a slow clock set right, and is followed the same way.
  • Any other move forward is a sleep (some platforms pause the monotonic clock while the device sleeps) or the clock set forward. The two cannot be told apart, so the correction is kept.
  • The move is added to the moves forward kept since the last reading, which are stored with the correction, so a reload and the device's other tabs undo them too. Kept, a clock set forward stamps ahead by the move, and by any positive correction besides, until a reading.
  • After any such move, and at every page load, the correction is kept but unconfirmed, and a reading is asked for at once.
  • A reading that agrees with it to within half a minute confirms it, and the log is not read again unless the clock had not counted as confirmed before. One that disagrees replaces it, and the log is read once.
  • At a page load after the device clock has moved at least the correction since the reading that confirmed it, a positive correction of more than a day is not in force until a reading confirms it. A slow clock set right moves so, and so does a move forward past the correction.
  • A load before that keeps it in force. Until the reading the device stamps by its own clock, with one new reading of the log when it comes. So an edit made offline after a slow clock was set right lands behind, which parks nothing.
  • A page loaded that long after the reading waits even while another tab of this browser holds the correction in force. That tab writes the correction only at a reading or a move of the clock, so it cannot vouch for it.
  • Until its own reading such a page stamps by the device's clock, and an edit made in it offline can lose to another device's edit made before it and not yet seen.
  • Meanwhile the clock does not count as confirmed, so another device's change far past it is held, never parked.
  • An edit made in sight of a field is placed past the field's newest stamp, a held change included. A removal is placed past the newest held edit to any field of its record, and an edit past a held removal of its record. Each goes up to a day past the device's clock plus the stored correction.
  • A reading that disagrees, or a move of the clock shorter than the correction (a sleep), never takes a confirmed correction out of force.
  • A page's wait from its own load is its own. It never takes the correction out of force in another tab, and it ends at a reading, or when another tab with the correction in force writes it.
  • Being unconfirmed changes nothing else. Changes are stamped and dates read by the correction in force, and holds are judged by it. This device's own changes are never held or parked by its own clock.
  • Offline, a slow device whose clock was set right, and whose page was reloaded before any reading, stamps its edits by the old correction until the first reading, when that correction was a day or less; one of more than a day is not in force until a reading.
  • Those edits are then stamped by the device's own clock, and park nothing.
  • A device still slow then stamps behind until the reading. An edit made in sight of a field is placed past the field's newest stamp, another device's held change included, and a removal past another device's held edit to the record, so each still wins once the reading comes.
  • A first reading that disagrees with the clock in force by more than two days stops it counting as confirmed until a second reading agrees. The correction stays in force and stored meanwhile, so every open tab stamps alike.
  • A page loaded meanwhile holds a positive correction of more than a day out of force until its own reading, since no reading confirms it then.
  • What is kept: the correction, the device's and the server's time of the reading, whether a reading has met it since the last move or load, and the moves forward kept since the last reading.
  • A reading is trusted only while it is under a week old and not dated more than five minutes after the device's own clock. Five minutes of slack cover the reading's rounding and a clock nudged back by a time sync. A reading further in the future means the clock was set back since, so it confirms nothing, and at a page load its correction is not used.
  • A correction whose last reading is older than a week stays in force, but no change is parked by it alone.
  • A change stamped more than two days past the arrival of the log batch that carried it is parked, on every device including the one that made it, and listed with Apply. It is a broken clock's, kept in the log and never read on its own. The record it belongs to offers to apply it as an edit made now, so every device takes it.
  • Each device lists the vault, so it learns when its own log batches arrived, and judges its own changes by that arrival as it judges a peer's. A log batch of its own that may hold such a stamp is fetched again to be judged. A device that synced before this rule lists the vault from the start once.
  • A change this device made is never held, and is judged once its log batch is listed.
  • No device keeps a verdict of its own clock alone. Another device's change with no arrival to judge it by (one read from a file) is held as a peer's is, or, against a clock a sync server has confirmed, parked for that load only and judged again at the next.
  • A change read from a file is parked for good only if the file names it as parked.

Marked stamps

  • An edit always wins: it is stamped just past the field's current stamp, however far ahead that stamp is. Such a stamp carries a mark in its counter, the bit 0x800000, saying it was placed after the field's stamp and not read from a clock.
  • A marked stamp is never held or parked, on any device. So an edit made after a clock was put right shows everywhere, and a later edit anywhere is placed past it in turn.
  • A field, and a record's removal, are ordered by a marked stamp's place, just past the far stamp it was placed after, until real time reaches that stamp.
  • An edit or a removal made later elsewhere, on a device that had not yet seen the marked edit, sorts before it, even one made on a right clock. So every device shows the marked edit alike; it resolves by the stamps, not by when each was made.
  • The mark says how a stamp was made, and nothing checks it: it is trusted as the key is.
  • A device holding the vault key that marks a far stamp read from its own clock escapes the hold and the park. It wins the fields it touches until real time reaches the stamp, and raises no clock line; every later edit is placed past it in turn.
  • An older version from before the mark parks such a stamp. A log batch carrying one is version 2, which that version sets aside.
  • A number repair past a marked stamp is placed past it with the mark too.
  • A device still on an older version that renumbers the same plant places its own repair just past that stamp without the mark. When the stamp is a broken clock's, far ahead, this version parks that repair, and leaving it parked keeps one renumbering and one note.
  • No clock counts onto the mark: a counter one short of it moves to the next millisecond, its own or one it follows.
  • Each change this version writes carries the time it was made beside its stamp (w), so the app dates a marked change by when it was made. The order is still the stamps'.
  • That a device holding the key can mark any change is not a gap to close. A device holding the key already holds the whole collection, and can write any change to it.
  • A device whose clock was a few days fast, offline for a month and then put right, sends its last days of stamps less than two days ahead. Its peers hold them rather than park them.
  • A peer's edit to one of those fields, made meanwhile, shows until the held change comes due, and is then replaced by the older edit, with no notice. Every device ends the same.
  • Two words for the two states. A held change waits for the clock to reach its stamp, then is read by itself. A parked change stays in the log and is never read unless the grower applies it.
  • A held change that an edit here has since been stamped past will never show, and is not counted as waiting.
  • A parked change that an edit was since stamped past is no longer offered with Apply. Apply takes a record's latest parked removal or restore, by its stamp, and on a restore brings the record back.
  • A new vault is sent the parked changes too, with their verdict. The log batch lists them under parked, and a device reading it stores them as parked before it reads the rest, as it does a file's. Judged by the new vault's arrival alone, a change parked long ago would no longer be far ahead, and would be read there.
  • Apply sends one as an edit made now. "Apply all from this device" on the Sync page applies this device's own parked changes at once; a peer's are left for the grower to judge one by one.
  • A device whose clock reads earlier than its own latest change says so on its clock line. That acts on nothing, and edits still save and show.

On the device

The device keeps the log, and a snapshot of its last reading so a page opens quickly. The snapshot is only a cache: dropping it never changes what you see. A backup and a sync carry the log, never the snapshot.

The format in full: on the device
  • The log is kept as an IndexedDB store of changes keyed by t, with an outbox of the stamps the server has not acknowledged (none in the example) and the order the changes arrived in, a numbered row per change stored.
  • A photograph's pixels that nothing names are deleted from the device a few seconds after a page opens the collection, and after a Merge, with sync on or off. Those are the pixels of a photograph whose record is removed, and those with no change under their id two days after the time the id carries.
  • The state the pages read is a reading of the log. The device keeps the last reading as a snapshot beside it, with the arrival number it was taken at, so a load reads the snapshot and the changes that arrived after it, not the whole log again.
  • A fresh snapshot is written after a load that read the whole log, after one that read 1,000 changes or more on top of it, after an import, after a merge from a backup, and after the example is set out. The changes after it are read in one range read of the log.
  • The example collection's database keeps no outbox, since it is never synced.
  • The snapshot is only ever a cache of the log. It is dropped, in the same transaction, whenever the log is replaced from a file, a stored change is displaced by one that ranks higher under its stamp, or a change is parked on its arrival.
  • A change the reading parks itself is parked by every reading of the same log, so the snapshot stands.
  • A load that finds the log changed between reading the snapshot and reading what followed it reads the log instead.
  • The snapshot is not read when it was built under other reading rules; a deploy that leaves the rules as they were keeps it. Nor when it was built by another device, or under another stored clock correction, or with that correction confirmed by a reading where it is now not, or the reverse.
  • Nor when it read a change from another device that the clock in force now would hold. A page load holds a correction of more than a day out of force until a reading, so a snapshot written while it was in force is read by that load only when nothing it read is past that load's clock.
  • Dropping the snapshot never changes what a page shows.
  • What the snapshot did not read it names, every stamp. The held changes are judged again at each load and read as they come due, and the parked ones are read back so their Apply stands.
  • A backup carries the log, never the snapshot; a sync sends the log, never the snapshot. A device with no snapshot reads the log and is the same collection.
  • The database is at version 4. Opening it at a newer version tells a tab still running an older version of the app, which lets go of it once its writes in flight have landed and reloads into the newer one. So a tab left open across an update does not go on writing beside it.

The example collection

The example collection is a database of its own, kept apart from yours. Nothing of it reaches your log, a backup or sync, and leaving it deletes it. It opens only from its own button, never from a link.

The format in full: the example collection
  • The example collection (the sample, in the code) is IndexedDB cultifolio-demo, beside the grower's cultifolio. A flag in this tab's session storage (cultifolio.demo) chooses it when a page loads, so entering or leaving it reloads the page.
  • Which collection a page shows is decided once, as it loads. Its settings, the "keep data" question, sync and the front page's hint all read that decision, never the flag as it is later.
  • A device's own collection is empty when its log holds nothing at all: no plant, removed or not, nothing in Propagation, no species followed or noted, no space, no numbering scheme and no pinned view.
  • It also has no frost site, no change waiting for this device's date or parked, no replacement waiting to finish, no change this version could not read, and no sync set up. This is read once the collection and the sync key have been read.
  • On such a device, Today, My spaces and Propagation show their own empty state with one button under it, Show the example collection, which opens it on the same page. One sentence beside it says it is a sample kept apart from your own collection, which you can close at any time.
  • My plants, while it lists no plant, has the same button and sentence at its head, whatever else the collection holds.
  • Nothing opens it by itself: arriving on a page, by a tab, a link or its address, never does.
  • The button goes to its page at an address that says so: ?enter= and a one-use token the button writes in the tab's session storage, cultifolio.sampleEntering.
  • That page's first script sets the flag only when the token matches the one written in that same tab, taking the token off as it reads it, and the page then takes it off the address. So a copied link, a bookmark, the history or another tab's address opens nothing.
  • While it loads the page says "Opening the example collection". A load into it that a page calls off (a "Leave site?" answered Cancel) leaves the tab outside it, however soon the page is reloaded after, since nothing but the token was written.
  • In a tab whose session storage refuses the token, the button says so.
  • On a device with a collection of its own, Today, My spaces and Propagation show their usual empty state alone.
  • Nothing opens it while a restore, a merge, an import or a sync is in progress on the device; a button pressed then says why.
  • Anyone can open it from the menu, a grower with plants too. The menu moves to Today first, so a page with something typed on it asks before it is left. Their own collection is left as it is, and Leave returns to it.
  • Leave goes to the front page, and Add your first plant (offered to a visitor) to the add form, both in your own collection, never back to the page that opened the example. Both ask first when you added or changed records in it.
  • So does every other way to add something of your own from inside the example (the top bar's +, Add one to my plants, New space, starting a propagation, Import). It leaves the example first, for the same page in your own collection.
  • An add form reached inside the example says that what is added there joins the example and is deleted with it.
  • Keep it as my own leaves for the same form in your own collection, with everything typed on it. That is every field (on the propagation form, all but the parent plant, which is the example's), kept for that one move in the tab's session storage, read once by the form and taken off. Nothing typed goes in the address.
  • The space goes by its name and kind, with the name and kind of the space it sits inside. Your own space of that name is picked; otherwise the space picker's New… opens with it filled in, inside your own space of the containing space's name, or at the top level with a line saying where it was.
  • The form's own "Leave site?" is not asked then.
  • When the tab's storage refuses to keep what was typed, Keep it as my own does not leave the example. It says so, and the form stays as it was.
  • The example's bar says that nothing added in it is kept. While a page shows the example, its top bar says Example.
  • Nothing of the example reaches the grower's own log, settings, a backup or sync, and leaving it deletes its database whole.
  • Leave goes to your own collection first, at an address that says so: ?left= and a one-use token Leave writes in the tab's session storage, read by the page's first script and then taken off the address. The first page there deletes the example, once every other example tab has let it go.
  • The address takes a tab out of the example, and marks the example for deletion only when its token matches the one Leave wrote in that same tab. So a copied link, a bookmark, the history or another tab's address deletes nothing.
  • A page that asks "Leave site?" (an unsaved form) and is answered Cancel stays a working example tab, and that Leave is called off. A later reload or closing the tab keeps the example, and the Leave button comes back.
  • When you added or changed records in the example, Leave says how many and asks first. A deletion held up because another tab still has the example open is said, and finishes when that tab closes.
  • Its settings are its own, and no cookie is written from it. In the example, units, the label sheet, preferences, the site, the last spaces chosen, the species compared and the plants picked for labels are kept for that tab only, in its session storage under cultifolio.demo. and the key's name.
  • Those keys are cultifolio.demo.units, cultifolio.demo.labels, cultifolio.demo.prefs, cultifolio.demo.frost.site, cultifolio.demo.theme, cultifolio.demo.lastLocation, cultifolio.demo.lastSowLocation, cultifolio.demo.countMode, cultifolio.demo.compare, cultifolio.demo.report and cultifolio.demo.labelsPicked.
  • Settings, Sync and Backup are shut there. A restore refuses to start in it, and so does sync, in the code and not only on the page.
  • It offers no watering calendar file and no spreadsheet of its plants. Where a page says how your collection is kept (Today, My plants), the example says it is kept nowhere and is deleted when you leave it.
  • Its frost watch says it has no site of its own (none is made up for it), and that yours is set on Today or in Settings once you leave.
  • It is set out in one commit (one transaction of the database, holding every change of the example), by one tab at a time. The tab holds a browser lock named cultifolio-sample-seed; without these locks, a claim in its own database that lapses after a minute and that only the tab holding it clears.
  • The commit is refused, setting out nothing, when the example already holds a seed's mark, when its log already holds anything of yours (read in that same transaction), or, without the locks, when the claim is no longer that tab's.
  • An example that already holds records of yours is not set out over, and its bar says so.
  • That same commit marks it as set out and notes the arrival number of its own last record (demoSeeded and demoSeedSeq in its database). What arrives after that number is yours, and is what Leave counts.
  • A page reloaded while it is being set out sets it out again. A change that fails leaves it to be set out on the next load. An example whose marks are missing (set out by an older version) is marked from its own records and never set out twice.
  • Each tab in the example holds a browser lock named cultifolio-sample-open, taken by the first script of each of its pages before anything else runs, so a tab that is only reloading still holds it.
  • A page outside the example deletes an example database that no tab holds and that holds nothing you added or changed. So one left by a tab closed without leaving does not come back stale.
  • One that holds records of yours is kept, and offered back on each page until it is answered: "You left an example collection with 3 records you added or changed there", with Open it, Delete it and Not now.
  • Not now is noted in its database as demoOfferedSeq, and it is not offered again until it changes. One in which nothing has changed for 30 days is deleted, answered or not.
  • A browser without these locks cannot tell an open example from a left one, so there the leftover is kept rather than risk deleting one open in another tab.
  • Leaving tells the example's other tabs, on a channel named cultifolio-sample, and they go to your own collection and say why. A tab that learns it from the database instead does the same.
  • Every Leave that is not called off, and every deletion of the example, also writes a new generation to local storage (cultifolio.sampleGen).
  • A tab that was away when another left (another site in it, a page kept in the browser's history, a tab the browser put away) compares it with the one it opened the example under. It opens your own collection on its next load, saying why.
  • From that moment such a tab saves nothing more and never opens the example's database again. A page with something typed on it is not sent away: it stays as drawn, with what was typed still there to copy and a sentence saying why nothing more is saved, and its next page is your own collection.

Endpoints and limits

These are the sync server's addresses, and the limits it keeps so one visitor cannot fill it. Every refusal says why, and the device waits it out without losing a change. Receiving goes on while sending waits.

The format in full: endpoints and limits
  • POST /api/sync/vault with { id, token, create }.
  • GET /api/sync/log?vault=&since=<ms> returns { batches: [{ key, at }], more, next?: { at, key } }. The next page is &after=<at>:<key>.
  • POST /api/sync/log?vault= with headers X-Batch, X-Batch-Plain and X-Device.
  • GET /api/sync/log/<hour>-0000-<device>-<fingerprint>?vault=: the log batch's name, as above, without the .bin.
  • PUT|GET|HEAD|DELETE /api/sync/photo/<id>?vault=. A DELETE comes from a device that has read the photograph's removal, ten minutes on, asking for its bytes to go. They come off the vault's count, and a 404 is taken as done.
  • The PUT carries X-Photo-Drop: the HMAC-SHA-256 of drop:<id> under the vault's naming key, which the server keeps with the object. The DELETE must repeat it, or is refused with 403. So the token alone can add to a vault and never destroy in it.
  • All but creation take Authorization: Bearer <token>. Every request the sync engine sends carries X-Cultifolio-Sync: 1.
  • A write with Origin: null and no Sec-Fetch-Site is taken as the site's own only when it carries that header. That is what a browser from before Sec-Fetch-Site (Safari before 16.4) sends for this site's own requests, under its no-referrer policy. Any other write that names another site is refused (403).
  • A page on another site cannot send the header without asking first, and this site never says yes.
  • A body larger than the limit is 413. A vault with no room left (2 GB) is 507 with { error: "vault full", bytes, limit }, and the device stops sending and says so rather than splitting the log batch.
  • A photograph or a paper is refused with that 507 once the vault holds 2 GB less 64 MB, its limit that figure: the last 64 MB is kept for log batches, so changes still sync. The device then sends its log batches as before, holds its photographs and papers, and says so.
  • A log batch the server refuses (400, 409 or 413) is halved down to the changes at fault. Those stay in the device's log and outbox, are said on the Sync page apart from what waits to be sent, and are sent again a day after the refusal, not at every run.
  • A refusal the sync code makes itself is JSON with an error. One the framework makes (a bad vault id, a missing token, a body past the limit) is JSON with a message. A fetch of a log batch or photograph that is not there is a plain-text 404. The device shows whichever of the two fields the body carries.

Limits for one address

  • One address (an IPv4 address, or an IPv6 /64) is bounded per day: 5 new vaults and 3 GB stored.
  • It is bounded per ten minutes: 600 requests to open, list and push, and 3,000 to fetch or store single log batches and photographs.
  • Past any of these the answer is 429 with Retry-After in seconds; for the new vaults and the bytes of a day, to midnight UTC. The sync page says the server refused, with the reason it gives.
  • Any 429 is waited out until its Retry-After, ten minutes at most on a listing or a fetch.
  • A 429 to an upload asking a minute or more is kept with the vault's sync state, so a reload or another tab waits too. It waits until its Retry-After or within the hour, whichever comes first, and for the bytes of a day until the time the server gives, a day at most.
  • Meanwhile nothing more is uploaded. Under the bytes of a day only photographs and log batches over 16 KB wait, and a smaller log batch, which the day does not count, still goes.
  • A shorter refusal met by such a log batch (a 503, or a request window's 429) leaves the day's wait standing and is kept beside it. So no log batch is sent, by any tab or after a reload, until it ends.
  • A photograph that does not finish uploading within three minutes waits two minutes, then four, eight and sixteen at most after each such photograph in a row. Records still go, and changes from other devices still come in. Receiving goes on.
  • A log batch of 16 KB or less is not counted against the address's or the /48's bytes of the day, only against its vault.
  • For an IPv6 address the /48 around it is counted as well: 20 new vaults a day (past that, 429 to midnight UTC with "too many new vaults from this network today").
  • And 12 GB stored a day (past that, 429 to midnight UTC with "the upload allowance for this network is used up for today"), kept by the counter object. The /48's requests for opening, listing and pushing, for single log batches and photographs, and for the reference's index and sheets are counted too.
  • For an IPv4 address the /24 around it is counted for the requests for opening, listing and pushing, for single log batches and photographs, and for the index, at four times one address's allowance, as a /48's are. Past that, 429 with "too many requests from this network".

Vaults for everyone

  • New vaults are bounded for everyone too.
  • A new vault takes its place among the day's new vaults and the vaults in all (200 a day and 2,000 in all by default; a deployment may set others in the Worker's variables SYNC_VAULTS_PER_DAY and SYNC_VAULTS_MAX, so this site's may be higher) when its first log batch or photograph is stored.
  • It takes none when it is made, so a vault made and never used takes neither.
  • A vault keeps its place while it is used. If its first upload does not land, the place is given back, unless another upload of it is still landing.
  • A vault with no upload for 90 days gives its place back at the next midnight UTC. The server first writes the time into the vault's own record (reclaimedAt in its meta.json), then gives the place back.
  • Nothing the vault holds is touched, and every device can still read it, but reading keeps no place.
  • Its next upload takes a place again among the vaults in all, not among the day's new vaults, and only once that place is checked. If the counters cannot be read, the upload is refused with 503 and Retry-After: 60.
  • If no place is free, it is refused with 503, Retry-After: 3600 and a sentence that says so ("Sync is full for now. This vault had no upload for 90 days, so its place was given back. …").
  • A vault made by an older version of the server, with no place recorded, is recorded at its next upload and not counted again.
  • When the day's places are taken, a vault that holds nothing yet has its uploads refused until midnight UTC.
  • A network (the IPv4 /24 or IPv6 /48 around the uploading address) may take 10 of the day's places. Past that its empty vaults are refused until midnight UTC too, with "Sync has taken all the new vaults it takes from this network today…". When the places in all are taken, they are refused until more are added.
  • Past either ceiling the answer is 503 with Retry-After and a sentence the sync page shows.
  • Joining a vault never takes a place. A joined vault that holds nothing yet is counted at its first upload like any other.
  • A device given that answer keeps receiving, sends nothing more until the Retry-After has passed or within the hour, whichever comes first, and shows the server's own sentence. The refusal is kept with the vault's sync state, so a reload or another tab waits too.
  • A 503 asking for less than a minute (a photograph another device is storing, a count that crossed an upload) is not kept: the device tries again then.
  • A photograph another device is storing or removing is answered with Retry-After: 10, whatever is left of that device's hold, so one photograph never holds up the vault's other uploads.
  • A 503 with no Retry-After is taken as five minutes and kept like any other refusal, as "The sync server is not taking uploads from this vault just now." when it carries no sentence.
  • An upload that would make a vault's first object is 503 too, with Retry-After: 60, when the counters cannot be read at all. An uncounted vault is one the ceilings never saw, so it is refused rather than stored ("The site could not count this vault just now; try again in a minute.").

Hourly limits for one vault

  • A listing of a vault holding more log batches than one listing can walk is 503. So is a listing past the vault's hour of listings: 1,200 pages of a thousand log batches in any sixty minutes.
  • Listings are counted in the vault's counter object by the minute each is asked. Each listing's most pages, 50, are counted when it is asked, and what it did not use is given back, so listings under way at once count too.
  • The server finishes a listing, and settles it, even when the device has gone. A reservation not settled within a minute, as when the server itself stops partway, lapses. No sixty minutes hold more than 1,249 pages of listings that settle.
  • The refusal carries Retry-After to when enough of the oldest pages have left the count, 61 minutes at most, and "Receiving is refused for now: …".
  • The device keeps a wait of a minute or more in its sync record (an hour at most), so no tab of it and no reload lists again before then. It receives again then, and its uploads go on meanwhile.
  • A vault may take 3,600 log batches and 3,600 photographs in any sixty minutes, each counted apart in its counter object by the minute the upload is taken (an upload that then fails still counts).
  • Past either, the next upload of that kind is answered 503 with Retry-After to when enough of the oldest have left the count, 61 minutes at most, and "Uploading is refused for now: …" or "Uploading photographs is refused for now: …".
  • The device keeps every change and sends it then, keeps receiving meanwhile, and past the photographs' hour still sends its record changes.

How bytes are counted

  • The byte counts live in a counter object (a Durable Object), one per vault and one per address. Each upload's bytes are checked against the allowance and taken in one step, so two uploads in the same instant cannot both pass on the same figure.
  • An upload not yet written is held as a lease on its bytes, released when it lands or fails, and lapsing by itself after ten minutes. So an upload whose Worker stopped midway cannot hold its bytes for good.
  • A removal is held the same way, with no bytes, from just before it deletes until its bytes are given back.
  • A photograph being stored and a removal of the same photograph wait for each other: a 503 with a short wait, which the device retries.
  • A removal made before an upload of that photograph claimed it leaves the photograph in place (409). The DELETE carries the removal's time in X-Photo-Removed-At.
  • An upload claims a photograph's name for two days, and only an upload that carries the photograph's removal proof claims it, whatever it is answered: stored, already there, or 409 for different bytes, which is what an Undo sealed again sends. So a first upload that lands after another device removed the record is removed once its claim is two days old.
  • An upload whose proof does not match is answered at once (200 for the same bytes, 409 for others, 403 for a removed photograph), and holds the photograph's name for no time at all, so it cannot keep a removal waiting.
  • The proof is checked before anything else.
  • A device answered 409 does not take the removal as done: it asks again at a later sync, at most once an hour. The time it was last answered is kept in the sync record, so a reload or another tab waits too. It asks until the server removes the bytes (a success or 404) or the photograph is live again.
  • A 403 (a proof that does not match the upload's) is said once on the sync page and not asked again.
  • A listing of the vault puts its total right once a day, on an open at most once an hour, and at the next request after an upload's lease lapsed, the open leases added to it.
  • It is kept only if no upload landed and no removal was made while it was being taken, and none is still between the bucket and the count. While one is, no listing is made at all.
  • After two tries that end that way, the request is answered 503 with Retry-After: 30 and the device tries again; opening or joining a vault waits that out and asks again, at most twice. An open of a vault whose count was already put right that day answers that count.
  • The midnight sweep gives places back a page at a time, each page and the lowered count of places in one step, so a sweep cut short loses no place.
  • Without the counter object bound, KV keeps the counts by read and write, which bounds the totals but cannot make them exact. It counts a vault's place once, by a key of its own, and does not reclaim places.

Photographs by generation

  • A photograph is stored by generation. Its first is at vault/<vaultId>/photo/<photoId>.bin.
  • A photograph stored again after its removal is a new generation, at vault/<vaultId>/photo/<photoId>.g and base-36 digits. A pointer at vault/<vaultId>/photoref/<photoId>.json names it.
  • The pointer is { g }, the generation that holds it (bin for the first), or after a removal { g: null, drop, at, was }, the removal's receipt: its proof, its time and the generation it removes. Each carries a random n that makes every write of it its own.
  • A removal renews its hold, and moves the pointer to its receipt only if the pointer is still the one it read (the bucket's own conditional write). Only then does it delete the generation it looked at. So a removal that stalls anywhere can remove nothing but that generation.
  • An upload with the proof that finds the photograph already there (a retry after a lost reply, or an Undo) moves the pointer too, naming the generation it found. So a removal that read the pointer before it, and stalled past its hold, finds it moved, removes nothing and is answered 409.
  • If a stalled removal's pointer write lands first, the upload is asked to wait ten seconds, and then stores the photograph again as a new generation.
  • A removal cut off after its receipt was written (the bucket's delete failed, or the server stopped) is finished when the device asks again. The receipt names the generation; a request with the removal's proof deletes it, gives its bytes back, and is answered as a removal made. So the 404 a device takes as done comes only when nothing is left.
  • A photograph whose name holds a receipt is stored again only with the proof the receipt holds (403 otherwise). So the token alone cannot put back a copy of a removed photograph.
  • Photographs stored before the server kept generations stay where they are, as their name's first generation. The pointers are not counted against the vault's 2 GB.
  • Bytes that nothing names (an upload cut off between storing a new generation and naming it, or a generation a cut-off removal left behind) are removed once ten minutes old. That happens at the next touch of that photograph, or by the vault's own sweep, whichever comes first.
  • A touch is its next removal by a device holding its proof, its next storing, or an upload that finds it already there.
  • Before a removal moves a pointer, and before an upload stores a new generation of a removed photograph, the server marks that photograph in the vault's counter object. If it cannot, the request is answered 503 with Retry-After: 10 and nothing is changed.
  • At midnight UTC the vault's counter object looks at each photograph marked at least ten minutes before. It holds the photograph's name (an upload or a removal of it waits ten seconds meanwhile), reads its pointer, and lists its generations.
  • It removes each generation the pointer does not name that is at least ten minutes old, giving its bytes back as a removal does.
  • Before it removes any, it writes the pointer back as it read it, under the condition that it is still the one read. So an upload whose own pointer write stalled cannot land afterwards and name bytes that are gone. An upload or a removal that finds such bytes does the same, and an upload renews its hold just before its pointer write.
  • The generations are listed a thousand at a time, at most five thousand at one look, and the mark stays until a listing that reached the end finds nothing unnamed. So a photograph with more is looked at again the next midnight.
  • A photograph with a younger unnamed generation, or whose name is held, is looked at again the next midnight. The mark goes once nothing unnamed is left.
  • A photograph the sweep cannot read (its pointer cannot be read, or the store fails for it) loses nothing: nothing of it is removed, and it is looked at again the next midnight.
  • After seven such nights its mark is dropped, and the night is counted among the server's faults, by kind alone (Cloudflare's request logs are off, so no log keeps its name). Anything of it left unnamed goes at its next touch instead.
  • A removal or an upload that cannot read the pointer is asked to wait ten seconds and ask again. It is never told the photograph is already gone, and never stores over it. A GET or HEAD of it is answered 503 with Retry-After: 10, never 404.
  • The sweep looks at 100 photographs at a time and goes on a second later until none is left.
  • A vault with no removal and no photograph stored again since its last sweep costs nothing; each marked photograph costs one read and one listing, once. Until then such bytes count against the vault's 2 GB.
  • Without the counter object bound there is no sweep, and they go at the next touch.
  • A removed object's bytes are given back once, under its name and version, however often the removal is asked for.

What the server can see

The server holds sealed blobs it cannot open. It can see when and how often each device syncs, and how large things are. It cannot see a plant's name, a note, a space, a date or how many plants you have.

The format in full: what the server can see
  • It holds a vault id, a hash of the token, and sealed blobs, and it cannot open any of them.
  • The blob names, sizes and arrival times are in the clear. A log batch is named by the hour and device id of its last change, and a photograph by the time of its creation (before October 2026, its device id too).
  • A sealed photograph is its full JPEG, plus its 320-pixel thumbnail, plus 17 bytes (a 4-byte length, the version byte and the IV), plus the 16-byte tag.
  • So the operator can count the devices in a vault, see to the hour when each one made changes and to the second when it synced, and count the log batches (roughly, how often changes are made) and the photographs. The operator can read their sizes, and see which photographs were removed or stored again.
  • This is not zero-knowledge in the strict sense: the pattern of activity is visible, its content is not.
  • Nothing about the plants themselves (names, notes, spaces, dates, the number of plants) is visible.
  • Anyone holding the bearer token (derived from the key, but it could be captured from a device) can add log batches to the vault, which the devices then set aside as unreadable, and can read the ciphertext. The token cannot delete a photograph, since removal needs a proof only a key-holder can make, and cannot read anything.

The reference lookups

Your own pages need the reference's figures for the species you grow. They ask for a group of a few hundred species at a time, never for one by name. So the server cannot tell which of them you grow.

The format in full: the reference lookups
  • A plant page, a batch page, Today, the labels, the plants list and the front page's own tiles need the reference's figures for your species. They ask for them by hash group, never by name or key.
  • The species' address is hashed (FNV-1a) into one of a number of groups. The count is a power of two from 32, the smallest that keeps a group at 320 species or fewer, chosen by the build for the catalogue it writes and announced by /api/corpus as buckets.
  • So a group never grows past 320 species, and once the catalogue holds more than 5,120, none holds fewer than about 160.
  • The device asks /api/sheets?b= or /api/entries?b= for the groups it needs, naming the count it hashed by (&n=), and picks its own species out of the answer.
  • A count that is not the one served is refused with a 409, and the device reads the reference's version again.
  • A group that cannot be read is answered 503 with a Retry-After of at most thirty seconds, and the server process that refused it does not try that group again for those thirty seconds.
  • Under a published reference a group's sheet file is always one the build wrote. If it cannot be read, the group is answered that way, and the server does not rebuild it from the species' own files.
  • The server sees which groups a device asked for, which narrows each species to one of its group's, and no more. A species page you open is, of course, a page you opened.
  • A search typed on the front page, in the search box at the top of every page or on the compare page, a name typed in the species picker as typed, and a name in an import the groups do not settle, go to /api/search?q=. The answer is kept a day in the site's cache under that text, linked to no address, since it is a question about the catalogue, not about your plants. The box's words also go to /api/suggest?q=, kept five minutes.
  • What is searched on the device is never sent: the text typed on "Your species", and anything typed before your collection has opened.
  • Nor is anything shaped like a plant number: two to four digits and another, a dash between or not, as 2026-0013; under a prefix scheme, the collection's prefix followed by a dash or a digit, as ACC-0013; or a batch's number, as S2026-001.
  • The catalogue's rows you scroll or jump to by letter are asked for by position (/api/rows: a grouping and a row number, nothing of yours).
  • The service worker keeps those answers under the reference's id (each request carries it, from /api/corpus), so a second visit asks nothing until the reference is refreshed.
  • The reference's photographs are not fetched for your own pages unless you switch them on in Settings. Then they come from the image host directly, which sees which species this address asked a picture of.

The search's order is set out on How it is made. Here is how a query is read, and what /api/search answers. Every header it adds says what it did to the words you typed.

The format in full: search
  • Search puts a name typed as a name first, then an older name typed as one, then a query read whole against each English name (every word in one name, never words of two), then every other match.
  • An older name typed whole that a species holds exactly comes before a name whose genus the query only begins: "Tecoma speciosa" is Handroanthus speciosus and Campsis radicans before Tecomanthe speciosa.
  • Within each, for an older name: a species that holds it exactly, then the species that keeps its epithet, then one that shows the name itself.
  • Then a name that is exactly the query, then whole words, then a match whose headline holds every word. Among English names, the matching name's place among the species' names, then a name written as typed, then more photographs; then the alphabet.
  • Apostrophes are taken out before a name is split into words. A family is matched whole, or from its start by a word of six letters or more that is neither a genus of the reference nor a word of the entry's own name.
  • Every older name of species rank is searched, not only the six an entry shows, and so are the names filed under the species' own varieties and subspecies.
  • A query is read as a botanical name where var., v., variety, subsp., ssp., subspecies, f., fo. and forma are skipped, what follows cv. is a cultivar and is not searched, and a word in a script the search cannot read is left out, and said.
  • "cf.", "cfr.", "aff." and "nr." are skipped as "x" is, and so are "vel" before "aff." or "cf." and "near" between two words of a name. "sp.", "spp." and "nov." end the name.
  • "x" or "×" marks a hybrid, and the word after it starts a name again and is never an author.
  • An author pasted after the name is ignored: a bracket, "&", "ex", or a capitalised abbreviation longer than four characters such as "N.E.Br.". After an epithet or a rank only, a shorter one such as "L.", or any word ending in ".", such as "l." or "mill.". And a capitalised word after an epithet of four letters or more.
  • A quoted text that begins with a capital, after a word of the name, is a cultivar and is not searched, in straight or curly quotes, single or double. One that holds an apostrophe ('Wendy's Gold') is not read as a cultivar, and its words are searched.
  • Every English name of a species' entry is searched, not only the first. The entry holds the names a source marks as English (lang "eng"), and, in spellings alone, searched and never shown, the names NCBI's taxonomy gives with no language; never another source's row with no language.
  • The query is NFKC-normalised, and loses its format characters (a zero-width space, a soft hyphen) first.
  • When nothing matches exactly, one typing error per word of four letters or more is forgiven. After a capitalised first word, a capitalised word is matched only against a whole word of a name, never the start of one.
  • Then the first two words of the name are searched, before any rank, "sp." or quoted cultivar. A hyphenated epithet is one word; a hybrid formula is searched on its first parent; a single letter is never searched again.
  • Last, a query whose first word is capitalised and whose second begins with a capital is answered with the species of its first word, when that word is a genus of the reference, or one typing error from one, at four letters or more. Otherwise with nothing.

What /api/search answers

  • /api/search?q= answers a list.
  • Whenever the answer used other words than those typed (the search on fewer words, the genus answered last, or a reading that left out an author, a cultivar, "sp." or a word it cannot read), the X-Search-Relaxed header carries the words searched, URI-encoded.
  • When a reading matched and left words out, and the query was not searched again, X-Search-Left carries those words as typed, URI-encoded.
  • When the hits came by a forgiven typing error, X-Search-Near: 1.
  • When every word of a query of two words or more, or a word with a typing error, begins words of more than 2,000 species, the answer is empty and carries X-Search-Narrow: 1. So it is when a typing error's similar spellings would mean reading more than 12,000 species or ranking more than 2,000.
  • A region of origin named whole, every word of it that common, is answered from the reference's own best hundred instead.
  • &n= asks for at most 100 hits (60 when not given), and &at= for those after the first so many (at most 2,000).
  • X-Search-Total carries how many species match, when it is known. X-Search-Kept carries how many of them can be listed, when that is fewer (a word so common that only its best hundred are kept).
  • X-Search-Regions carries the regions of origin the query names, as URI-encoded JSON, each { name, row: { id, label } } with the Origin grouping's row it is part of.
  • With &shape=2 the answer is { hits, relaxed?: { query, left? }, near?: true, narrow?: true, total?, kept?, at?, regions? }.
  • /api/names?q= takes letters, marks, spaces, ".", "'", "’", "-", "&" and "×", NFKC-normalised, and answers 400 for anything else, such as a digit.

The species picker

  • A name picked in the Add form's species picker replaces only what it names. A qualifier, a cross's parentage and a cultivar are kept as typed.
  • A rank with its epithet is kept (written var., subsp. or f.) when the species picked has the epithet typed. The reference key is filed only when the name filed is the picked taxon's own.
  • When a pick leaves typed words out (an author, a locality), the text as typed is kept as the plant's name as received.
  • A nothogenus keeps its sign (× Gasteraloe), and a field number after the genus (Gymnocalycium LB 123) is kept as written.

Import, the watering calendar and the label code

An import reads a pasted list or a spreadsheet on the device, and shows you every line before anything is saved. Nothing in the sheet is dropped unseen. Running the same sheet again adds only the plants still missing.

The format in full: import, the watering calendar and the label code

Reading a sheet

  • Import (My plants, Import) reads a list pasted one plant per line (name; cultivar; number; where it came from; notes, separated by semicolons or tabs). Or it reads a CSV sheet with a comma, semicolon or tab separator, quoted cells and an optional byte order mark.
  • It is read on the device, and nothing in the sheet is dropped unseen. Cells are kept as text and never evaluated. A cell written ="0012", as the backup's sheets write the shapes of text listed below, is read as 0012, and a note keeps its own spaces and line breaks.
  • A column no field takes is listed before the names are checked and, unless you untick it, added to each plant's notes as "Column: value".
  • Genus and Species in two columns make one name.
  • A name cell is read with its compatibility forms folded (full-width letters, ligatures, a no-break space: Unicode NFKC), and its invisible format characters taken out (a soft hyphen, a zero-width space, a byte order mark). A joiner inside an emoji is kept.
  • A cell that held a soft hyphen, a zero-width space or full-width letters keeps its text as the plant's name as received.
  • A Qty of 3 is three plants, and a Qty of "3.0" is three plants. A part of a name in brackets is kept with the name as received.
  • "cf." (or "cfr."), "aff." (or "vel aff."), "nr." (or "near"), "sp." and "nov." stay in the name, written one way, whether before the genus or after it. A name in quotes after "sp." is the undescribed species' own.
  • The reference is asked about the species part only, so such a plant is filed with no reference key. Its label's care line says whose care it borrows ("care as for C. cinerea").
  • A cultivar in any quotes, straight or curly, single or double, is read as a cultivar.
  • A plant filed under a name other than the sheet's (a suggestion used, a name edited in the review, a word not read) keeps the sheet's text as its name as received. "Use it" puts the suggested species in place of the species part only.
  • A name the reference holds as an older name of one species is said as that ("an older name: the reference has this species as …"). Its name can be taken on one line, on every line of the same name, or on every such line at once. A near spelling is offered line by line.
  • A Status or Kind the import cannot read is said on its line and kept in the notes, as Provenance is.
  • "Taken from" names a plant by its number, and "taken as" how (offset, cutting, division, leaf or bulbil). Once the plants are in, the number is read as the one plant of the import under it, else the one plant here under it, and linked. A number that names no single plant is kept in the plant's notes and said.
  • A word for how that is not one of the five is said on its line and kept in the notes.
  • A space path is split on " › ", after a space whose whole name is the cell.
  • When the sheet's space cells have a ">" between words (Greenhouse > Bench 2), a "/" with a space on each side (Greenhouse / Bench 2), or a "/" with no spaces between two words of three letters or more after a space here (Greenhouse/Bench 2), the review asks once whether to read those as paths too. The answer is yes by default when the first part names a space here or begins another such cell.
  • Nothing in brackets is a step, so Cold frame (N/S), S/W window and Shelf 1/2 are each one space.
  • A sheet with a quote that is opened and never closed is not read, and the page says on which row.
  • A row repeating the header is left out and counted, as is a line with no name.
  • A new space named in the paste's space box and not yet added is made when Check names is pressed, so every line gets it.
  • Names are checked against the reference: by hash group first, then by the catalogue's search for those the groups do not settle; never by GBIF's name service, which the Add form's picker asks.

Dates

  • Dates are read at the precision they are written at: a year (2009), a month (August 2017, 2017-08), a named month with a day, or a day and month where a number over 12, or the same number twice, says which is which.
  • A two-digit year is read after a day and month, as 20YY, and only when 20YY has come. So 1/1/27 is not read, since it could be 1927 or 2027.
  • A two-digit year is not read in three numbers joined by dashes, or when the first number could be a year too (24/03/09, 24.03.09, 05/01/24), which could be written year first.
  • That holds unless the sheet's dates are said to be written day first or month first, both of which put the year last (LibreOffice saves a date as 05/01/24 or 01/05/24, by its language).
  • Or year first, offered when the sheet holds a date that could be read so. It reads such a date with its two-digit year first (10-04-15 is 15 April 2010), and no other date differently.
  • A time after a date (09/03/2024 10:15) is not part of it. A day or month of 0 is no date. A year and a month joined by a full stop (2019.5) is a number, and is not read.
  • A month name and a two-digit number (Aug-17), as a spreadsheet writes a month, is not read, since the number could be the year or the day. Nor is a five-digit number (45123), which may be a spreadsheet's count of days: the line says which, with the date it would be.
  • A date like 09/03/2024, 05/01/24 or 19-05-23 is read only by one choice for the whole sheet: day first, month first, or year first where a date could be written so. It is asked whenever the sheet holds such a date, and left as written unless you make it.
  • The question names the day each answer reads, with its year, and says what the sheet's other dates show: a first number over 12 can only be day first, a second over 12 only month first. It chooses nothing for you.
  • A date in the future, or before 1900, is not read either.
  • A date not read is said on its line and kept in the notes as "Acquired (as written): …". Its plant is numbered for the year it names, or this year when it names none.

Numbers, and running a sheet again

  • A number already used here is replaced by the next free number. A number given twice in the sheet keeps it on its first line and is replaced on the later ones.
  • When the sheet's numbers share one pattern, the next free number is in that pattern, one past the highest of that pattern in the sheet or here, and unpadded when the sheet's numbers are.
  • One pattern means the same letters before the digits, and either as many digits (0001 to 0300, or A001 to A095), or no number padded with a leading 0 (1 to 300, or A9 to A95).
  • Otherwise, or past a padded pattern's last number (9999 for four digits), or past the largest whole number a browser counts exactly (9007199254740991), it is this collection's next number (2026-0009).
  • A sheet numbered as this collection numbers, over one year or several, is numbered by its rule.
  • The further plants of a line of several (Qty) that gives a number are numbered the same way, whether the line keeps its own number or not. The review says which, and the number it carried on from.
  • Each plant an import adds carries its line's import key. Running the same sheet again, or the sheet saved again by a spreadsheet or given a column, leaves out every line whose plants are all here, removed plants included. It offers only the missing plants of a line partly added, numbered on in the sheet's pattern.
  • The key reads a date by its exact day, so 2024-01-05 and 2024-05-01 are two lines.
  • A date cell that reads either way round (09/03/2024), left as written, is keyed by its year with day and month in either order. That also finds a plant filed under either reading. Answered by the sheet's choice, it is keyed by the day the answer reads, which finds a plant of that day, or one an unanswered run filed with no date.
  • A date whose two-digit year could come first or last (05/01/24) is keyed as such a cell is, by its readings with the year last; read year first, by the day it reads.
  • The key reads the notes as the plant gets them, the columns no field takes included. It reads a price as its amount: 12.50 and 12.5 are one, and £12.50 also finds a plant filed at 12.50.
  • A column added to the sheet leaves a line found in three cases: no other line of the sheet differs from it only there; or each that does is found by its own key; or the plants filed under the line without the column are as many as the lines sharing it that still lack a plant.
  • A plant filed from a line with columns no field takes keeps the line's key without them too, numbered after the plants of lines that had none, so a sheet that has lost those columns finds it.
  • While the plant's own line, those columns and all, is still in the sheet, that key finds it for no other line. So a line beside it with those columns empty is a new plant.
  • A plant an earlier version's import filed is found by that version's key only when its own date acquired and notes agree with the line.
  • A line whose number a plant here holds (compared without its leading zeros) looks already imported when the name is the same, or under any name when an import filed that plant (a name corrected since). The line names that plant when its name differs, and is skipped unless you add it anyway.
  • A line with no number whose name, date acquired and source match a plant an earlier import added from a line this sheet no longer has looks already imported, changed. It is said, and added unless you drop it.
  • The review before anything is saved says each.
  • My plants' Newest first orders numbers with their digits read as numbers (A95, A94, A77, A9). A search that is a plant's whole number lists that plant first.
  • The numbers shown in the review are the numbers given. The import gives each plant its number, and a number another tab takes meanwhile is replaced by the next free one, said.
  • One import is written at a time in this browser. Before writing, it reads what other tabs wrote, leaves out every plant whose import key is already here, and names the lines imported elsewhere. So a sheet imported in two tabs adds each plant once.
  • 2,000 lines are read at a time, the lines already here not counted. The page then offers the next lines of the same file, and a line you dropped in an earlier pass stays dropped, left out and counted.
  • Lines are written in groups of up to 50 plants, each group one write, so an import cut off partway keeps the groups before it. A group that cannot be written is tried again a line at a time, so the stop names its line.
  • A change to the date order, the notes box, a column, the header or the path question after the names are checked reads the sheet again at once, and says so.
  • A line of several plants bought at one price keeps the price on its first plant, and the others note "Bought with <number>, whose record holds the price.". A failure before the first plant says which spaces were made.
  • A last watering given for the whole list is one watering line per plant.

The backup's spreadsheets

  • My plants offers the plants sheet on its own too, as cultifolio-plants- and the day, .csv: the backup's plants.csv, written the same way.
  • Its columns, in order: number, species, cultivar, kind, parentage, name as received, field number, provenance, status, location, acquired, from, lot or reference, form, price, sowing and notes.
  • Then GBIF key, water every (days) and older name of. Then the identity and provenance, under ITF2's names where it has a field: item of, accsta, no longer held, no longer held on, no longer held note, prot, prohis, cnam, cid, field code, cdat, idql, rkql, vlev, vnam, vdat, vhist, ex and clone. Then taken from and taken as.
  • Then growing season, rest months (as Jun Jul Aug), season from, photographs (a count) and papers (each as its kind and file name, joined by semicolons). The id is last.
  • The import reads back by their heads the columns before GBIF key, but for sowing, and the identity and provenance columns, taken from and taken as. It lists item of, accsta, cid beside a field number, field code, idql and rkql apart, as restating other columns. It names the others apart. None is added to a plant's notes.
  • The backup's sheets write ="…" around the shapes of text a spreadsheet would change into a number or a date. These are a leading zero (0012), an exponent (1E5), a day and month (3-12, 1/2), a year and month (2026-01), a day, month and year (3-12-2024, 1/2/24), and a run of twelve digits or more.
  • A text a spreadsheet would read as a formula gets a leading apostrophe, and one that already begins with an apostrophe and a formula sign gets a second.
  • Only those shapes: text such as 3.12, 2026/01, Aug 2017, 1:30 or 50%, which some spreadsheets read as a date, a time or a number, is written as it is.
  • A price is written as typed and never quoted, since quoting it would break other readers; a spreadsheet may show 12.50 as 12.5.
  • A full date (2017-08-14) is written as it is. A spreadsheet takes it for a date and shows it in its own short form (14/08/2017 in Excel set to British English). A sheet saved again from the spreadsheet carries that form, which the import reads, asking once which way round a date like 09/03/2024 is.
  • A date kept as a month (2017-08) is one of the shapes above, so it shows as written, not as Aug-17.
  • In LibreOffice, tick "Evaluate formulas" when opening the sheet, or those cells show as ="…".
  • A plant's lineage is in the sheets by plant number. plants.csv has "taken from" and "taken as", which the import reads back. events.csv has a cross's pollen parent and a graft's scion and stock plants. batches.csv has the cross a batch was sown from, seed parent first, and a graft batch's stock plant.
  • A linked plant this file holds no record of is written by its record id.

The watering calendar

  • The watering calendar is an iCalendar file (cultifolio-watering- and the day, .ics, RFC 5545) made on the device. It holds one all-day event per space, and per plant with its own rhythm, repeating every n days (RRULE:FREQ=DAILY;INTERVAL=n) from its next due day.
  • Each has a reminder at 09:00 on the day (VALARM, TRIGGER:PT9H); some calendars use their own default instead.
  • Where a space keeps months dry, its rhythm is one series per run of watered months, for two years ahead. Each ends (UNTIL) on the last day before the dry months, and the next starts on the first day after them, the day Today lists the space's plants again.
  • A space kept dry in every month makes no event, and the page names it.
  • A rhythm that is not a whole number of days from 1 to 365 (one that came from a backup, an import or a sync) is written at the default of 21 days, and a plant's own at its space's.
  • Every event has a UID that carries a short tag of the collection (a hash of its earliest record's id), and a SEQUENCE that grows with each download. A series after dry months is named by the first day of its watered months. So a file downloaded again names the same events the same way.
  • Where any series stops at the two-year horizon, the file's last event, on the day the first one stops, says to download the calendar again. When other series stop later or repeat without end, it names the ones that stop that day.
  • A calendar keeps an imported event as it was, so the page still asks for the old Cultifolio events to be deleted before a new file is added.

Spent this year, and "No photo in 12 months"

  • Spent this year is read from each plant's price, by the year the plant was acquired, where the price is a plain number with at most one currency mark (12, £6, 6 EUR, US$12, R$ 30, 12 usd).
  • A thousands separator is read only where exactly three digits follow it (£1,250, 1.234,56 €), and a space too (1 200 €, a no-break or thin space as well).
  • "free" and "gift" count as nothing spent, and are said apart. Any other price is counted as not read, and the page says how many.
  • The names of one currency are one total: $, US$ and USD; £ and GBP; € and EUR; ¥ and JPY; a code in lower case as in capitals.
  • R$, A$, NZ$, C$ and Rs are each their own. Prices with no currency are a total of their own. Nothing is converted.
  • Today's line "without a photograph in the last twelve months" and the plants list's "No photo in 12 months" read one rule. A growing plant had six months or more, by its acquisition date or else the day its record was made, with no photograph dated in the last twelve months.
  • A date kept as a year or a month counts from its last day ("2026" as 31 December, "2026-04" as 30 April), so a plant is never counted six months old on a day its record does not give. The date itself is kept as written.
  • Both read today's date from the same corrected clock, as the local day where you are, so they always agree.

The label's QR code

  • The label's QR code is the plant's address by its number, /plants/<number>#i=<tag>&s=<species>&n=<name as printed>, the number escaped as an address needs. On label tape it is the address and the tag, /plants/<number>#i=<tag>, so the code is small enough to read at 9 mm. A batch's is /propagation/<number>.
  • The tag is six characters of base 36 made from the plant's record id: two FNV-1a 32-bit hashes of label: and the id, from the offset bases 0x811c9dc5 and 0x050c5d1f, each written in base 36 and joined, and the first six characters kept. The id itself begins with the time it was made, so plants of one import share its first characters, and the hash tells them apart.
  • A plant's page finds a plant by its number as by its identity, and with a tag opens it only when the tag is that plant's; otherwise it lists the plant the tag names and the plant holding the number, or says no plant here has the tag. A code printed before this carries the identity, /plants/<identity>#…, and opens the plant as it did.
  • The 12 mm tape's code is drawn at error correction L, so with the tag it stays at version 3, 29 modules a side; the other stocks' codes are drawn at M.
  • The part after # stays in the phone that scans it and is never sent to the server as written.
  • A phone without that plant shows the species the label names and a link to its page, after asking for that species' hash group (/api/entries?b=, as a plant page asks for its own). So the server learns the group, one species in a few hundred, and not the name.
  • The name in the code is cut to at most 60 code points, by whole characters as a reader sees them (a letter with its marks, a joined emoji), never inside one.
  • Every format character is taken out of it, closing the word up: text-direction marks, zero-width spaces and joiners, soft hyphens, tag characters. A joiner inside an emoji is kept.
  • A control character, or a line or paragraph separator, is made a space; a letter keeps at most two marks; and a broken character (a lone surrogate) is replaced, so the label keeps its code. This is done on the label and when a scanned label is shown.
  • A cross has no species page, so its code names no species, and its name is the cross's parents when they are known (Astrophytum asterias × capricorne), as its label prints it. A hybrid with a name of its own, such as Mentha × piperita, names its species as a species does.
  • An "sp." plant's code names no species either. A name that cannot be put in a code leaves that one label without its code, and the others keep theirs.

A species dossier

Each species page is drawn from one JSON file, its dossier, which anyone can fetch. It holds every figure the page shows, and a record of every source asked. A field a dossier lacks means it was not read, never "none".

The format in full: A species dossier
  • Each species page is rendered from one JSON document, served at /api/dossier/<id>, the page's id.
  • It is answered no-store and kept by no cache, since a dossier's address stays the same when the reference is refreshed.
  • A dossier the index lists but that cannot be read just now answers 503, never 404. A key the index does not list answers 404, whatever the group still holds.
  • A GBIF key in its place (/api/dossier/<gbifKey>) moves for the moment to the id of the page whose own GBIF key it is, and is a 404 where no page's is.
  • It holds: the name and classification; the native range as TDWG level-3 codes; the open occurrence points with licence tags; and the map marker and how it was placed.
  • It holds the climate envelope (the median year, the 10th and 90th percentile years, the cells and records it rests on, the typical cell) with its sources, and the extremes.
  • It holds the photographs with author and licence; licence is cc0, pd, by or by-sa. pd is public domain that is not a CC0 waiver; an older dossier tags a Commons file "Public domain" cc0, which the site reads as pd.
  • It holds the summary with its licence, at most 1,500 characters, cut where a sentence ends, with cut: true where the article's lead went on, or the text does not end a sentence, when it ends with "…".
  • The summary carries revision, the article's revision it was quoted from, and read, the day it was read, which the page names.
  • It holds links, and literature, which is empty: the reference does not ask OpenAlex, and upstream.openalex is skipped, with why.
  • And an upstream block, recording for every source whether it answered, refused, was not asked (skipped), or was carried from an earlier build. For a source read from a file, asOf is the day of the file it was read from (Kew's files, GBIF's download).
  • A species with more records than GBIF's download was cut to is read from GBIF's occurrence search. A rebuild from the files keeps the search's answers with the download and reads them again until a new download; its gbif.occurrences row then says the day GBIF's search gave them, and asOf is that day where every record is of it.
  • Its gbif.occurrences row says how its records were tested against the range: by the regions' shapes, by their boxes, or by both, naming the regions tested by box.
  • occurrences.rangeRule: the rule of the regions' shapes its records were tested by, named by the round that wrote it. The build's range check lists every page tested by an older rule.
  • occurrences.admitted ({ strict, buffer, coast, island }): every record in the range counted by how it was let in, inside a native region's shape, by the buffer, by the coast reach, or on a small island. Since rule r86 the buffer counts a record within 0.02° across a border, let in by its stated country and, where it names a state or province the shapes can match to one of the two regions, by that state. occurrences.edge names the open records the last three took.
  • climate.admitted counts the climate's cells the same way, and climate.edge gives each cell not strictly inside a native shape, by its middle and why, which the build's range check tests. climate.place: the typical cell's state or province and country.
  • Where GBIF held more records than the build reads, they are a sample chosen by grid cell, every distinct cell first (the rule).

A photograph's fields

  • Each photograph carries read, the day its credit and licence were read from its source, which the page says with the credits.
  • A Commons photograph carries categories, Commons' categories for the file as the build or the fill of Commons' categories read them, absent where not yet read. It carries struck where its description strikes out a name. The site reads both to decide whether it is shown.
  • A Commons photograph may carry slips (the uploader's slips in its name that Kew and GBIF were asked of and hold as no species).
  • It may carry inat (the iNaturalist photograph its source names), kind (what its source or description says it is, when not a living plant), sourceRead (set once the fill has read them) and kindRule. A file left out by its description is asked again only when the description rules (kindRule) are newer.
  • Any photograph may carry shared: the ids of the other species' pages that hold it, Kew's ids before GBIF's, each by number, written when the index is made. It is then not shown.
  • A Commons photograph carries judged ({ not, rank }), written when the index is made, with every name the reference holds. not is why the file is not a photograph of the species, absent when it is one.
  • rank is 0 when its title holds the species' own epithet, 1 an older name's, 2 neither. The site shows the file, and orders the Commons files, by it; a file without one by the same rules with no names but the species' own.
  • A GBIF photograph whose record is not an observation of the living plant carries specimen, and is not shown.

The id and the names

  • The document's key is the page's id (dossier version 3): k and Kew's plant_name_id where Kew's file gives the page one accepted taxon that no other page holds. Otherwise it is g and its GBIF Backbone key.
  • A g page is one where Kew's rows do not decide, or two pages hold one Kew entry (which is Kew's is not guessed: a merge decides it), or a page merged into another until it is pruned.
  • ids.gbif is its GBIF key.
  • A k page's name is Kew's accepted name for its entry, with Kew's author; GBIF's name for its key, where it differs, is among its older names.
  • ids.gbif is absent for a species Kew accepts whose name GBIF's backbone holds as no one accepted species. Its key is k and Kew's plant_name_id.
  • Its name block (with name.kew), range and IPNI and POWO numbers are read from Kew's file (upstream['kew.names'], asOf the file's day). Its Wikidata item is the one that carries that IPNI or POWO number.
  • GBIF is not asked by its name: its gbif.species, gbif.synonyms, gbif.vernacular and gbif.media rows are skipped, with the reason.
  • Its English names are its item's, in name.vernacular with source "Wikidata". upstream['wikidata.names'] says what was read: ok or none where Wikidata answered; skipped, refused or error, with why, where it was not checked.
  • Where Kew's synonymy gives it GBIF keys of its own (the list of keys from Kew), its occurrences, centroid and climate are read from their records as any page's, and occurrences.keys names each key.
  • Otherwise its gbif.occurrences and climate rows are skipped with the reason, its occurrences are empty with rangeTested false, and it has no centroid. Its climate is pending with the reason, and the site says each as not asked, never none.
  • That reason is the page's own, in occurrences.unread ({ kind, why, under }). It says what GBIF's backbone holds of Kew's names for it: lumped, none, other-type, pro-parte, other-author or other.
  • It carries the words the page says and, where GBIF files those names under other pages here, each of them by its GBIF key, its name and its id (page). A dossier without it says the general reason.

Fields that may be absent

  • Each of these fields, where absent, means not read, never none.
  • name.cited ({ gbif, kew }), present when the page cites Kew's author for the number it links: the backbone's citation, and Kew's row cited (its plant_name_id).
  • name.kew ({ entry, synonyms, acceptedElsewhere, file, heldBy? }): Kew's accepted entry for the page's plant, Kew's synonym binomials of it, the stored older names Kew accepts as species of their own, and the day of Kew's file.
  • The entry is '' when the names do not lead to one, or lead to an entry another page holds, whose id heldBy names; there are then no synonyms. One Kew entry is one page's.
  • name.kew.accepted ({ name, authors, rank, other?, family? }): Kew's row for the entry, with Kew's family, which heads the page while its id is k and the entry's number. name.gbif: GBIF's name for the page's key, where Kew's heads the page, with GBIF's family; added names the older name the heading put among the synonyms.
  • name.shared: the one-word English names the page does not head with or show, since another species of its genus is given them more often, or as often. name.infra: the names GBIF files under the species' own varieties and subspecies, read by the fill of GBIF's infraspecific names, which the search reads as a name typed.
  • name.formerly: the names that headed the page before its heading now, each still an address of the page. name.kew.elsewhere: GBIF's names on the page that Kew's file files only under another plant, which are not the page's names, so neither searched, shown nor an address.
  • distribution.via, where the range comes from: its kind (own, older-name, synonym-of, kew-entry or spelling), and the entry whose range is shown.
  • distribution.kew.area: Kew's own words for where the plant grows (WCVP's geographic_area, "New Zealand (Poor Knights Is., Hen I.)"), quoted and never read as the range. A region Kew gives no level-3 unit for is named as Kew names it, a level-2 region or a continent, with no code (Mexico, Malesia).
  • It also carries page, that page's id when the entry is another page here; unplaced, when Kew holds the name as unplaced; and file, the day of Kew's file.
  • distribution.doubtful: the regions where WCVP records the plant as doubtfully present, listed apart, never a range box.
  • occurrences.keys ({ key, name, kew, n, from, slug }), present when the records also come from other GBIF keys than the page's own, or, on a page without a GBIF key, from the keys Kew's synonymy gives it.
  • For each key: GBIF's name for it, how Kew's file holds it as this page's name or type, the records it added, download or api, and, for a page merged into this one, the old address.
  • The species page reads these fields.
  • occurrences.api ([{ key, n }]): the in-range records that came through GBIF's search API rather than a download, counted by their dataset (GBIF's datasetKey), the largest first. Empty when none came so; absent where the page was derived before the count was kept, so not known. The page does not show it; the build adds these counts up across the pages for a GBIF derived dataset of those records.
  • flowering, in one of two forms. Counted from GBIF's download ({ source: "gbif", key?, keys, months, doi, made, read }): iNaturalist's research-grade observations annotated flowers that iNaturalist shares with GBIF, by month, January first, under the page's own GBIF key (key) and the keys that gave a count (keys); the download's DOI, the day GBIF made it, and the day the page was counted. Read from iNaturalist's API ({ taxon, months?, read, unanswered? }): the same annotation for the iNaturalist taxon named, and the day read. Without months, with unanswered: asked and not answered.
  • elsewhere.wikidata ({ item, read, ids, unanswered? }): the identifiers the page's Wikidata item holds, each { p, v }, its Wikidata property and value, and the day read.
  • elsewhere.published ({ place, volPage?, year?, row, file?, bhl? }): where the name was published, as Kew's file writes it for the row named, and the day of Kew's file. bhl ({ page?, none?, read }): BHL's page for exactly that citation, or why none was taken, and the day asked.
  • parents ({ formula, row, file?, of }): a hybrid's parents as Kew's formula states them. Each of of gives the words, Kew's row and accepted entry, the page here where there is one, and why where there is none. others counts the other authors' names of the same words.
  • risk, cites, chromosomes and nameAgreement: Kew's predicted extinction risk, the CITES listing, ChromoDB's counts and the WFO Plant List's reading of the name. Each has a status (ok, none, undecided, or skipped for not asked, with why), the day it was read, and the file or table it was read from, with the date its publisher gives it.
  • hardiness ({ usda?, usdaWhy?, rhs, src }): the USDA zone of the mean yearly low, with its years, or why there is none, and the RHS band of the record low. koppen: the Köppen–Geiger class, or why there is none, with the figures it was worked out from.
  • climate.extremes.lows ({ from, t }): the lowest night of each calendar year from the first, null for a year with fewer than 347 of its days.
  • name.kew.by: for each of Kew's older names, Kew's authors of it in the plant.
  • GBIF's English names are one row per exact spelling and language. Each has the first source that gives it (source), the other named sources of that spelling (alsoFrom), how many sources give it when more than one (sources), and GBIF's preferred flag.
  • A row whose name holds commas is read by the common-name rule as a list of names, each given by that row's sources. A list longer than four pages of a thousand rows is kept as far as it was read, and its upstream record says "truncated".
  • A row whose source is "Wikidata" is an English name from the page's Wikidata item, its taxon common name (P1843), for a page without a GBIF key.
  • Its alsoFrom lists the references of its statement that name a source ("stated in Q…", or "at" and the site of a reference URL). Its preferred is Wikidata's preferred rank. The record wikidata.names names the item and each name taken or refused, with why.
  • climate.annualRain holds the 10th and 90th percentiles and the median (p50) of the cells' own yearly rain totals.
  • changed is { on, h }: the day (YYYY-MM-DD, UTC) the page's substance last changed, and a 16-hex fingerprint of it.
  • The fingerprint is of the dossier without built, builtBy, changed, each photograph's judged, and each source row's at and detail. Each photograph's shared is read as a set, so the same pages in another order are no change.

An index entry

  • Each species' index entry, as /api/entries?b= answers a group of them, carries key, the page's id. It carries gbif, its GBIF key, which a plant's taxonKey is compared with; the figure sheets carry both too. A page without a GBIF key has no gbif.
  • slug, name, family, origin, photos, open and climate (ok, none or pending).
  • common, the shown English name, and commons, the others. spellings: the other spellings of the shown names, searched, never shown.
  • thumb and credit: the thumbnail and its licence and author as a tile shows them after "Photo: ", absent when they cannot be said short and true.
  • near: the ids of the six species of nearest habitat climate.
  • changed: the day the dossier last changed in substance, as whole days since 1 January 1970.
  • low: the record low at the typical spot, °C to one decimal, where the page shows one. first: the day the page was first seen, as days since 1970-01-01, the earliest day its record notes or an earlier index's.
  • syn: up to six older names, shown. older: every other older name of species rank, searched, never shown.
  • kew: Kew's older names for the plant that syn and older do not hold, and the names GBIF files under the species' own varieties and subspecies, which the search reads only as a name typed and nothing shows. Absent where there are none, or Kew's file has not been read for the page.
  • gname: GBIF's name for the page's own key, where Kew's name heads the page and the page answers to GBIF's too; a row found by it says "GBIF's name for" the page. Absent on a page GBIF's own name heads.
  • hom: the record's older names spelt as another page's accepted name, by another author than that page's, searched only as a name typed and said as another author's name. homBy: for each of them, the authors the record writes after it, as written.
  • Or, in homBy, Kew's authors for the name in this plant, where the record writes none or Kew files the name here by another author than the other page's.
  • merged: the names of the pages merged into this one, each also among its older names. The search lists this page first for them, and its row says the name is merged into it.
  • grown: how many of iNaturalist's observations are marked captive or cultivated for the species, as the species list counts them. The search breaks a tie by it, before the photographs.
  • Each of these, where absent, means none was written, never that the species has none.

The dataset export

  • The reference is built from public data under CC0, public domain, CC BY and CC BY-SA. The source code's export script packages a built reference as a dataset bundle: the species JSON, species.csv, climate.csv, and the licence terms per source.
  • That is how the reference data leaves the site as data rather than pages.
  • species.csv ends with annual_precip_cells_p10_mm, annual_precip_cells_median_mm and annual_precip_cells_p90_mm: the 10th percentile, median and 90th percentile, across the cells, of each cell's own yearly total. annual_precip_mm stays the median year's total.

The reference's files

Beside the dossiers, the build writes small files the server reads instead of the whole index. Each is named by the hash of its content, and a manifest names them all. The file counts grow with the reference by a fixed rule.

The format in full: the reference's files
  • The files are stored under the hash of their content (s/v3/p/<md5>.json; the dossiers are s/v3/<id>.json). s/v3/manifest.json names them: { v, id, built, species, buckets, postings, files: { <name>: <md5> } }, where id is a hash of every file's hash.
  • index.json: every species' index entry. /api/index passes it on as it is stored.
  • entries/<group>.json and sheets/<group>.json: a hash group's entries and figure sheets (/api/entries, /api/sheets).
  • A sheet filed under another name than its page's carries via and page, the page's own address. via: 'merged': the name of a page merged into it. via: 'gbif': GBIF's name for the page's own key, where Kew's name heads the page; the app takes such a copy only for a plant of that GBIF key. An app of an earlier round reads either as the page's sheet.
  • postings/<n>.json: which entries, by position in the index, each short key of a name can match. short.json: the best hundred for each key of one or two letters.
  • catalogue/<grouping>-<chip>.json: the catalogue's rows ({ rows, letters, letterAt, total, withClimate }).
  • rows/<grouping>/<n>.json: each catalogue row's species under "all", by row id ({ at, items }), sorted by name, with each one's position in the index.
  • The row files of a grouping are the power of two at or above the species count divided by 150 for genera, and by 600 for families and regions, and at least 16. At 48,375 species, on 19 November 2026: 512 for genera, 128 for the others.
  • genera.json: every genus with its count of species, [[genus, count], …].
  • older-genera.json: every genus no page is headed in that is the first word of the older names of at least three species, with that count, [[genus, count], …]. The search reads a misspelt genus against both files.
  • featured.json: the species the front page's strip rotates through ({ slug, name, thumb, credit, common, family }).
  • browse.json: what the browse pages filter, count, list and export, as columns, every species by its position in the index ({ v, n, name, key, gbif, slug, common, families, family, origins, origin, climate, grown, changed, low }).
  • In it key is the page's id (a number for Kew's) and gbif its GBIF key, or 0. slug holds only the addresses that are not the name's. family and origin are positions in families and origins, and climate is one letter a species.
  • grown is a species' observations in cultivation, or -1 where they were not counted, and changed the day it last changed, in days since 1970. Its record low is low, °C to a tenth, or null where none is known; a table written before it lacks it. A first column, the day a page was first seen, is no longer written, and is not read where an earlier table has it: the index keeps that day. Where the reference has no such file, the server makes the table from the index, if it can read one.
  • browse-counts.json: { grown, regions, families, genera, grownNotCounted }: the species with observations in cultivation, as the browse page's filter counts them (null where the index counts none); the TDWG level-3 regions, the families and the genera that /region, /family and /genus list; and the species whose cultivated observations are not counted. The front page's Browse table shows them.
  • sitemap/<n>.json: forty thousand of the sitemap's addresses a file, with each one's day ({ urls, days }).

The names every page looks up

  • cards/<n>.json, what a species page reads: an object from each page's address to the id of its species, and from #<id> to the species itself.
  • The species is { key, gbif, slug, name, at, family, common, thumb, credit, open, climate, syn, near, x }: key its id, gbif its GBIF key, at its position in the index, and x its record's older names that are another species' accepted name here.
  • It also maps @<GBIF key> to the id of the page whose own GBIF key it is, by which an answer of GBIF's finds its page.
  • The card files are the power of two at or above a 64th of the species count, and at least 64: 1,024 at 48,375 species.
  • older/<n>.json, read for an address that is no page's and for a page reached by an older name. It maps each accepted name in lower case, and each older name in lower case and as an address, to { n, o }.
  • n is the species whose accepted name it is, as [id, address, name]. o is an older name's holders, { m, h }: h the species that hold it, as [id, address, name], and m the name as written.
  • With two or more holders, h is in the order the 404 names them, and the address leads to none.
  • The files of names are the power of two at or above a hundredth of the species count, and at least 64: 512 at 48,375 species.
  • The file a key is in is the FNV-1a hash of it, modulo the number of files of its set.
  • A reference whose manifest lacks any of these is read through its index, as before.

The search's files

  • search/top.json and search/<n>.json are the directories of the search's keys. top.json holds every key of one or two characters; each other key is in the file its first three characters' FNV-1a hash, modulo the number of files, gives.
  • The number of directory files is sixty-four, doubled while the species count is more than 160 times it, up to 4,096: 512 at 48,375 species.
  • Each directory is an object from a key to [count, md5], the key's file. Or [count, md5, 2]: the key's file, and the keys one character longer are listed too, as they are for every key of one or two characters and every key of more than 200 species.
  • Or [count, md5, 1]: more than 2,000 species, so no file; the keys one character longer are listed, and md5 names its answers. Or [count]: a similar-spelling key with no file, of more than 2,000 species or of one or two characters; the keys one character longer are listed.
  • A key is the beginning of a word as the search reads it (alo). A similar-spelling key, written with ~ before it, is the beginning of a word of a species' name, English names or older names with one of its letters taken out, and under three characters the beginning itself too.
  • A key's file, s/v3/p/<md5>.json, is [[position, doc], …]: every species with a word so begun, in the index's order, with its position in the index and what the order reads of it.
  • The doc is [name, family, origin, common, commons, spellings, syn, older, kew, hom, merged]. The family and the regions of origin are numbers into search/tables.json ({ families, regions }), with -1 for no family and '' for no headline; empty fields at the end are left off.
  • kew is filled only in a file of Kew's older names (an @ key), with the names of that key's genus.
  • search/blocks.json is { photos, show }: the md5s of the photograph counts by position, 4,096 to a file ([count, …]), and of the index entries by position, 16 to a file ([entry, …]). A search reads them for its matches only. Where the index carries grown, it also holds grown, the md5s of the growers' counts by position, as the photographs'; a server of an earlier round reads neither.
  • Answers are { a, b?, t?, x?, n? }, by position in the index: the whole index's best hundred to the word alone as typed (a); in a form no English name is written as, when that differs (b); and in each form an English name is written as (t, by the form).
  • x: 1 when they came from the word as typed rather than a similar spelling. n is how many species the whole index answers, of which these are the first.
  • search/genera.json is every genus of the reference as the search reads a word.
  • The key files and answers are named by the directories, and the count and entry files by blocks.json, not by the manifest. A server that reads them reads neither the index nor the postings. The postings and short.json are still written, for a server deployed before them.
Cultifolio

Opening your plants…