Qualify evaluation bounds, cancellation, retry, and host documentation

Open
  • Is something wrong?
#1,824 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
c
Domain
backend, documentation, testing-qa

Research direction

Start with the required behavior matrix, prerequisites #1819–#1823, and the existing implementation boundaries in #1373, #1375, #1383, #1765, and #1805. Inspect tests/meson.build and meson test --list, then run the relevant session, delta, public facade, continuation/JOIN, TDD, worker, and workqueue tests. Done means every applicable matrix cell has a passing assertion or documented nonapplicability, the five named documentation files and public headers are accurate, and final-SHA build, ABI, sanitizer, platform, and benchmark evidence is recorded.

Written by the indexing model from the issue text.

Description

enhancement track/docs

Outcome

Close #1817 only when an installed-API host can bound/interrupt evaluation, calibrate the allowance from observed work and safely retry, with evidence for the final implementation SHA and honest cooperative-stop documentation.

Parent: #1817. Hard prerequisites: #1819, #1820, #1821, #1822, #1823. Individual implementation issues own their focused tests; this issue audits their assertions, fills real integration gaps and records cross-path evidence rather than adding duplicate tests by filename.

Required behavior matrix

Axis Required evidence
Default/limit no control, zero/unlimited, generous bound, exact bound, mid-evaluation exhaustion, overflow-safe accounting
Work shape deep/multi-relation recursion, acyclic product JOIN, selective/zero-output work, scan/filter/aggregate/sort, actual fallback paths
Cancellation pre-cancel, actual second-thread mid-work request, sticky token, active reset refusal, quiescent reset and late publication request
Retry larger bound, repeated failed attempts, callback and callback-free STEP, evaluating/typed SNAPSHOT, insert and retract, later session reuse
Publication zero events/tuples on stopped evaluation; one complete baseline-relative signed delta after successful STEP retry; no partial-delivery cancellation failure
Parallel W=1/2/8 with actual-path evidence; recursive/nonrecursive TDD, ordinary JOIN, K-Fusion if enabled, inline/fallback/replay; global budget not per-worker
Ownership partial submission, retained cleanup refusal, source/cache/arrangement leases, queue payloads, no leaks or poisoned sessions after recovery
Public API easy lazy/eager, advanced ordinary/extension snapshot, legacy prefixes, installed C/C++ usage, distinct stop errors and reports
Memory interaction work exhaustion vs memory denial, both orders of failure, reservation balance or explicitly retained ownership after stop/drain

A generous budget/control-absent run is an independent expected-results oracle, not just a tuple-count comparison. Compare relation-qualified canonical content and signed multiplicity where applicable. Cancellation tests coordinate with deterministic barriers/hooks; wall time is a hang watchdog, not the main correctness assertion. Worker count alone does not demonstrate a parallel code path. Do not require cross-width work/iteration equality.

Documentation and host example

Update docs/SEMANTICS.md, docs/MEMORY.md, docs/THREADING.md, docs/ERROR_MODEL.md and public header comments with:

  • exact work metric, maximum polling quantum per engine path, admitted vs consumed units, overflow and attempt reset semantics;
  • token ownership, permitted concurrent cancellation, quiescent update/reset, destruction and signal-safety rules;
  • one completed report per external attempt, cumulative counting across internal replay/resume, distinct stop vs engine/memory errors;
  • baseline/retry and publication commit boundary, including no-callback sessions and evaluating snapshots;
  • memory governor independence and cleanup after exhausted allowance;
  • cooperative limitations: host extension functions/output callbacks, synchronous runtime/library operations and drain/cleanup costs; no promised wall-clock deadline;
  • an installed-header host example that reports the used budget, increases it or resets cancellation, retries, and releases retained handles correctly.

Remove/reconcile the false pre-feature cancellation claim in docs/THREADING.md §9. Reconcile atomic-site inventories and source anchors when atomics are introduced. Keep trusted-program threat-model assumptions unchanged.

Validation and closing evidence

Baseline analyzed for planning: e8e977ec6ffcc0bcc0b0a4aae56bb842da34b389; implementation evidence must name its own final candidate SHA, toolchain, build options and actual commands/results.

  • Register and run the new control/retry/work/cancel tests plus relevant existing session, delta, public facade, continuation/JOIN, TDD, worker and workqueue tests. Inspect tests/meson.build/meson test --list for real test names; the early comment claiming delta/session tests are disabled is stale.
  • Run the full configured Meson regression suite and ABI suite for the final code candidate, ASan/UBSan, supported pthread TSan (-Dthreads=posix), and applicable existing Windows/macOS build coverage. Report unavailable platform evidence as outstanding, not passed.
  • Use existing benchmark workloads to measure default-control overhead and enabled-checkpoint overhead with matched build/data/worker configuration. Publish raw repeated samples and variation; investigate material unexplained regressions. Do not reuse historical timings as measured results or introduce a new unrelated performance threshold.
  • Audit coverage against the table and list the concrete test assertion/checkpoint proving each cell. Add tests only for uncovered requirements.
  • For #1373 bounded channels, test full-channel blocked-producer stop if the mechanism is present. Otherwise record the current nonblocking transport behavior and link the stop/wake contract that #1373 must preserve; do not claim a nonexistent scenario was run.

Acceptance

  • Every original #1817 criterion maps to merged implementation and passing final-SHA evidence; no essential behavior deferred to an unrelated future issue.
  • All matrix cells have concrete passing assertions or an explicit nonapplicable configuration reason consistent with the shipped support contract.
  • Documentation names finite engine polling units and the limits on return latency accurately; host examples use only installed APIs.
  • Default behavior, error mapping, ABI, ownership accounting and sanitizer checks pass; remaining platform evidence and genuine regressions block their applicable acceptance.
  • Parent #1817 is updated with implementation/evidence links. Creating these planning issues alone is not grounds for closure.

Existing ownership boundaries

#1373/#1383 retain channel/memory-backpressure ownership, #1765/#1805 retain existing cleanup-defect ownership, and #1375 retains K-Fusion retirement ownership. Reuse applicable merged fixes/evidence and explain any unresolved reachable blocker. Closed #1812 is historical lifetime evidence, not an unfinished prerequisite. No new deadline feature or full bounded-DOOP qualification project is introduced.

Dominant language
C
Stars
18
Forks
2
Avg merge
9h 45m
Merged PRs (30d)
162

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from semantic-reasoning/wirelog

All issues in semantic-reasoning/wirelog

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.