fix: type accuracy, confidence docs, and published-artifact verification (#1 #2 #4)

Author: Garfield-yin

.github/workflows/release.yml

@@ -434,15 +434,111 @@ jobs:
           done
           npm publish "$tarball" --access public --provenance --tag "$publish_tag"
 
+  # The release job verifies a locally packed tarball. That cannot catch a
+  # package that reaches the registry incomplete, which is exactly how 2.3.0
+  # shipped without dist/ and wasm/ while every pre-publish gate passed. Install
+  # the published version from the public registry in a clean directory and
+  # exercise it the way a consumer would.
+  verify-published:
+    name: Verify the published npm package
+    needs:
+      - plan
+      - publish-npm
+    if: ${{ always() && needs.publish-npm.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - name: Verify the registry artifact and run it as a consumer
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ needs.plan.outputs.tag }}
+        run: |
+          version="${RELEASE_TAG#v}"
+          package="@deckflow/deckprobe@${version}"
+
+          # npm publishes are not immediately readable. Retry, then fail loudly.
+          for attempt in $(seq 1 15); do
+            if npm view "$package" version >/dev/null 2>&1; then
+              echo "$package is readable from the registry"
+              break
+            fi
+            if [[ "$attempt" == 15 ]]; then
+              echo "$package never became readable from the registry" >&2
+              exit 1
+            fi
+            echo "attempt $attempt: not readable yet, waiting"
+            sleep 20
+          done
+
+          # The declared entry points must actually be inside the published tarball.
+          npm pack --dry-run --json "$package" > packed.json
+          node -e '
+            const packed = require("./packed.json")[0];
+            const files = new Set(packed.files.map((file) => file.path));
+            const required = [
+              "dist/index.js",
+              "dist/index.node.js",
+              "dist/worker.js",
+              "wasm/deckprobe_wasm.js",
+              "wasm/deckprobe_wasm_bg.wasm",
+            ];
+            const missing = required.filter((path) => !files.has(path));
+            if (missing.length) {
+              console.error(`registry tarball is missing: ${missing.join(", ")}`);
+              process.exit(1);
+            }
+            console.log(`registry tarball carries all ${required.length} declared entry points (${packed.entryCount} files)`);
+          '
+
+          # Install into a clean project, the way a consumer would.
+          mkdir -p "$RUNNER_TEMP/consumer"
+          cd "$RUNNER_TEMP/consumer"
+          npm init -y >/dev/null
+          npm install "$package" >/dev/null
+
+          # The Node entry point, its WASM, and the discovery contract.
+          cat > check.mjs <<'CHECK'
+          import assert from "node:assert/strict";
+          import { writeFileSync } from "node:fs";
+          import { formats, probeFile, version } from "@deckflow/deckprobe";
+
+          const expected = process.argv[2];
+          assert.equal(await version(), expected, "runtime version disagrees with the published version");
+
+          const drivers = (await formats()).formats.map((entry) => entry.driver);
+          assert.ok(drivers.includes("pdf"), "discovery did not report the pdf driver");
+
+          // A minimal valid PDF, so the check needs no fixture from the repository.
+          writeFileSync("probe.pdf", "%PDF-1.7\n%%EOF\n");
+          const report = await probeFile("probe.pdf", { targets: ["@header"] });
+          assert.equal(report.schema_version, 2);
+          assert.equal(report.input.source_kind, "local_file");
+          assert.equal(report.driver.id, "pdf");
+          console.log("node entry point, WASM, discovery, and probeFile all work from the registry copy");
+          CHECK
+          node check.mjs "$version"
+
+          # The CLI resolves through its optional platform package.
+          npx --no-install deckprobe --version
+          echo "published $package verified from the public registry"
+
   announce:
     needs:
       - plan
       - host
       - publish-npm
+      - verify-published
     # use "always() && ..." to allow us to wait for all publish jobs while
     # still allowing individual publish jobs to skip themselves (for prereleases).
     # "host" however must run to completion, no skipping allowed!
-    if: ${{ always() && needs.host.result == 'success' && needs.publish-npm.result == 'success' }}
+    # verify-published gates the announcement so a release cannot report success
+    # while the artifact on the public registry is incomplete.
+    if: ${{ always() && needs.host.result == 'success' && needs.publish-npm.result == 'success' && needs.verify-published.result == 'success' }}
     runs-on: "ubuntu-22.04"
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -461,6 +461,14 @@ Schema version 2 uses one JSON envelope on standard output. Top-level `status` i
 - the executed `path` and evidence `source`;
 - deterministic physical-byte, expanded-byte, and random-read counters for the whole probe.
 
+`confidence` records how strong the evidence for a value is — `exact` when it was read from the
+authoritative structure, `high` when it came from a statistic the authoring application saved,
+`medium` when it was inferred from a proxy. The paired `confidence_score` is a **fixed constant per
+label** (`0.4`, `0.7`, `0.95`, `1.0`), not a calibrated probability: `0.95` does not mean the value
+is right 95% of the time. Likewise `partial` only means some requested target was unresolved — the
+other results are still valid, and it is not a verdict on the document's health. See
+[Reading confidence and partial results](docs/CLI-REFERENCE.md#reading-confidence-and-partial-results).
+
 Wall-clock `elapsed_ms` is omitted by default so identical inputs and options produce byte-identical JSON. Add `--telemetry` when timing is needed.
 
 Use `--strict` when unresolved targets should make the command exit non-zero.

docs/CLI-REFERENCE.md

@@ -239,6 +239,86 @@ deckprobe -t slide_count,orientation \
 
 An explicitly named target can be valid for the detected format but unavailable at the chosen level or confidence. If some other requested target can be planned, the report records the unavailable target under `execution.unresolved_targets`. If no requested target has an eligible path, DeckProbe exits with status `1` as an unsupported-target request.
 
+## Reading confidence and partial results
+
+### What the confidence labels mean
+
+`confidence` describes how strong the evidence for one value is, as judged by the path that
+produced it. It is not a measured accuracy rate.
+
+| Label | Score | What normally backs it |
+| --- | --- | --- |
+| `exact` | `1.0` | Read directly from the authoritative structure in the container |
+| `high` | `0.95` | A statistic the authoring application saved, such as the slide count in `docProps/app.xml`. Authoritative unless that application left it stale |
+| `medium` | `0.7` | Inferred from a proxy, such as counting `xl/worksheets/sheet*.xml` parts instead of reading the workbook's declared sheets |
+| `low` | `0.4` | Weak or indirect evidence |
+| `none` | `0.0` | Accompanies a result that carries no value |
+
+**`confidence_score` is a fixed constant per label, not a calibrated probability.** `0.95` does not
+mean the value is correct 95% of the time on real-world files; no corpus measurement backs these
+numbers. Use them to order or threshold results, never to report an accuracy figure to a user.
+
+### Report status versus target status
+
+The report's own `status` is `ok` or `partial`. A result's `status` is one of eight values, and the
+two answer different questions.
+
+`partial` means at least one requested target could not be resolved at the requested confidence. It
+says nothing about whether the document is damaged or unsafe — the remaining results are still
+valid.
+
+```bash
+deckprobe -t slide_count,author --pretty deck.pptx
+```
+
+```jsonc
+{
+  "status": "partial",                       // because author could not be resolved
+  "results": {
+    "powerpoint.slide_count": {
+      "status": "resolved", "value": 31,
+      "confidence": "high", "path": "powerpoint.app_statistics",
+      "source": "docProps/app.xml saved statistic"
+    },
+    "document.author": {
+      "status": "unknown",                   // the path ran; the file records no author
+      "confidence": "none"
+    }
+  },
+  "execution": { "unresolved_targets": ["document.author"] }
+}
+```
+
+The slide count here is perfectly good. Treating `partial` as a failure would discard it.
+
+Contrast that with a structural target the format cannot answer at all:
+
+```bash
+deckprobe -l d -t corrupted report.pdf     # exits 1
+```
+
+`corrupted` and `missing_assets` are declared for every modern format, but only the iWork drivers
+implement a path for them. Naming one on a PDF or OOXML file is an unsupported-target request, so
+DeckProbe exits `1` rather than returning a report. Use the `@quality` selector to get whatever the
+active driver actually supports.
+
+| Result `status` | Carries `value` | Meaning |
+| --- | --- | --- |
+| `resolved` | yes | Obtained at or above the requested confidence |
+| `estimated` | yes | Obtained, but an estimate |
+| `unknown` | no | The path ran; the document does not record this fact. A normal answer, not an error |
+| `unsupported` | no | This format has no path for the target |
+| `invalid` | no | The document records something that fails validation |
+| `budget_exceeded` | no | A limit stopped this target specifically |
+| `failed` | no | The path errored |
+| `planned` | no | `--plan-only` only |
+
+Distinguish `"value": null` on a `resolved` result — the field exists and is empty, which is an
+answer — from `status: "unknown"`, where the probe could not answer.
+
+Use `--strict` when an unresolved target must fail the command; it exits `5` and still writes the
+full report.
+
 ## Input interpretation and format options
 
 DeckProbe uses the normalized filename extension to select a format path, then verifies its signature and internal type. Renaming a PPTX to DOCX, for example, returns `MALFORMED_INPUT`. `-f`/`--input-format` adds another assertion; it does not force an unrelated parser onto the file: