droboticflow/internal/api/part_index_contract_test.go
d-robotics 7b5604f9e0 🧾 Deliver one part index JSON instead of sliced directories
Add a PART_INDEX_DELIVERY mode to the package operator (default off): a part
delivers a single part.json carrying both split levels, the task-level slice
boundaries and the action-level segments, plus a classification for every
reviewed interval. Kept intervals land in slices[], discarded intervals in
discardedSlices[] with their discard evidence, which deliberately makes the
discard reason part of the customer deliverable. Media, PTS, IMU, pose and
calibration bytes are no longer published; downstream packaging resolves them
from the pinned materialization revision.

The worker publishes the index through the same frozen-destination path as the
directory form. Extract prepareDeliveryTarget so single-file and directory
publication share one owner marker, overlap guards, delegated-scope check,
conditional create, sha256 verification, idempotent retry and the refusal to
overwrite another delivery. A part index also refuses to adopt a destination
that holds files without an owner marker, so additive migration cannot claim a
legacy directory by accident.

The API and download control plane recognise the new schema, project the split
classification for the browser, and treat a part index as a first-class final
delivery. Cross-language contract tests read the operator's own schema and
field literals so a one-sided rename fails a test.

Verification: 10 operator tests, 8 worker tests and 3 API tests for the new
behaviour pass. Failure sets match the HEAD baseline name-for-name for
internal/api (75), internal/worker (4), tests/backend and the frontend suite;
no regression. The end-to-end local replica stack was not exercised: it needs
image builds and the opt-in Go materialization fixture, so the Go to operator
handoff is covered by the contract tests instead.
2026-10-09 00:28:50 -07:00

89 lines
3.5 KiB
Go

package api
import (
"os"
"path/filepath"
"regexp"
"strings"
"testing"
"droboticflow/internal/domain"
)
// The part index crosses a language boundary: the package operator (Python)
// produces it, the worker publishes it, and this package projects it for the
// browser. Nothing type-checks that boundary, so read the producer's own
// schema and classification vocabulary and require it to still match what the
// reader understands. Without this, renaming a field on either side silently
// degrades to "暂不支持预览" instead of failing a test.
func TestPartIndexContractMatchesThePackageOperator(t *testing.T) {
root := filepath.Join("..", "..", "backend", "operators", "builtin", "package", "operator.py")
source, err := os.ReadFile(root)
if err != nil {
t.Fatalf("package operator source is unavailable: %v", err)
}
text := string(source)
quoted := func(pattern string) string {
match := regexp.MustCompile(pattern).FindStringSubmatch(text)
if match == nil {
t.Fatalf("package operator no longer declares %s", pattern)
}
return match[1]
}
schema := quoted(`_PART_INDEX_SCHEMA = "([^"]+)"`)
if schema != "droboticflow.delivery.part-index/v1" {
t.Fatalf("part index schema changed to %q; update the reader and its tests", schema)
}
fileName := quoted(`_PART_INDEX_FILE = "([^"]+)"`)
if fileName != "part.json" {
t.Fatalf("part index file name changed to %q; the worker identifies deliveries by it", fileName)
}
if !strings.Contains(text, `"kind": "part_index"`) {
t.Fatal("part index no longer declares its delivery routing kind")
}
if !strings.Contains(text, `_PART_INDEX_ARTIFACT = "delivery.part-index"`) {
t.Fatal("part index artifact name changed; the worker and port binding rely on it")
}
// The payload the projection reads must keep its producer-side keys.
payload := partIndexPayload()
for _, key := range []string{"schemaVersion", "datasetType", "delivery", "coverage", "deliveryClassification", "slices", "discardedSlices"} {
if _, ok := payload[key]; !ok {
t.Fatalf("part index payload fixture is missing producer key %q", key)
}
}
for _, key := range []string{"sliceId", "sliceName", "taskSplit", "classification", "segments"} {
if !strings.Contains(text, `"`+key+`"`) {
t.Fatalf("package operator no longer emits the task-level key %q", key)
}
}
for _, key := range []string{"deliveryDisposition", "discardEvidence", "descriptionStatus", "taskLabel", "taskLabelId"} {
if !strings.Contains(text, `"`+key+`"`) {
t.Fatalf("package operator no longer emits the classification key %q", key)
}
}
for _, key := range []string{"reason", "reasonLabelId", "reasonName", "note", "discardedByUserId", "discardedAt"} {
if !strings.Contains(text, `"`+key+`"`) {
t.Fatalf("package operator no longer emits the discard evidence key %q", key)
}
}
for _, key := range []string{"id", "description", "status", "isInvalid", "startTimestampUs", "endTimestampUs", "clipStartMs", "clipEndMs", "labelId", "phrases", "source", "confidence"} {
if !strings.Contains(text, `"`+key+`"`) {
t.Fatalf("package operator no longer emits the action-level key %q", key)
}
}
}
// The API must recognise exactly the schema the worker is willing to publish,
// otherwise a delivered part index renders as an unsupported preview.
func TestPartIndexSchemaIsRecognisedByThePresentationWhitelist(t *testing.T) {
artifact := domain.ExecutionArtifact{
Name: "part.json",
Type: domain.PortTypeJSON,
Data: partIndexPayload(),
}
if !artifactLooksLikeCollection(artifact) {
t.Fatal("part index is not offered as a structured collection")
}
}