Skip to content

Disable text augmentor output that isn't enabled - #81

Merged
JackLewis-digirati merged 2 commits into
mainfrom
feature/textAugmentorRespectingFlags
Nov 10, 2026
Merged

JackLewis-digirati merged 2 commits into
mainfrom
feature/textAugmentorRespectingFlags

Conversation

@JackLewis-digirati

@JackLewis-digirati JackLewis-digirati commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

Resolves #75

This PR makes it so that the text augmentor will no longer advertise what can't be served, and will instead pick based on the capabilities.json file.

There has also been a change so that if the capabilities.json doesn't exist, the assumption is nothing can be served because this can now only happen to jobs created prior to version 1 (effectively nothing) or pending jobs. Previously, failed jobs would have been included in this, but they have now been fixed to properly clean up after themselves

@JackLewis-digirati

JackLewis-digirati commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

How this works

Fixes #75: the text-augmented Manifest added search, autocomplete, plain text and annotation links whether or not the job asked for them.

1. Every text-augmented link is gated on its flag

TextAugmentedHandler loads the job's capabilities (the services the builder fulfilled) once, and each addition checks its own flag:

Added to the Manifest Flag
SearchService2 / SearchService1 and the search @context entries Search
AutoCompleteService2 / AutoCompleteService1, nested inside the search services Autocomplete, only together with Search (it's described as a child of the search service, so it can't be added alone)
Plain-text rendering link FullText
PDF rendering link Pdf (still skipped for audio/video-only content, because jobs built by v1 marked Pdf fulfilled for that too)
Per-canvas line/word AnnotationPage links and the Manifest-level annotations link Annotations
Figures AnnotationPage link Figures
Per-canvas SVG rendering link Svg (unchanged)

A job with only TextAugmented set gets its stored Manifest back with nothing added except the updated id.

The plain-text link now depends only on FullText. A job with FullText but no Search/Pdf/Svg never saves a Text artefact, so it used to get no plain-text link even though the plain text existed. It now gets one.

2. A missing capabilities.json now means no services are enabled

Previously a missing capabilities file meant every service was enabled. Every release since v1.0.0 writes the file for every completed job, so in practice it was only missing for:

  • jobs still running, including reprocesses after DeleteArtefacts: the Manifest is saved early, before the file;
  • jobs that failed part-way.

Both of these exposed every endpoint, and the text-augmented Manifest linked to every service, including ones never requested.

Now:

  • CapabilitiesExtensions.IsEnabledAsync returns false when there's no file.
  • TextBuildJob writes capabilities.json as the last artefact (it was previously followed by SavePageSequence), so nothing is exposed until all of a job's artefacts are saved.

3. Failed jobs clean up after themselves

  • The catch block in TextBuildJob calls DeleteArtefacts, so a failed job leaves nothing in storage. This includes the late case where the failure happens after the capabilities file was written. If the delete itself fails, the error is logged and the job is still marked Failed.
  • The completion notification is sent once, after the try/catch. A notification failure can't turn a successful build into Failed, and so can't delete its artefacts. IJobNotifier implementations shouldn't throw anyway.

Tests

  • TextAugmentedHandlerTests: one test per flag being off, a TextAugmented-only job, a FullText-only job with no Text artefact, and a missing capabilities file returning 404.
  • TextBuildJobTests: a job that fails at the last write (capabilities) has all its artefacts deleted and sends one Failed notification; a job whose cleanup also fails is still marked Failed and notified.
  • CapabilityGatingTests: direct IsEnabledAsync tests. The handler test stubs that returned null capabilities to mean "everything enabled" now return JobServices.All explicitly.

Docs

docs/builder-api.md (service flags), docs/search-api.md (capability gating), CLAUDE.md, and a new dated entry in instructions/decisions.md. The new entry replaces the earlier "no file = all enabled" rule.

Not in this PR

  • A job with Annotations but none of Search/Pdf/Svg gets the Manifest-level annotations link but no per-canvas links, because those need the Text artefact. The line/word annotation endpoints probably have the same dependency. That's a builder change for a follow-up.

@JackLewis-digirati
JackLewis-digirati marked this pull request as ready for review November 9, 2026 09:33
@JackLewis-digirati
JackLewis-digirati requested a review from a team as a code owner November 9, 2026 09:33
@JackLewis-digirati
JackLewis-digirati merged commit 67de0f0 into main Nov 10, 2026
4 checks passed
@JackLewis-digirati
JackLewis-digirati deleted the feature/textAugmentorRespectingFlags branch November 10, 2026 16:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Text augmentor doesn't respect certain flags

2 participants