The order is the whole contract
pithy add vector wrote the wiring, pithy provision covers the rest of the project, pithy vector is this capability’s command, and the metadata indexes have to be decided before the index exists.
- Create the index.
- Create every metadata index its schema declares.
- Deploy the Worker that writes vectors.
The ordering is asserted by a test that records the call sequence against a fake provisioner, so it cannot regress into a plausible-looking refactor.
What add could not write
pithy add vector writes the bindings it can. The vectorize and workflows bindings are not among them.
Wrangler requires an index_name on the first and a name plus class_name on the second — and every one of those values is an output of provisioning. A partial entry stops wrangler loading the config at all, so add writes neither, and the CLI writes both, complete, once provisioning has succeeded.
Naming
<project>-<env>-vector-<index>.
Per environment, never shared: a staging index and a prod index sharing vectors means staging’s test corpus answers prod’s searches, and a staging teardown deletes prod’s embeddings.
Per project, for a sharper reason. Vectorize’s index namespace is account-wide and provisioning reuses an index it finds by name. An unscoped name would let a second Pithy project adopt this one’s index, mix two corpora into one search, and delete both on either teardown.
And because dimensions and metric are fixed at creation, that adoption would also silently pin the second project to the first project’s embedding model — a constraint nobody wrote down and nobody could see.
The name goes through the naming facade, which carries Vectorize’s own rule: 64 bytes, not the 63 every namespace was once held to, and refused rather than truncated. A shortened index name is a different, empty index, and re-embedding a corpus is neither free nor quick.
Vectorize also constrains the charset — an index name must start with a letter and end alphanumeric. The project rule already requires a letter-leading project and every composed name leads with the project, so the two agree by construction.
The facade validates the project once and the environment once, so production is refused here rather than standing up a fourth environment nothing else knows about.
Idempotency, and one caveat about it
Every step is idempotent — find-then-create for the index and its metadata indexes, and a deploy that overwrites. A re-run reconciles rather than fails.
Nothing writes and immediately reads back, because Vectorize applies both index and metadata-index changes asynchronously. A verification read straight after a create would be a flake generator, and a wrong one: it would report absence for a change that was simply still landing.
What it records
Provisioning writes down the metadata indexes it observed. The Worker reads that record at boot and compares it against the config’s declarations — the offline half of the drift check.
That is what catches the case that actually happens: a metadata schema edited and deployed without re-provisioning.