feat(schema): declare an FTS or invert index in addString() (#223)

[s2x]

Closes #223.

Summary

A full-text index on a STRING field used to need two steps — create the collection, then createIndex(). Upstream puts index params on the field, so it can now be one:

$schema->addString('body', indexParams: ZVecIndexParams::forFts());
$schema->addString('tag',  indexParams: ZVecIndexParams::forInvert());

The index exists from the first insert. This matches the Python SDK's FieldSchema(index_param=...) and how upstream's own hybrid tests build collections. The new argument is last and optional, so existing calls are unchanged.

Design notes

A mismatched index type is deliberately not rejected in PHP. Upstream reports it at ZVec::create() time with a message naming the field:

schema validate failed: scalar field[body] does not support vector index params, but got index_type ...

That is clearer than anything the adapter could produce, so there is one source of truth rather than two. The test asserts the upstream path rejects it.

A duplicate field name is now reported here, unlike in the other add*() methods. add_field() returns AlreadyExists, and every zvec_schema_add_field_* function discards that Status — so addString('body') twice currently loses a field silently. This one propagates it because it already has to build index params and return a status. Worth noting as a pre-existing bug in the other setters that is out of scope here (changing them is a BC-sensitive sweep).

No new memory handling. Upstream's FieldSchema constructor clones the index params, so the ZVecIndexParams object keeps owning its handle and is freed by its own destructor as usual.

The FFI function is declared next to zvec_collection_create_index() in both headers rather than next to zvec_schema_add_field_string(), because the zvec_index_params_t typedef comes after the schema block.

Verification

// no createIndex() anywhere
$schema->addString('body', indexParams: ZVecIndexParams::forFts())
        ->addVectorFp32('vec', dimension: 4, metricType: ZVecSchema::METRIC_IP);
$collection = ZVec::create($path, $schema);
$collection->insert(/* ... */)->flush();
$query = (new ZVecVectorQuery('body', []))->setTopk(10)->setFts('body', 'fox');
// -> [d1]

Full suite from a clean build:

Number of tests : 195               195
Tests skipped   :   0 (  0.0%)
Tests failed    :   0 (  0.0%)
Expected fail   :   2 (  1.0%)
Tests passed    : 193 ( 99.0%)

tests/test_schema_fts_index.phpt covers the query without createIndex(), getIndexType() before and after a reopen, invert via params, both validation errors, and the pre-existing argument combinations. test_ffi_load.phpt gained the symbol (67 → 68). test_dbs/ is left with only .gitignore.

One thing to watch

tests/test_diskann_index.phpt failed once during this work, returning doc2 where the expectation was doc1,doc2,doc3. It then passed on five consecutive single runs and four consecutive full-suite runs, and the failure did not reproduce with the change stashed. Not caused by this PR as far as I can tell — most likely a flaky DiskANN result on a 3-document collection — but flagging it rather than leaving it unexplained.

🤖 Generated with Claude Code