Query/index capability 0.1
Stable commands, JSON documents, bounds, errors, and conformance for Folderbase metadata queries.
folderbase.query-index@0.1.0 is a separately advertised experimental capability. It
does not add commands to Compatibility Contract v1 or definitions to
Folderbase CLI JSON v1. Integrations must discover it with:
folderbase protocol contract --jsonProcess interface
| Command | Input | Success document |
|---|---|---|
folderbase query run ROOT --json | one folderbase-query-request-v1 on stdin | folderbase-query-result-v1 |
folderbase query explain ROOT --json | one folderbase-query-request-v1 on stdin | folderbase-query-explain-v1 |
folderbase index status ROOT --json | none | folderbase-query-index-status-v1 |
folderbase index rebuild ROOT --json | none | folderbase-query-index-rebuild-result-v1 |
The request is a closed JSON object with a required scope and page. Live
scope observes the current folder. Historical scope selects one exact
folderbase_version_id. Optional filters cover exact paths, component-aware
path prefixes, kinds, lifecycles, object identities, Object Version identities,
and minimum or maximum logical bytes.
Within one filter family, values are ORed. Different filter families are ANDed. Page limits are 1 through 1,000. The request transport is bounded to 4 MiB and each output document to 8 MiB. Error messages are bounded to 4,096 Unicode scalars.
The canonical schema is
query-index.schema.json.
It is the source of truth for every required field, enum, bound, and closed
object.
Ordering and cursors
Results use deterministic query_row_key_v1 ordering. A cursor is opaque and
bound to the physical Folderbase Root, normalized request, root manifest,
effective ignore policy, optional Local Head, and complete observed metadata
generation. Callers must not parse or modify it.
Output and exits
Exit 0 writes one success document to stdout and leaves stderr empty.
Exit 1 means the request was valid but its cursor observation changed. Stdout
contains folderbase-query-attention-v1 with code
query_snapshot_changed and retryable: true; stderr is empty. Retry from the
first page rather than continuing the old cursor.
Exit 2 is an operational or domain failure. Stdout is empty and stderr
contains folderbase-query-error-v1 with one of these codes:
| Code | Meaning |
|---|---|
invalid_query_request | Invocation syntax, JSON, request shape, path, filter, or request bound is invalid. |
invalid_query_cursor | Cursor encoding or its request/root binding is invalid. |
query_root_changed | Root authority or required observable root state is unsafe or changed. |
query_inventory_limit_exceeded | A bounded live inventory cannot be represented safely. |
query_scope_version_missing | The requested historical Folderbase Version does not exist. |
query_scope_version_invalid | The requested historical Folderbase Version is invalid. |
query_index_rebuild_failed | The disposable index could not be rebuilt safely. |
Messages are explanatory and must not be parsed.
Once the first argument selects query or index, syntax failures are also
capability failures: a missing root or --json, an unknown option, or an
unknown subcommand exits 2 with empty stdout and the typed error document on
stderr. Help and version output remain ordinary successful CLI output.
A host output-stream failure is the sole delivery exception. If stdout or
stderr is unavailable, Folderbase still exits 2 and attempts a non-panicking,
best-effort diagnostic on stderr, but no program can guarantee typed JSON
delivery to an unusable stream. This includes a failed stdout write. Normal
invocation, domain, and operational failures still require the typed envelope
whenever the destination stream is usable.
Metadata and file types
Rows can represent directories, regular files, symlinks, and opaque nested Folderbase boundaries. Repository trees remain ordinary directories and entries. Regular files include logical byte size and may be Markdown, PDF, CSV, SQLite, video, or any other ordinary file type. Live queries never read regular-file content. Historical rows may carry stable Knowledge Object, Object Version, and Folderbase Version identities.
Independent conformance
Run the dependency-free black-box suite against any executable:
node protocol/conformance/capabilities/query-index-0.1/run.mjs \
--implementation /absolute/path/to/folderbaseThe runner uses only the process interface, filesystem fixtures, checked-in
schemas, and independent digest vectors. A passing report exits 0 with
failed: 0.