Skip to content

haskell(feat[docs]) Document creation and owned-server lifecycle - #309

Draft
tony wants to merge 58 commits into
mainfrom
feat/haskell-creation-docs
Draft

tony wants to merge 58 commits into
mainfrom
feat/haskell-creation-docs

Conversation

@tony

@tony tony commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Haskell callers can create sessions, retain target references through uncertain completion, and use an owned server scope. The reference preserves the exported fields of constructor-hidden receipts, and the guides, examples and command listings cite the qualified native source. The lifecycle implementation still awaits master integration.

Summary

  • Export creation declarations, recovery and owned-server configuration from the native Haddock interface, checking field ownership and types against compiler source annotations.
  • Refresh API, source guides, package metadata and command-use evidence at qualified lifecycle source.
  • Keep creation recovery and owned-server configuration with the server scope in navigation.
  • Document private server scopes through withOwnedServer and explicit daemon retirement through killServer.
  • Refresh the complete homepage program, source-install project and native playback; classify the hook-free version and process identity reads as probes.

Design decisions

The fixture records its retained library and producer commits separately. Earlier qualified profiles keep their own validation. Private defining files remain source destinations rather than public modules.

The homepage records its program source separately from its dependency pin. Its Cabal project uses the committed source-install recipe. Playback retains the library's version and process identity probes with stable nonces and checks the existing per-capability revision override.

Validation

  • Native export and model: 412 symbols, 43 source-file hashes, 335 command classifications and 19 Haskell claims
  • Fixture-based Python audit: 32 tests and 46 subtests
  • Navigation, creation and lifecycle suites
  • Homepage and playback checks, including the recording on released tmux 3.8
  • Exact displayed homepage execution on released tmux 3.8, expected output and daemon cleanup
  • Source command-use checks and global navigation validation
  • Pass the complete local outer gate within its 60-second budget; timeout diagnosis is in progress
  • Complete independent fix review and exact-head hosted publication checks

The corrected playback and homepage checks pass. Full local qualification remains incomplete: the parallel outer runs still fail on timed provenance and audit checks. The existing budgets remain in force.

Companion source

Session creation and recovery is merged. The lifecycle records use the qualified topic source above while startup safety and fixture cleanup qualification continue. Shared-site publication remains with the docs coordinator.

@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 12, 2026
tony added 4 commits November 15, 2026 10:51
why: Session creation adds opaque receipts whose exported record labels are omitted from Haddock declarations.

what:
- Add a creation profile with its public module and recovery origin
- Check field owners and types against GHC source annotations
- Preserve compiler-qualified public owners for shared record labels
- Retain native source fixtures and reject mismatched field evidence
why: Readers need discoverable creation fields and recovery without exposing private constructors or implementation modules.

what:
- Adapt the creation profile and its public module navigation
- Retain the source-bound native artifact and producer identity
- Resolve declaration links and check constructor opacity
- Cover both valid compiler destinations for shared field labels
…data

why: Callers need the creation API, installed examples and recovery guide to describe the same public source.

what:
- Refresh the Haskell API, navigation, guide and command evidence caches
- Add the session-creation guide and task-oriented core-library copy
- Bind the executable homepage recipe to the reviewed public package
- Derive Haskell rendering assertions from the authenticated native fixture
why: Example links and staged navigation must describe the same public creation revision as the API.

what:
- Include the installed creation program and link every example at the model revision
- Explain when mutating examples need a fresh demonstration server
- Check creation guide routes and derive the staging description from canonical metadata
@tony
tony force-pushed the feat/haskell-creation-docs branch from 3edf835 to b24c03c Compare November 15, 2026 19:15
tony added 7 commits November 15, 2026 13:23
why: Creation export checks need isolated inputs and source references
that remain available after the creation stack lands.

what:
- Exercise creation field ownership and type checks with pytest fixtures
- Derive native package-unit names from compiler evidence
- Refresh the native fixture at retained source and producer commits
why: The reference and guides must describe the public library and keep
creation recovery beside its server scope.

what:
- Refresh native API, guide, package and command-use evidence from
  master
- Place creation declarations and recovery helpers with their tasks
- Update source links and contributor guidance for the current transport
why: Playback must match the displayed program and distinguish server
admission probes from application commands.

what:
- Refresh the source-pinned homepage, native proof inputs and recording
- Recognise and redact the nonce-qualified hook-free version probe
- Check the recording capability revision and preserve ordinary commands
why: Generic name rules separate creation options and process choices
from the session API that uses them.

what:
- Place creation options and process types under Session
- Check their placement against the native creation fixture
why: Callers need the current command limits and a fresh demonstration
server before examples that change its state.

what:
- State the daemon setup requirement and unfinished commands
- Restore the fresh-server instruction for mutation examples
- Describe the recording default and capability source revisions
why: A forged field must fail its source, type or owner check rather
than
an unrelated validation step.

what:
- Assert the specific diagnostic for each native field defect
why: The source guides use the current record-dot URL while the link
review and evidence still name its versioned address.

what:
- Review the current GHC record-dot page
- Refresh its verified destination without changing other records
@tony
tony force-pushed the feat/haskell-creation-docs branch from b24c03c to d4c0d23 Compare November 15, 2026 19:38
tony added 8 commits November 15, 2026 14:02
why: Port checkouts carry their own Python configuration and must not
expand the documentation repository's lint surface.

what:
- Exclude .port-sources from recursive Ruff discovery
- Exercise a nested port configuration alongside an owned defect
- Run the fixture through the outer suite
why: Symbolic release forms in the staged guide were counted as
missing API references and exceeded the rendered build ceiling.
what:
- Classify Haskell release patterns without hiding missing APIs
- Render staged Haskell guides in the dangling-reference regression
why: The mention index still marked the Haskell guide's symbolic tmux
release patterns as unresolved after the prose classifier recognized
them. Its freshness check therefore rejected the matching source change.

what:
- Regenerate the index to remove the three Haskell pattern diagnostics.
- Preserve every symbol backlink and other port's unresolved entries.
why: The reference, guides and command evidence described the library
where every daemon was started and stopped by the caller. The lifecycle
source adds withOwnedServer, defaultOwnedServerConfig, OwnedServerConfig
and killServer, and readers need to see which of them send tmux commands
and which only signal a process.

what:
- Refresh the Haskell API model, navigation and source paths from the
  qualified native export of the lifecycle source and keep that export
  as a rendering fixture beside the earlier creation fixture
- Place the lifecycle declarations beside withServer in the Server
  navigation and add the lifecycle guide to the Haskell routes, guide
  cache, mentions, package manifest revision and Core landing copy
- Re-review the native usage profile for the new inventory and six new
  public declarations; record the start-server, set-option and hook-free
  identity and version probes of withOwnedServer; rebind the withServer
  probe chain through captureProbe and probeArguments; review killServer
  as a pidfd signal that sends no kill-server
- Repin the examples index to the lifecycle source and add the
  owned-server program

Source: libtmux/libtmux-haskell feat/owned-server-lifecycle at
03c914a6298708c786cea21233eb39acf9b7c085, exported by producer
7f5c4e2 (GHC 9.14.1, Haddock 2.33,
Cabal 3.18.2.0). The lifecycle source is not merged to the library's
master.
why: withServer now reads the daemon's process ID through a second
hook-free run-shell before the callback runs. The recorded landing
program must show it as a probe, not an application command, and the
landing page must install the library at the lifecycle pin.

what:
- Recognise and redact the nonce-qualified #{pid} probe beside the
  #{version} probe
- Re-record the landing program against the library at its pinned
  install revision with tmux 3.8a
- Refresh the landing record and its fixture hashes for the new
  cabal.project pin
why: main gained a generated cache of the source files each API model
cites, and its test-all gate compares it with the model. The branch's
Haskell model moved to the lifecycle revision, so the cache must be
regenerated on a base that already contains it.

what:
- Merge origin/main without conflicts
- Regenerate the Haskell source cache in the next commit
…e model

why: main's test-all gate compares the cached bytes of every file an API
model cites with the model's revision. The Haskell model now cites the
lifecycle source, so the committed cache was stale and the hosted run
failed at that step.

what:
- Regenerate the Haskell source cache from the committed files at the
  model's revision
why: Haskell playback must reflect a released tmux version used to
qualify the port, including the captured server version.
what:
- Regenerate the landing program recording with tmux 3.8.
@tony tony changed the title haskell(feat[docs]) Document session creation and recovery haskell(feat[docs]) Document creation and owned-server lifecycle Nov 16, 2026
tony added 6 commits November 15, 2026 23:41
why: The loops launched every check at once. On a CPU-limited job that
start-up burst shared the cores among far more runnable work than they
could run, which stretched subprocess tests past their own wall-clock
limits. The Haskell native audit (uv and pytest) and the prose audit CLI
timed out although each finishes in a few seconds alone, and a loop that
could not fit its budget read as a test defect.

what:
- Add cpuBudget, which starts work in arrival order while its CPU cost
  fits the CPUs Node reports for the job, a cgroup quota included.
- Queue loop checks through it: a vitest suite costs one CPU per worker,
  with workers capped at the job's CPUs, and other checks cost one.
  Short checks queue first; the site suite, type checks and the browser
  sample queue last.
- Report an over-budget loop as "cancelled or exceeded" instead of the
  exit status of whichever child the deadline killed first.
- Cover arrival order, oversize work and cancellation in
  site/test/cpu-budget.test.ts, and describe the scheduling in
  CONTRIBUTING.md.
why: The bounded browser sample slept through the status badge hover
dwell and close delay and the link preview dwell. Of its 138 s, about
35 s was idle waiting: 47 waitForTimeout calls plus waits on the card
to open and close, with the page and the CPU idle. A sleep also races
the delay it waits out when the host is loaded.

what:
- Add holdClock to browser-context.mjs. It pauses a page clock that was
  installed before the page loaded, so the page's own timers are the
  clock's and clearTimeout can cancel them. A timer set before the
  install survives its clear and closed a hover-opened card.
- Install the clock when checkStatusBadges and checkBlockLinksUndecorated
  create their pages, and advance it with runFor where they slept or
  waited: the 500 ms hover dwell, the close delay, the card staying open
  under the pointer, a tapped card, and the preview dwell on block links.
- Keep every assertion, route, viewport and negative control. Moving the
  hover dwell to 100 ms still fails "a passing pointer leaves the card
  closed", and a block link that becomes a preview candidate still fails
  "Block links with a preview line".

Sample 138.4 s -> 98-103 s; --status-badges 318.8 s -> 234.4 s.
why: The Haskell draft must retain its existing PR ancestry while using
current documentation layouts and source mappings.

what:
- Integrate docs main at 1bc6579
- Preserve the Haskell draft at aaf70d1
- Retain main's current OCaml index alongside the draft Haskell index
why: The Haskell documentation draft should not change the shared test
scheduler or browser timing behavior.

what:
- Restore the test runner and three browser helpers to docs main
- Remove the draft-only CPU scheduler helper and its tests
- Preserve Haskell native export and playback qualification

Main reference: 1bc6579.
why: The draft reference advertised an unshipped server lifecycle while
omitting the current creation source from reader records.

what:
- Replay source-checked hosted Haddock inputs for shipped session creation
- Pin the public model, source cache, guides and command claims together
- Describe seven shipped programs and preserve historical fixture coverage
- Keep startup and daemon retirement outside the advertised API

Source: a1b058b3143587b1fbb7846a6ac846bcc22e94a4.
Native inputs: libtmux/libtmux-haskell run 44446435812, artifacts
14492784327 and 14492809551; the model records their replay provenance.
why: Agent prompts denied the public createSession operation and could
send callers away from an available API.

what:
- Name detached session creation on an existing daemon
- Keep the startup, pane, event and workspace boundaries explicit
- Add LibTmux.Creation to package discovery aliases
tony added 3 commits November 18, 2026 22:09
why: The shipped pane capture module and creation receipt aliases add native interface shapes outside the previous Program profile.
what:
- Bind the pane text profile to its public and private native inventories
- Preserve compiled receipt type synonyms and validate their public target
- Keep older profiles closed to the new declaration shape
why: Landing playback must execute the displayed program against the same shipped source revision.
what:
- Replace the archived lifecycle trace with a fresh exact and marked run
- Record the borrowed handle preflight on released tmux 3.8
why: Creation aliases and pane operations must retain their actual native types while remaining discoverable by task.
what:
- Retain the source-checked pane interface and reject unqualified synonyms
- Keep shared receipts with Server and target operations with their object
- Refresh Haskell navigation without changing the current source pin
why: The combined public source exposes environment values and reexports named layouts from their private defining module.
what:
- Bind the environment profile to all public modules and defining sources
- Retain existing native declaration and alias checks across older profiles
@tony

tony commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor Author

Heads-up for this PR's next pin of libtmux-haskell.

libtmux-haskell#54 adds "What is on here" capability directories to the Session, Window and Pane Haddock (design record 0057, adoption step 40): 12, 16 and 18 rows, 0 dangling references. Once it merges, the pin this PR takes will carry them.

The extractor at this PR's head (3327720) fails on haskell master d81c3cd, on NamedLayout, which LibTmux.Server exports from LibTmux.Internal.Command (ValueError: Unsupported cross-module native source: LibTmux.Server: src/LibTmux.Internal.Command.html#NamedLayout). Adding that module to the pane origins in both packages/api-model/scripts/export-haskell.py and packages/api-model/src/languages/haskell.ts was enough to export the model and fold the three directories:

 PANE_ORIGINS = [
     *PANE_MODULES,
     *(module for module in PROGRAM_ORIGINS if module not in PROGRAM_MODULES),
+    "LibTmux.Internal.Command",
 ]
 const PANE_ORIGINS = [...PANE_MODULES,
-  ...PROGRAM_ORIGINS.filter((module) => !PROGRAM_MODULES.includes(module))]
+  ...PROGRAM_ORIGINS.filter((module) => !PROGRAM_MODULES.includes(module)), 'LibTmux.Internal.Command']

This was a scratch run, not a fix for this branch; the owner of this PR decides the right origin list.

Timing: docs main freezes for the r32 publish wave from the merge of #334 (expected around 02:00 CST) until its live checks pass.

tony added 24 commits November 18, 2026 22:51
why: Shared signatures can omit raw text, so the synonym check must establish a string before applying its expression.
what:
- Guard the native type synonym check without changing profile or provenance validation
why: Public environment and window-context declarations need exact defining-source coverage and task navigation.
what:
- Retain the source-checked combined interface and private layout origin
- Reject missing defining files and earlier module profiles
- Place text waits and contextual operations with their target tasks
- Document all qualified native profiles and raw hosted inputs
why: Native record fields escape g, so a random sandbox name containing
that letter could bypass the literal path replacement and fail playback.

what:
- Let the Haskell recipe supply its encoded sandbox prefix for redaction
- Keep raw replies and the final host-path refusal unchanged
- Cover the escaped prefix and preserve unrelated escaped text
why: The reference and examples must use the same shipped source and
execution evidence as creation, input, text and environment operations.

what:
- Pin native declarations and source records to
  ac127a605d6861d912d89efb9199d470bbfbb987
- Document Program ownership, contextual creation and pane operations
- Review native command effects and preserve source-only installation
- Import fresh released-tmux playback from the exact displayed inputs
- Qualify every header by module within the existing test time limit
why: The Haskell draft must retain the site's current navigation, touch
controls and build behavior when it is updated through its existing ref.

what:
- Integrate main at a626ef8
- Preserve the fixed Haskell source, native records and fresh playback
why: The public option facade exports catalogue types defined in a
private module, so its native interface needs both exact source origins.

what:
- Qualify the options/1 profile with22public modules and35source origins
- Preserve earlier profiles and native visibility checks
why: Native server functions still belong with the tmux object they
change, and the option facade needs its own reference entry.

what:
- Keep the compiled settings interface and its private catalogue origin
- Place absolute resize calls with panes and windows
- Place the option module with its catalogue and settings
- Check native object directories without changing their source prose
why: Shipped facade and guide additions must keep navigation, home
metadata and verified example inputs consistent in the complete site.

what:
- Link guide dependencies to their pinned Haskell package declarations
- Preserve missing-name reporting and explain the With naming suffix
- Place handle capabilities with Server and check scoped target roles
- Align home metadata and shared project hashes with displayed inputs
- Regenerate Haskell navigation and dangling-reference records
why: Capability discovery has an established bucket distinct from the
Server handle, while target operations belong with their tmux objects.

what:
- Restore the curated serverCapabilities placement and its sidecar
- Keep the site expectation consistent with the package navigation check
why: Native section headings do not identify module exports, and their
English label must not control whether the interface can be consumed.

what:
- Recognize the first plain interface h1 without comparing its text
- Check changed headings against real native creation HTML while preserving
  all declarations, reexports and section membership
why: The next fixed native batch needs the current draft corrections and
the structurally qualified Haddock heading parser in one reviewable tree.

what:
- Preserve the exact current draft and isolated heading commits in ancestry
- Retain the separate native options profile and task navigation support
why: The native resizing guide names IO (), whose unit application was
left unresolved by both declaration and prose linkers.

what:
- Normalize Haskell unit applications without changing other languages
- Keep unknown type names unresolved and cover the native guide spelling
why: Explicit option deadline variants fell through to Server because the
shared name rule recognizes the ordinary option suffix.

what:
- Place both Haskell variants in the existing option-functions child
- Preserve the explicit parent placement and other language navigation
- Check settings, buffer and geometry ownership against the expanded model
…source

why: The Haskell reference and guides need the shipped binary buffer,
absolute resize and scoped settings contracts alongside native object tables.

what:
- Bind 716 native declarations and 35 source files to the selected library
- Stage buffer, resize and option guides and expose the options module
- Refresh reviewed command evidence and homepage installation inputs
why: The native control batch adds public stream and recovery modules,
including selected Program cleanup imports with a different canonical owner.

what:
- Add the exact 24-module and 38-origin control profile
- Retain canonical Program declarations for checked Recovery reexports
- Preserve compiled export multiplicity and earlier profile qualification
why: The shared model must retain native STM reads and canonical Program
cleanup owners when the new recovery module imports selected declarations.

what:
- Store the source-bound 789-symbol native control export
- Check opaque control ownership and selected Program cleanup references
- Reject changed import owners and older module profiles
why: Recovery is now a public module, and STM event reads observe owned
mutable state without dispatching a tmux command.

what:
- Curate recovery owners and structured operational failures by role
- Classify local control observations separately from pure detached values
- Preserve complete source-bound callable and command coverage
why: Haskell readers need the native control scope and recovery facade
alongside the exact guide, example and command evidence for that library.

what:
- Bind the reference and source records to the selected control batch
- Stage control and capability guides and retain canonical Program imports
- Describe attached observer effects and the absence of a command writer
- Refresh source usage and the homepage installation provenance
why: The selected native component replaces eight query field modules
with one public Fields facade while retaining the control and recovery APIs.

what:
- Add the exact 17-module and 31-origin fields profile
- Preserve earlier compiler-qualified module layouts and import checks
why: The consolidated facade must keep each field row and relationship
meaning while excluding the removed field-module layout.

what:
- Store the source-bound 805-symbol native field export
- Check field prefixes, relationship types and captured version metadata
- Reject the prior control-only module profile
why: The source-owned daemon scope and explicit retirement operation need the same native provenance as the captured graph API.

what:
- Retain the exact compiled interface export and source hashes
- Check scoped startup, retirement and public configuration signatures
why: The displayed program starts and retires its own daemon and reads detached snapshots after the scope returns.

what:
- Keep the real foreground launcher on the PID the Haskell library owns.
- Expose the private socket directory to the recorder inside Bubblewrap.
- Record creation, retirement and detached reads, and normalize native framing tokens.
…ecords

why: The reference, guides and runnable homepage must describe the same public Haskell behavior and preserve the provenance of its native evidence.

what:
- Qualify the complete public interface and defining source files
- Map daemon scopes, consolidated fields and the external MCP adapter guide
- Preserve the exact recorded example and review native command effects
- Refresh source links, navigation, installation metadata and reader indexes
why: The Haskell quickstart owns its daemon, and verified example pins can precede guide-only API updates.

what:
- Assert owned scope calls and the Cabal setup and run commands
- Check required example paths, unique source links and the recorded source fixture

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