Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Default owner for everything in this repository.
* @phenixrizen
83 changes: 83 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
name: Bug report
description: Something evaluates or behaves incorrectly
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
A minimal decision graph plus its input is by far the most useful thing you can give us.
Without one, most evaluation bugs cannot be reproduced.
- type: textarea
id: what-happened
attributes:
label: What happened
description: What you observed, and what you expected instead.
validations:
required: true
- type: textarea
id: graph
attributes:
label: Decision graph
description: The smallest JDM graph that reproduces this.
render: json
validations:
required: true
- type: textarea
id: input
attributes:
label: Input
description: The context passed to the evaluation.
render: json
validations:
required: true
- type: textarea
id: output
attributes:
label: Actual output
description: What came back, including any error.
render: json
validations:
required: false
- type: dropdown
id: binding
attributes:
label: How are you calling it?
options:
- Rust crate
- Go
- NodeJS
- Python
- C / FFI
- UniFFI
- Other
validations:
required: true
- type: input
id: version
attributes:
label: Version or commit
placeholder: "v1.0.0-beta.12, or a commit SHA"
validations:
required: true
- type: input
id: features
attributes:
label: Cargo features enabled
description: Numeric behaviour differs with `arbitrary_precision`, so this matters for anything involving numbers.
placeholder: "default, or arbitrary_precision"
validations:
required: false
- type: input
id: platform
attributes:
label: Platform
placeholder: "linux-x64-gnu, macOS arm64, ..."
validations:
required: false
- type: checkboxes
id: upstream
attributes:
label: Upstream
options:
- label: I checked whether this also reproduces on upstream `gorules/zen`
required: false
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Bug in upstream ZEN, not specific to this fork
url: https://github.com/gorules/zen/issues
about: If it reproduces on gorules/zen, report it there too so both projects benefit.
- name: Security vulnerability
url: https://github.com/phenixrizen/zen/security/advisories/new
about: Report privately through a security advisory. Please do not open a public issue.
- name: JDM standard and documentation
url: https://docs.gorules.io
about: The JDM standard is GoRules'. Their documentation is the reference.
32 changes: 32 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
name: Feature request
description: Suggest a capability or improvement
labels: ["enhancement"]
body:
- type: textarea
id: problem
attributes:
label: What problem are you trying to solve?
description: Describe the situation, not the solution. What can you not express today?
validations:
required: true
- type: textarea
id: workaround
attributes:
label: What are you doing instead right now?
description: If there is a workaround, showing it helps size the gap.
validations:
required: false
- type: textarea
id: proposal
attributes:
label: What would you like to see?
description: If you have a shape in mind, sketch it. A JDM snippet or API signature is ideal.
validations:
required: false
- type: checkboxes
id: scope
attributes:
label: Scope
options:
- label: This is a change to the JDM standard itself (GoRules owns the standard; this fork tries to stay compatible with it)
required: false
40 changes: 40 additions & 0 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Security Policy

## Reporting a vulnerability

**Do not open a public issue for a security problem.**

Report it privately through GitHub Security Advisories:
[Report a vulnerability](https://github.com/phenixrizen/zen/security/advisories/new).

Please include what an attacker can achieve, a minimal reproduction (a JDM graph and input if the
issue is in evaluation), and the affected version or commit.

## What to expect

This fork is maintained by one person, so response times are best-effort rather than contractual:

| stage | realistic timeframe |
| --- | --- |
| Acknowledgement | within a week |
| Initial assessment | within two weeks |
| Fix or mitigation plan | depends on severity and complexity |

If you have not heard back in two weeks, please ping the advisory thread.

## Scope

In scope: the Rust crates in this repository — evaluation, expression handling, the database node
and its SQLite handler, and the bindings.

Particularly interested in: anything that gets untrusted graph or expression input to escape its
evaluation boundary, reach the filesystem, or reach a database outside its configured root; and
any way to get a value into SQL statement text rather than a bound parameter.

Out of scope: vulnerabilities in upstream `gorules/zen` that are not specific to this fork should
also be reported to [upstream](https://github.com/gorules/zen). Denial of service from a graph you
authored yourself is not a vulnerability — evaluation is not sandboxed against its own author.

## Supported versions

Only the latest `master` is supported. There are no backported security releases.
28 changes: 28 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## What this changes

<!-- The behaviour difference, in a sentence or two. -->

## Why

<!-- What problem this solves. If it fixes a bug, describe how the bug manifests. -->

## Testing

<!-- How you verified this. For a bug fix, confirm the regression test fails without the fix. -->

- [ ] `cargo fmt --all -- --check`
- [ ] `cargo test --workspace --all-features --exclude zen-ffi --exclude zen-nodejs --exclude zen-python --locked`
- [ ] `cargo test --workspace --exclude zen-ffi --exclude zen-nodejs --exclude zen-python --locked`
- [ ] For a bug fix: the new test fails without the fix

## Relationship to upstream

<!-- Delete whichever does not apply. -->

- [ ] Fork-specific — builds on this fork's own additions
- [ ] Also affects upstream `gorules/zen`
- [ ] Merges cleanly with current upstream `master`

## Notes for the reviewer

<!-- Anything surprising: a deliberate trade-off, a snapshot change and why, a follow-up you left out. -->
6 changes: 3 additions & 3 deletions .github/workflows/go.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -97,15 +97,15 @@ jobs:
name: Release
runs-on: ubuntu-latest
environment: release
if: "github.ref_type == 'tag' || github.event_name == 'workflow_dispatch'"
if: "(github.ref_type == 'tag' || github.event_name == 'workflow_dispatch')"
needs:
- build
- copy-common
steps:
- name: Checkout zen-go
uses: actions/checkout@v3
with:
repository: gorules/zen-go
repository: phenixrizen/zen-go
persist-credentials: false
token: ${{ secrets.PAT }}
- name: Download all artifacts
Expand Down Expand Up @@ -146,7 +146,7 @@ jobs:
- name: Push changes
uses: ad-m/github-push-action@master
with:
repository: gorules/zen-go
repository: phenixrizen/zen-go
github_token: ${{ secrets.PAT }}
branch: ${{ env.BRANCH_NAME }}
- name: Create PR
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/uniffi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,7 @@ jobs:
echo "Detected version: $VERSION"

- name: Pack NuGet package
run: dotnet pack nuget/GoRules.ZenEngine.csproj -c Release -p:Version=$VERSION
run: dotnet pack nuget/PhenixRizen.ZenEngine.csproj -c Release -p:Version=$VERSION

- name: Upload NuGet package artifact
uses: actions/upload-artifact@v4
Expand Down
59 changes: 59 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Code of Conduct

## Our pledge

We as members, contributors, and leaders pledge to make participation in our community a
harassment-free experience for everyone, regardless of age, body size, visible or invisible
disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
education, socio-economic status, nationality, personal appearance, race, caste, color, religion,
or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
and healthy community.

## Our standards

Examples of behavior that contributes to a positive environment:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes
* Focusing on what is best for the overall community

Examples of unacceptable behavior:

* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address, without their
explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Enforcement responsibilities

Project maintainers are responsible for clarifying and enforcing these standards and will take
appropriate and fair corrective action in response to any behavior that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is
officially representing the community in public spaces.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project
maintainers through a
[private security advisory](https://github.com/phenixrizen/zen/security/advisories/new) or by
contacting **@phenixrizen** directly on GitHub.

All complaints will be reviewed and investigated promptly and fairly. Maintainers are obligated to
respect the privacy and security of the reporter of any incident.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available
at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

[homepage]: https://www.contributor-covenant.org
97 changes: 97 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Contributing

Contributions are welcome. This is a maintained fork of
[`gorules/zen`](https://github.com/gorules/zen); upstream states it cannot accept code
contributions, so this fork exists to take them.

Maintained by Phenix Rizen (Nathan Rockhold).

## Scope: what belongs here

| belongs in this fork | send upstream instead |
| --- | --- |
| Fixes upstream has not responded to | Anything you would rather see in the canonical project first |
| The fork's own additions (`databaseNode`, `zen-database-sqlite`, `$params`) | JDM standard/spec changes — GoRules owns the standard |
| Correctness fixes with a regression test | — |

A bug that reproduces on upstream is worth reporting
[there](https://github.com/gorules/zen/issues) too. Both projects benefit, and this fork tracks
upstream `master`.

## Development setup

Requires a stable Rust toolchain. Nothing else — the SQLite handler is pure Rust
([Turso](https://github.com/tursodatabase/turso)), so there is no C compiler or vendored
amalgamation in the build.

```bash
git clone https://github.com/phenixrizen/zen.git
cd zen
cargo build --workspace
```

## The test gate

Run all four commands before opening a PR. CI runs the same ones.

```bash
# 1. Formatting.
cargo fmt --all -- --check

# 2. Full workspace, all features.
cargo test --workspace --all-features \
--exclude zen-ffi --exclude zen-nodejs --exclude zen-python --locked

# 3. Again with default features. CI runs both; feature unification means
# they do not exercise the same code.
cargo test --workspace \
--exclude zen-ffi --exclude zen-nodejs --exclude zen-python --locked

# 4. WASM still builds.
cargo check -p zen-engine --target wasm32-wasip1-threads --all-features
```

### Things that will trip you up

- **`arbitrary_precision` changes numeric output.** With it off, numbers serialize through `f64`.
Some upstream fixtures (`customer-lifetime-value.json`) encode 28-digit decimal expectations and
can only pass with the feature on, which is why step 2 and step 3 differ. If you touch numeric
serialization, run both.
- **Snapshot tests.** `cargo insta` review if you change engine output. A PR should not carry
unexplained `.snap` changes.
- **Tests that need reference data skip by default.** `zen-database-sqlite`'s differential suites
read `ZEN_CATALOG_DIR` and `ZEN_CORPUS_MANIFEST`. Unset means "no bundle available" and they
skip. Never commit a `.db` fixture — build read-only fixtures at test time from a committed
`.sql`.

## Commit messages

[Conventional Commits](https://www.conventionalcommits.org/). Release automation parses them, so
the prefix determines the version bump.

```
fix(expression): honour TZ when resolving the local timezone
feat(engine): add database node and handler extension point
test(database-sqlite): require an explicit catalog bundle path
```

Explain *why* in the body, not just what. A reviewer can read the diff; they cannot read your
reasoning.

## Pull requests

- Branch off `master`.
- One logical change per PR.
- A bug fix needs a regression test, and you should confirm the test **fails without the fix**.
State that you did.
- Do not commit absolute paths, machine-specific defaults, or generated artifacts.

## Tracking upstream

```bash
git remote add upstream https://github.com/gorules/zen.git
git fetch upstream
git merge upstream/master
```

Keep fork-specific changes additive where practical, so upstream merges stay cheap.
Loading