Agents need a stable command surface for file inventory and assessment. Add the
two commands, collection resolution, format selectors, sample limits, capability
refusals, and the existing budget handling.
Acceptance criteria
CLI and library behavior agree; every invocation emits exactly one envelope; a
missing result binding produces an actionable prerequisite that names the
inventory command as the available alternative; no confirmation path can enable
native processing.
Detail
One small command group, not a new top-level surface:
explore files inventory [collection]
explore files profile <collection> [--format pdf|scanned_image] [--sample-files N]
Both commands keep the existing JSON envelope, connector selection, source
scopes, and applicable budget controls. collection is a configured logical
name or a supported warehouse collection identifier.
explore files profile requires a result binding. Without one it returns a
prerequisite refusal rather than an empty report, and it names inventory as what
can be run instead.
--format is repeatable and initially recognizes pdf and scanned_image.
Both families are assessed by default. --sample-files defaults to 200 with a
ceiling of 1,000.
A missing capability or an unmet prerequisite never triggers a fallback. Dex
does not switch connectors, does not read object storage directly, and does not
substitute a cached report for a requested assessment.
Confirmation exists for spend on ordinary warehouse queries. It is not a route
to document processing, and no flag added here may become one.
Constraints
Two constraints govern this work wherever it touches the engine, and an issue
that satisfies its own tests while breaking either is implemented wrong:
- Document content never leaves the warehouse. Every content computation
runs inside a warehouse expression. No document body, excerpt, heading,
extracted value, image, file name, path, signed URL, individual file
identifier, or raw provider error string may reach stdout, stderr, the cache,
or an audit record.
- Nothing in this backlog invokes document processing. Only engine-authored
diagnostic queries over materialized tables execute. New document-processing
charges require a provider-enforced hard monetary ceiling that Dex can verify,
and no estimate, page limit, delayed quota, or user confirmation substitutes
for one.
Dependencies
Depends on #453, #454, #455, and #456.
Agents need a stable command surface for file inventory and assessment. Add the
two commands, collection resolution, format selectors, sample limits, capability
refusals, and the existing budget handling.
Acceptance criteria
CLI and library behavior agree; every invocation emits exactly one envelope; a
missing result binding produces an actionable prerequisite that names the
inventory command as the available alternative; no confirmation path can enable
native processing.
Detail
One small command group, not a new top-level surface:
Both commands keep the existing JSON envelope, connector selection, source
scopes, and applicable budget controls.
collectionis a configured logicalname or a supported warehouse collection identifier.
explore files profilerequires a result binding. Without one it returns aprerequisite refusal rather than an empty report, and it names inventory as what
can be run instead.
--formatis repeatable and initially recognizespdfandscanned_image.Both families are assessed by default.
--sample-filesdefaults to 200 with aceiling of 1,000.
A missing capability or an unmet prerequisite never triggers a fallback. Dex
does not switch connectors, does not read object storage directly, and does not
substitute a cached report for a requested assessment.
Confirmation exists for spend on ordinary warehouse queries. It is not a route
to document processing, and no flag added here may become one.
Constraints
Two constraints govern this work wherever it touches the engine, and an issue
that satisfies its own tests while breaking either is implemented wrong:
runs inside a warehouse expression. No document body, excerpt, heading,
extracted value, image, file name, path, signed URL, individual file
identifier, or raw provider error string may reach stdout, stderr, the cache,
or an audit record.
diagnostic queries over materialized tables execute. New document-processing
charges require a provider-enforced hard monetary ceiling that Dex can verify,
and no estimate, page limit, delayed quota, or user confirmation substitutes
for one.
Dependencies
Depends on #453, #454, #455, and #456.