Skip to content

haskell(feat[docs]) Document capture, queries and native examples - #293

Merged
tony merged 26 commits into
mainfrom
feat/haskell-capture-docs
Nov 11, 2026
Merged

tony merged 26 commits into
mainfrom
feat/haskell-capture-docs

Conversation

@tony

@tony tony commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Haskell now exposes scoped capture, detached observations, validated offline fixtures, shared Runtime ownership and typed snapshot queries. This follows the initial Haskell registration in #265 and documents the merged native API using its Haddock artifacts and committed reader guides.

Closes #297.

Summary

  • Add native observation and query reference pages with record ownership and accurate source links.
  • Preserve authored export groups, module reexports and typed signatures.
  • Add capture, query, offline fixture, shared Runtime and performance guides from the documented source.
  • Replace the values-only homepage with the native query program, its Cabal files, owned-server setup and checked output.
  • Update the Core Library copy, API links, package discovery, installation requirements and copied setup prompts to match the implemented API.
  • Attribute capture and fetch commands through a reviewed source catalogue.
  • Keep MCP excluded and workspace tooling marked unpublished.

Reference and source fidelity

The exporter preserves the scalar profile and adds qualified observation and query profiles. Record labels retain their owning types, parameterized opaque declarations retain their native heads, and private defining sources receive source links without private API pages. Native artifacts and library/exporter revisions remain independently bound.

The native command catalogue qualifies the complete library, C and package inputs, API metadata and public effect classifications. Capture and explicit fetch receive reviewed entries for display-message, if-shell and session-gated list-clients. Existing evidence, scope and drift checks remain active. Public mutations are not inferred from the private command implementation.

Reader guides

Installation, capture, graph traversal, typed filtering, fixture validation, independent Server scopes, operational recovery and measured capture costs use committed native guides. Long type signatures wrap at valid Haskell boundaries. Collection ordering checks include the snapshot module’s ordinary functions.

The homepage runs the native query example against a private tmux server. It distinguishes physical panes from contextual occurrences, checks cardinality and compares typed selection with an ordinary Haskell predicate. The displayed program, Cabal files and shell recipe run together on both supported CI endpoints. A subshell completes teardown before returning to the caller and preserves an existing caller EXIT trap.

The setup card and copied agent prompts select compatible GHC and Cabal versions from the manifest. Cabal package bounds remain unchanged. Program grids fit narrow pages, while setup files and output keep their natural heights.

Test plan

  • Native exporter and Haskell adapter regressions
  • Haskell declaration rendering, navigation and guide staging
  • Reviewed command catalogue, drift rejection and unchanged generic scanner checks
  • Site type checking and lint
  • Zero unresolved Haskell guide mentions
  • Full site unit suite
  • Clean selected-source assembly and publisher input inventory
  • Haskell-prefix link audit and sampled Chromium layouts
  • Native module/member regressions and the Haskell reference-link ratchet
  • Exact displayed homepage program, expected output and owned cleanup on tmux 3.3a and 3.8
  • Full assembled-site and browser matrix
  • Combined outer loop within its configured budget
  • Hosted publication audit

The source-bound build qualifies the Haskell landing and version prefix. A fresh Astro server separately qualifies the exact shared homepage URL through the existing responsive-layout checks. The Haskell-prefix audit found no broken internal links or unresolved type names. Sampled Chromium pages fit at phone, tablet and desktop widths; the homepage recipe, query guide and native query signatures resolve their current API and source destinations. The native graph fence currently displays as code on the shared site.

Haskell's resolved-reference floor rises to 2,205; its unresolved-type ceiling remains zero. Other ports' baseline rows are unchanged. Native module/member and guide-staging regressions pass. The installed shared Runtime program also passes from its pinned Git dependency on both tmux endpoints.

Full site and hosted publication qualification remain pending for the current head. The exact-head hosted run is queued. The preceding run passed the source suites but found an outdated homepage-hover assertion. The corrected check reads task availability from the prompt policy and passes across every port on a fresh browser context (19.301 seconds). The first hosted run found stale Haskell solution-card wording and package aliases; their corrected target suites pass. The recorded pre-refresh main baseline also exceeds the local ten-second medium-loop limit under the four-core, 8 GiB guard. A diagnostic completion run reached a shared sitemap import deadline; that suite passes in isolation. Workspace type checking passes with an explicit 6 GiB Node heap inside the same job cap. No test budget increase is included, and source-only runs explicitly skip assembled-output checks. The PR remains draft with preview publishing disabled.

Companion PRs

tony added 19 commits November 9, 2026 22:25
why: Shared documentation needs the public record owners and actual
defining sources while retaining native Haskell signatures.

what:
- Add a separate observation profile for the scoped Server and snapshots
- Preserve module reexports and owner-scoped record fields
- Validate compiled exports, native anchors and archived source text
- Retain native inputs and preserve the qualified scalar profile
why: Duplicate record labels and facade reexports need their public
context without changing native names or losing defining sources.

what:
- Adapt the qualified observation profile alongside scalar interfaces
- Retain record owners, native links and ordered module reexports
- Give the reexport root one navigation row without copied members
- Reject incomplete modules and conflicting module identities
why: Public capture and recovery types need readable continuation lines
within the API reference column limit.

what:
- Continue outer type arrows while preserving native links and tokens
- Keep callback scopes, character literals and escaped strings intact
- Leave unbreakable literals exact and report their width
why: The public observation API needs native reference ownership, checked
source provenance and guides that use the same reviewed library revision.

what:
- Publish the Haddock observation model and authored navigation groups.
- Stage capture, offline-fixture and performance guides from source.
- Bind native command attribution to reviewed source and API metadata.
- Exercise snapshot collection ordering and preserve excluded products.
why: Function and type references need declaration-level destinations so
readers reach the named API with the correct language kind.

what:
- Resolve unique public labels within their declared module.
- Prefer data heads for shared type and constructor spellings.
- Preserve ambiguous labels and explicit source-fragment destinations.
why: Compiler extension references need checked destination identity
alongside the package API links.

what:
- Record the owning GHC manual heading for record-dot syntax.
- Capture the successful destination response and identity evidence.
why: The capture API adds an entry module and reverse references beyond the scalar API. Reference checks need to preserve that native structure.
what:
- Derive module sections from the current public model in its declared order.
- Compare exported members within their own sections, excluding backlinks.
why: The capture reference now resolves more native cross-references. Preserve
that coverage as the public API grows.
what:
- Raise the Haskell-only resolved-link floor from 300 to 1372.
- Keep the unresolved-type ceiling at zero and other ports unchanged.
why: The public Runtime API needs reference pages and an installed guide
that agree with the source consumers can build.

what:
- Refresh the native Haddock profile while retaining separate exporter provenance
- Stage the shared Runtime guide and preserve every existing public signature
- Bind queued command evidence and reference fixtures to the selected source
why: Shared Runtime declarations add native links that the reference
regression check must retain.

what:
- Raise only Haskell's floor from the complete rendered reference
- Keep the unresolved-type ceiling and other port baselines unchanged
why: The exact guide-path fixture omitted the shared Runtime page and
rejected the complete public guide catalogue in CI.

what:
- Include the shared Runtime source and reader route in the guide contract
why: The shared reference must preserve the current public query types and
field modules alongside detached snapshots, without exposing implementation APIs.
what:
- Qualify the sixteen-module query profile and its defining source inventory
- Preserve opaque type parameters, constrained signatures and native default sections
- Retain honest file-level source links for ambiguous native identifiers
- Compare native source pages with the merged source and retain compiler fixtures
- Preserve the scalar and observation profiles and their validation checks
why: Parameterized query declarations need source-bound evidence through the
shared adapter, not assumptions carried over from scalar and observation models.
what:
- Record the isolated native export and its committed producer separately
- Retain native signature and defining-source fidelity through normalization
- Check opaque query parameters, field ownership and public reference navigation
- Reject unsupported profiles and declaration forms before rendering
why: Whole native fixture and cross-port manifest audits need the outer tier;
fast adapter and route checks should retain their shorter development loop.
what:
- Classify the complete Python native audit as an outer subprocess check
- Bound that case independently inside the unchanged outer-loop budget
- Move the complete reference manifest assertions into a dedicated outer suite
- Preserve all route, native provenance and cross-port assertions
why: Reference pages, reader guides and command attribution must describe the
same merged public source and preserve its typed query contracts.
what:
- Regenerate the current observation and query model with native provenance
- Stage the query guide alongside capture, fixtures and shared Runtime scopes
- Qualify capture and query-fetch command paths against the complete source
- Keep relationship tokens distinct from commands that change window links
- Validate declaration heads before matching their type parameters
why: Readers need to see the implemented client observe tmux, select panes
and handle errors rather than only construct scalar values.
what:
- Reuse the native query program with complete private-server setup and teardown
- Show physical and contextual selection, cardinality and application errors
- Bind standalone Cabal inputs, expected output and copied programs to the source
- Replace the core copy and link capture, snapshot, query and fixture modules
- Resolve the program's public API links without requiring extra showcase panels
why: A pasted recipe must stop its owned server without replacing the caller shell exit handler.

what:
- Run setup, the native query program and teardown in one subshell
- Check cleanup before the caller exits and preserve its existing trap
- Keep the displayed recipe and execution record identical
why: The expanded reference needs complete native rendering checks and a subprocess deadline that can stop a stalled audit.

what:
- Update signature, link and semantic-kind coverage for the current native artifact
- Keep every declaration and constructor rendering assertion
- Bound the Python fixture process within its outer test deadline
…#293)

what:
- Include the current shared landing layout, capability-panel and badge fixes
- Retain the real-tmux Haskell homepage, public API links and reference qualification
- Carry the current build checkout handling from the shared site

why:
- Validate the refreshed Haskell docs against the current shared site
- Preserve the committed exporter identity already recorded by the native artifacts
@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 10, 2026
tony added 5 commits November 10, 2026 00:15
why: The query guide names Natural, which belongs to base rather than the libtmux declaration catalog.

what:
- Link the documented bound to its verified Numeric.Natural declaration
- Check native type resolution without claiming the name in other ports
- Regenerate the mention index after resolving the guide reference
…cessor

why: Core home entries describe either objects or modules, so their shared type does not expose a lead field.

what:
- Check the rendered Haskell lead through the existing coreLead accessor
- Preserve the content assertion while satisfying both entry variants
why: A long Haskell program expanded the grid beyond the phone viewport, and nested setup blocks inherited the showcase fixed height.

what:
- Give the program grid a column that can shrink to the available width
- Restrict showcase sizing to its direct program block
- Let setup, package files and expected output retain their natural heights
why: Installation cards and copied agent prompts still described the scalar bootstrap and falsely required exact compiler tool patches.

what:
- Lead with the public LibTmux facade, detached graphs and typed queries
- Select compatible tools from the manifest and state the native host requirements
- Run the owned capture/query example while preserving the boundary around unfinished automation
why: The rendered public query surface resolves more references than the observation-only profile, so the existing floor would permit a regression.

what:
- Raise only the Haskell cross-reference floor from the measured selected-source build
- Keep its unresolved-type ceiling at zero and every other port baseline unchanged
@tony
tony changed the base branch from haskell-port to main November 10, 2026 06:35
@tony
tony force-pushed the feat/haskell-capture-docs branch from 790b895 to cc6f9fc Compare November 10, 2026 06:35
@tony tony changed the title haskell(feat[docs]) Document captures and snapshots haskell(feat[docs]) Document capture, queries and native examples Nov 10, 2026
tony added 2 commits November 10, 2026 00:55
…scription

why: The root solution card depended on the old values-only execution profile, and package discovery still listed only scalar modules.

what:
- Select module-home descriptions from the core metadata independently of example execution
- List the public facade, capture, snapshot, query and fixture entry points
- Check the root Haskell card against capture and detached-query behavior
why: A real capture example does not imply that the port can implement every proposed agent task.

what:
- Read task boundaries from the existing prompt policy during language previews
- Verify unavailable tasks retain their boundary instead of requesting missing APIs
@tony
tony merged commit f48b847 into main Nov 11, 2026
5 of 6 checks passed
tony added a commit that referenced this pull request Nov 11, 2026
why: Four kinds of failure reached the ports only when a port built its
own docs, never in docs CI: an unmapped README badge, a checkout path a
wrapper library could not derive, a tmux-usage citation pinned to a line
the port had moved, and a Haskell exporter gap at the port head. The six
new ports' pages also lagged their repositories, and the Haskell front
page described entity IDs instead of the client.

what:
- Resolve every port checkout through one helper, so a wrapper such as
  Clojure derives its parent's checkout (scripts/lib/port-checkout.mjs)
- Fail on any README badge the badge renderer cannot map
  (scripts/check-port-badges.mjs)
- Build every port's head against docs main weekly and on dispatch,
  without publishing (.github/workflows/port-heads.yml); port-docs.yml
  gains an optional source-repository input, so callers are unchanged
- Locate tmux-usage citations by their text within their body instead of
  a stored line (scripts/lib/tmux-usage-locate.mjs, claims.json)
- Bring the Haskell (#293, #300), OCaml (#294, #295), Clojure (#299),
  Erlang, Common Lisp and Perl pages up to each port's source, with
  examples indexes of their tested programs
- Describe a staged guide without a catalog description by its first
  sentence, and title a link to a staged guide instead of naming its file
- List a port's API roots in llms.txt, and mention MCP only for ports
  that ship an MCP server
- Give every language's Core Library card on the front page the same
  one line, and drop the MCP aside from the new ports' landing pages
- Remove two 5-second test timeouts and record Common Lisp's type-link
  baseline at libtmux-lisp e6f319c42

Base main 856211d, head e36e62b. CI run 43009353757.
@tony
tony temporarily deployed to docs-preview-cleanup November 11, 2026 22:49 — with GitHub Actions Inactive

This branch was previously deployed

2 inactive (1 outdated) deployments
docs-preview-cleanup — f48b8476 Deployed Nov 11, 2026 by tony via cleanup #236
docs-preview — 6fe29bc6 Deployed Nov 9, 2026 by tony via publish-preview / publish #1366
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.

Show Haskell capture and query APIs in homepage examples

1 participant