Skip to content

docs(compound): guide users to negation workaround for side compounds - #921

Merged
justinjoy merged 1 commit into
mainfrom
docs/negated-side-compound-workaround
Jun 20, 2026
Merged

docs(compound): guide users to negation workaround for side compounds#921
justinjoy merged 1 commit into
mainfrom
docs/negated-side-compound-workaround

Conversation

@justinjoy

Copy link
Copy Markdown
Collaborator

Summary

Negating a side-tier compound body pattern (e.g. !event(ID, metadata(...))) is rejected at IR conversion because negated side-join lowering is not yet implemented. This is a narrow limitation — it fires only when all three hold: (1) the atom is negated, (2) the column is a side-tier compound, and (3) the body pattern destructures it with functor syntax. Negating presence (!event(ID, _)), inline compounds, and positive destructuring all work today.

Crucially, expressive power is unaffected: extracting the compound fields in a positive rule and negating the resulting flat relation is fully supported and stratifies naturally. This PR makes that workaround discoverable instead of leaving users stuck on an opaque error.

Changes

  • wirelog/ir/program.c — extend the IR-conversion error message to name the workaround and point at the docs.
  • docs/COMPOUND_TERMS.md — add a "Negation and side compounds" section documenting the exact trigger conditions, the unsupported form, and the supported positive-extraction pattern; link it from the Errors table and TOC.

Behavior / risk

Behavior is unchanged — the pattern is still rejected. Only the log string and documentation change.

Testing

  • Clean build compiles.
  • meson test wirelog_easy wirelog_advanced pass (includes the negated-side-compound rejection test and side-compound binding tests).
  • Full suite: 249 pass / 10 skip; the single failure is sbom_snapshot (dependency-manifest baseline check), which is environmental and unrelated to a log-string + docs change.

Follow-up

Full negated side-join lowering implementation remains deferred; promote when real demand accumulates or language orthogonality becomes a release goal.

Negating a side-tier compound body pattern (e.g. !event(ID, metadata(...)))
is rejected at IR conversion because negated side-join lowering is not yet
implemented. The expressive power is unaffected: extracting the compound
fields in a positive rule and negating the resulting flat relation is fully
supported and stratifies naturally.

Make that workaround discoverable instead of leaving users stuck on an
opaque error:

- Extend the IR-conversion error to name the workaround and point at the docs.
- Add a "Negation and side compounds" section to docs/COMPOUND_TERMS.md
  documenting the exact trigger conditions, the unsupported form, and the
  supported positive-extraction pattern.

Behavior is unchanged (the pattern is still rejected); only the log string
and documentation change. Existing rejection tests continue to pass.
@justinjoy
justinjoy enabled auto-merge (rebase) June 20, 2026 06:36
@justinjoy
justinjoy merged commit c484902 into main Jun 20, 2026
26 checks passed
@justinjoy
justinjoy deleted the docs/negated-side-compound-workaround branch June 20, 2026 07:24
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.

1 participant