Skip to content

Add OCaml workspace interruption guidance after the release - #294

Draft
tony wants to merge 3 commits into
mainfrom
followup/ocaml-workspace-docs-3935b3a
Draft

tony wants to merge 3 commits into
mainfrom
followup/ocaml-workspace-docs-3935b3a

Conversation

@tony

@tony tony commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add a complete workspace interruption guide and task-page navigation.
  • Refresh API contracts, package catalogs, example provenance, guide bodies and source citations.
  • Preserve partial workspace qualification and unresolved streaming failures.

Applications need to retain the execution journal outside cancellation and client cleanup, inspect reported creations, and check compensation without assuming program effects were undone. The guide uses the installed, independently exercised native example. The updated backend contracts state the compensation default and the journal's in-memory lifetime.

Integration

This draft targets main after the combined new-port release in #291. API and source caches follow the published native source, with separate exporter provenance. The deferred constructor-parser change remains a separate follow-up. The no-preview label holds preview publication.

Test plan

  • Real selected-source export and isolated rejection controls, including unchanged-output assertions.
  • OCaml and Clojure adapter suites (2.023 s).
  • OCaml documentation, navigation, source-staging and package suites (5.557 s).
  • API model, staged guides and mention freshness (combined checks: 4.806 s).
  • Revision-bound package inventory and example caches (included in the combined freshness checks).
  • Source-link destinations (0.148 s).
  • Selected-port render (73.452 s) and owned-link/fragment audit (23.323 s).
  • Rendered navigation, compensation defaults, compatibility rows and unchanged example blocks.
  • Package-scoped type-aware lint for the guide catalog (0.795 s).
  • Existing OCaml cross-reference floor and type-link ceiling, with tracked thresholds unchanged.
  • Complete assembled-site audit, cross-port browser/search checks and hosted CI for this follow-up.

The render is a qualification build, not evidence that the development-loop budget passed. The latest local outer check fails on the resolver corpus test's five-second timeout (39.809 s for the command); broader type checking was interrupted. Earlier independent source review found no remaining findings. The complete example and its displayed commands retain their installed-consumer evidence; no new local real-tmux run was performed for this documentation refresh.

Qualification limits

The latest native master CI passed quality and tmux 3.3a, but failed the tmux 3.8 installed stream-gap walkthrough after gap and fresh-coverage output with outcome unknown: disconnected: bound daemon exited. The later documentation step was skipped. The daemon's exit cause remains unresolved.

The published native source CI passed quality and both tmux endpoints. That positive sample does not resolve the later streaming failure or earlier findings. The guide preserves the earlier workspace readiness finding, installed stream-gap FAIL/FAIL and final-suite UNVERIFIED/UNVERIFIED. Full native qualification and package adoption remain on hold. This draft leaves producer/publisher pins and production publication to the shared-docs owner.

why: Workspace callers need a complete interruption example with
retained evidence, compensation limits and navigation from task pages.

what:
- Add the source-owned workspace recovery route and overview links
- Refresh native contracts, guide bodies, source links and mentions
- Preserve partial qualification and unresolved streaming results

Native source: 3be232388ec28a260bb87c20e410af2dfa7b1fa2
@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 9, 2026
why: Revision-bound package and example catalogs must describe the
same native source as the refreshed API model and guides.

what:
- Regenerate the OCaml manifest inventory at the selected source
- Align embedded example provenance without changing source bytes
- Preserve every sibling catalog entry
@tony
tony changed the base branch from release/combined to main November 10, 2026 01:33
why: The interruption guide needs public contracts, examples and source
citations from one native revision. The released builder validates its
compiled inputs and native exporter separately.

what:
- Integrate the released docs baseline without rewriting branch history
- Regenerate OCaml API, guide, example and package provenance
- Keep recovery navigation and unresolved qualification limits

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-preview Run CI without publishing a PR preview.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant