@open-predicate/open-predicate 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,57 @@ minor release may break compatibility, in which case the break is spelled out be
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-09-14
+
+**A packaging release, again.** The schema is still byte-identical and the `$id` still names
+`v0.4.0`. 0.6.1 fixed the defects an audit of the package found; this one fixes the ones that
+audit had not looked for, and closes the coverage gaps that let the first set through.
+
+### Fixed
+
+- **35 links in the shipped documents pointed at files that are not shipped.** The package is a
+  subset of the repository, so a relative link into `examples/` reads fine on GitHub and is dead for anyone
+  reading the same file in `node_modules`. npmjs.com hides this for the README — it rewrites relative
+  links against the repository — but only for the README, and only on that page.
+
+  Fixed from both ends. `files` now ships the documents a consumer or a would-be contributor
+  plausibly wants offline: `COMPARISON.md`, `CONTRIBUTING.md`, `GOVERNANCE.md`, `CODE_OF_CONDUCT.md`,
+  `SECURITY.md` and `SUPPORT.md`. Links to things a schema package has no business shipping —
+  `examples/`, `assets/`, `.github/`, `tests/`, `experiments/`, the 39 KB decision record and the
+  maintainer-only `RELEASING.md` — are now absolute. The tarball grew from 61 KB to 77 KB, which is
+  the price of the docs being readable where they are installed.
+
+- **`npx open-predicate` printed npm's `could not determine executable to run`.** The unscoped name
+  is a deprecated placeholder with no code, so npm had no bin to run and said so in its own terms,
+  which tells someone following a stale instruction nothing. It now carries a single executable
+  whose only job is to name the scoped package and exit non-zero. The recipe in
+  [`RELEASING.md`](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md) is updated
+  to reproduce it, and records that `npm deprecate` marks a version rather than a package, so the
+  deprecation has to be re-applied after each publish.
+
+### Added
+
+- **The packed artifact is now tested under every package manager, on every platform that links a
+  bin differently.** The 0.6.0 no-op was a symlink bug, and package managers disagree about
+  symlinks: npm and yarn classic symlink, pnpm writes a shell shim, Yarn Berry's PnP has no
+  `node_modules` at all, and Windows gets `.cmd` wrappers that pass the real path — which is why the
+  bug never existed there. The release gate added in 0.6.1 only ever proved the npm-on-Linux case.
+
+  [`.github/scripts/smoke-packed-artifact.sh`](https://github.com/OpenPredicate/open-predicate/blob/main/.github/scripts/smoke-packed-artifact.sh)
+  installs the tarball and drives the bin, `require()`, the documented ESM import attribute and
+  `./generate` under a named package manager, and CI runs it across npm, pnpm, yarn, yarn-pnp and
+  bun on Linux plus npm on Windows and macOS. The release workflow calls the same script rather than
+  keeping a second copy of the logic.
+
+- **`tests/packaging.test.mjs` asserts the claims a tarball can break.** Every relative link in a
+  shipped document resolves to a shipped file; no shipped document links outside the package; the
+  bin is shipped, non-empty and still has its shebang; and the declared Node floor is the one the
+  code actually needs. It reads the file list from `npm pack --dry-run --json` rather than
+  extracting a tarball, so it needs no `tar` and runs on Windows unchanged.
+
+- **CI declares `permissions: contents: read`.** It had no `permissions` block at all, so it
+  inherited the repository default while `release.yml` had been careful to take none.
+
 ## [0.6.1] — 2026-09-14
 
 **A packaging release.** No change to the grammar, the schema or the semantics of evaluation:
@@ -41,7 +92,7 @@ changed is that the package now works the way 0.6.0 said it did.
 - **The release pipeline never exercised the artifact it publishes.** `npm test` and
   `npm run generate:example` both invoke the generator by path, which is the one way that never
   crosses the symlink npm installs a `bin` as — so the no-op above passed every check and shipped.
-  [`.github/workflows/release.yml`](./.github/workflows/release.yml) now packs the tarball, installs
+  [`.github/workflows/release.yml`](https://github.com/OpenPredicate/open-predicate/blob/main/.github/workflows/release.yml) now packs the tarball, installs
   it into a scratch project the way a consumer would, and drives every entry point the README
   documents: the bin through its symlink, `require()`, the ESM import attribute, and
   `./generate`. It also asserts the generator stays silent when merely imported. A release cannot
@@ -63,14 +114,22 @@ changed is that the package now works the way 0.6.0 said it did.
   and no code, so the name cannot end up on something unrelated to the project.
   `npm install open-predicate` prints a redirect to the scoped package. It is not versioned
   alongside releases and the release pipeline never touches it — see
-  [`RELEASING.md`](./RELEASING.md#the-reserved-unscoped-name).
+  [`RELEASING.md`](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md#the-reserved-unscoped-name).
 
 ### Added
 
+- **GitHub Packages has its first copy.** `@openpredicate/open-predicate@0.6.1` is the first version
+  to reach it; npmjs.com had been the only registry carrying anything. Installing from it still needs
+  an `.npmrc` and a token even though it is public, so npmjs.com remains the easier path.
+
+- **0.6.1 is the first release with provenance.** Published over OIDC from the workflow rather than
+  from a laptop, so the tarball carries a SLSA v1 attestation linking it to the run and commit that
+  built it. Verify with `npm view @open-predicate/open-predicate@0.6.1 dist.attestations`.
+
 - **The project has a written governance and contribution process.**
   [`GOVERNANCE.md`](./GOVERNANCE.md) states how a decision is made and what it costs — editorial,
   substantive-compatible, or normative, where normative requires a record under
-  [`decisions/`](./decisions), a migration note and a `$id` bump. It sets out how a disputed design
+  [`decisions/`](https://github.com/OpenPredicate/open-predicate/tree/main/decisions), a migration note and a `$id` bump. It sets out how a disputed design
   call is resolved (answered in writing, then a decision record quoting the objection in the
   objector's words, then 14-day lazy consensus, then the editor decides **and the dissent is recorded
   in the record**), what earns commit rights, and an explicit royalty-free patent posture — MIT
@@ -113,10 +172,10 @@ changed is that the package now works the way 0.6.0 said it did.
   Serving it is a second repository's job, so a release is not finished when the tag is pushed —
   [`OpenPredicate/openpredicate.tech`](https://github.com/OpenPredicate/openpredicate.tech) vendors
   the artefacts and has to be synced at the tag. That step is now written down in
-  [`RELEASING.md`](./RELEASING.md#serving-the-schema-from-its-id).
+  [`RELEASING.md`](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md#serving-the-schema-from-its-id).
 
 - **Publishing is back on, and npmjs.com authenticates by OIDC.**
-  [`.github/workflows/release.yml`](./.github/workflows/release.yml) publishes to both registries
+  [`.github/workflows/release.yml`](https://github.com/OpenPredicate/open-predicate/blob/main/.github/workflows/release.yml) publishes to both registries
   when a GitHub Release is published. The npmjs job uses npm's [trusted
   publishing](https://docs.npmjs.com/trusted-publishers): it requests `id-token: write` and npm
   exchanges that for a short-lived credential, so there is **no `NPM_TOKEN` secret** in this
@@ -135,14 +194,14 @@ changed is that the package now works the way 0.6.0 said it did.
   **npm cannot mint a package's first version over OIDC**, because a trusted publisher can only be
   attached to a package that already exists. Claiming `@open-predicate/open-predicate` was therefore
   a one-time manual publish, documented along with everything it cost to get right in
-  [`RELEASING.md`](./RELEASING.md#trusted-publishing-and-the-one-time-bootstrap) — including that
+  [`RELEASING.md`](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md#trusted-publishing-and-the-one-time-bootstrap) — including that
   *configuring* the trusted publisher needs npm >= 12, which fails with an unexplained `E400` on
   npm 11 because the older client omits the `permissions` field the registry now requires.
 
 - **`@open-predicate/open-predicate` is on npmjs.com**, public and installable, from `0.6.0` on. The
   package is the schema: `require()` it, or `import` it with `{ type: 'json' }`. The trusted
   publisher is configured, so every release from here is published by the workflow rather than by
-  hand. GitHub Packages gets its first copy with the next release.
+  hand. GitHub Packages got its first copy with 0.6.1.
 
 ## [0.6.0] — 2026-09-13
 
@@ -188,9 +247,9 @@ to re-point at.
 
 ### Added
 
-- **Brand assets, in [`assets/`](./assets/).** The `{ > }` mark — JSON braces around a comparison —
+- **Brand assets, in [`assets/`](https://github.com/OpenPredicate/open-predicate/tree/main/assets/).** The `{ > }` mark — JSON braces around a comparison —
   as SVG and as raster at three sizes, plus a wordmark for light and dark backgrounds.
-  [`assets/README.md`](./assets/README.md) states the palette and the usage rules. The README now
+  [`assets/README.md`](https://github.com/OpenPredicate/open-predicate/blob/main/assets/README.md) states the palette and the usage rules. The README now
   opens with the mark. MIT-licensed with the rest of the repository.
 
 ## [0.5.0] — 2026-09-13
@@ -352,7 +411,7 @@ document's top-level members. No filter valid under 0.4.0 becomes invalid.
 **Breaking.** The `$id` is now `…/v0.4.0/open-predicate-schema.json`. This release resolves the
 three operator overlaps that an external review and this repository's own
 `experiments/filter-to-sql` flagged independently; the design and the evidence are in
-[`decisions/0001-array-quantifiers-and-unknown-handling.md`](./decisions/0001-array-quantifiers-and-unknown-handling.md).
+[`decisions/0001-array-quantifiers-and-unknown-handling.md`](https://github.com/OpenPredicate/open-predicate/blob/main/decisions/0001-array-quantifiers-and-unknown-handling.md).
 
 The headline is that the language had **two** unrelated mechanisms for looking inside an array —
 `$elemMatch` and the `[*]` path segment — and one mechanism now does both jobs while naming its
@@ -456,7 +515,7 @@ grammar and the grammar did not move. Consumers pinning that `$id` have nothing
   name, and npm blocks a name from reuse permanently once it has been published and unpublished. `.github/workflows/release.yml` now only verifies a release —
   the test suite, and the tag-against-`package.json` check — and uploads nothing. The
   `NPM_TOKEN` secret and `.github/scripts/version-published.sh` are deleted with it.
-  [RELEASING.md](./RELEASING.md#turning-publishing-back-on) keeps what the jobs needed, so they
+  [RELEASING.md](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md#turning-publishing-back-on) keeps what the jobs needed, so they
   can be restored from git history rather than rewritten.
 
 ### Changed
@@ -465,7 +524,7 @@ grammar and the grammar did not move. Consumers pinning that `$id` have nothing
   `npm install --save-dev open-predicate`, which the README's own *Status* table already
   contradicted two screens further down. It now vendors the file by `curl`, which is the only
   way to obtain the schema and always was.
-- **[RELEASING.md](./RELEASING.md) documents the process that exists** — a tag and a GitHub
+- **[RELEASING.md](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md) documents the process that exists** — a tag and a GitHub
   Release, carrying notes and a source snapshot and nothing else.
 
 ## [0.3.0] — 2026-09-04
@@ -620,6 +679,7 @@ Initial research draft: `$and`, `$or`, `$not` over eight leaf condition types
 (`$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$gt`/`$gte`/`$lt`/`$lte`/`$between`, `$isnull`),
 laid out as an OpenAPI `components.schemas` fragment.
 
+[0.6.2]: https://github.com/OpenPredicate/open-predicate/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/OpenPredicate/open-predicate/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/OpenPredicate/open-predicate/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/OpenPredicate/open-predicate/compare/v0.4.0...v0.5.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,66 @@
+# Code of Conduct
+
+## The short version
+
+Attack arguments, not people.
+
+This project [asks for disagreement](./CONTRIBUTING.md) and means it. Saying *"this operator is
+redundant and the spec is wrong to include it"* is the contribution, not a breach of conduct. Being
+blunt, unimpressed, or persistent about a technical position is fine. Saying *"only an idiot would
+have designed it this way"* is a different act, and it is the one this document is about.
+
+## Our pledge
+
+We pledge to make participation in this project 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, colour, religion, or sexual identity and orientation.
+
+## Expected behaviour
+
+- Argue about the specification, the schema, the code and the evidence.
+- Assume the other person has a reason, and ask for it before assuming they do not.
+- Accept a decision you disagree with once it has been answered on the substance — and note that
+  [GOVERNANCE.md](./GOVERNANCE.md) requires your dissent to be recorded in the decision record
+  rather than discarded, so you do not have to keep re-litigating it to keep it on the record.
+- Give credit, including to people whose objection changed your mind.
+
+## Unacceptable behaviour
+
+- Personal attacks, insults, or derogatory comments — including ones dressed as technical criticism.
+- Harassment, public or private; sexualised language or imagery; unwelcome sexual attention.
+- Publishing others' private information without explicit permission.
+- Sustained disruption: reopening a settled decision with no new argument, brigading a thread, or
+  demanding a maintainer's time as though it were owed.
+- Any conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This applies in the repositories of the [OpenPredicate organisation](https://github.com/OpenPredicate),
+in issues, pull requests, discussions and commit messages, and anywhere someone is representing the
+project in public.
+
+## Reporting and enforcement
+
+Report to **contact@openpredicate.tech**. Reports are read by the maintainers listed in
+[GOVERNANCE.md](./GOVERNANCE.md) — at present that is one person, Christos Gkoros, so a report about
+the maintainer has nowhere independent to go inside the project. That is stated rather than hidden;
+where the complaint is about the maintainer and that is unacceptable to you, GitHub's own
+[abuse reporting](https://github.com/contact/report-abuse) is the escalation path.
+
+You will get an acknowledgement within seven days. Reports are kept confidential to the extent
+possible, and the reporter's identity is never disclosed to the person reported without consent.
+
+Enforcement is proportionate and escalates: a private correction explaining what was wrong; a
+warning with conditions; a temporary ban from interaction; a permanent ban. Anything beyond a private
+correction is recorded, though not necessarily published. Comments, commits, issues and other
+contributions that breach this document may be edited or removed, with a reason given.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, which is
+available at
+[contributor-covenant.org/version/2/1/code_of_conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+and licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The opening section, the
+single-maintainer disclosure in *Reporting*, and the dissent clause under *Expected behaviour* are
+specific to this project.

package/COMPARISON.md

@@ -0,0 +1,195 @@
+# OpenPredicate and GraphQL
+
+The question arrives in two forms. *Why not just use GraphQL?* — asked by someone choosing
+between them. And *could this become a JSON-Schema-native alternative to GraphQL?* — asked by
+someone who has noticed that the two overlap somewhere. This document answers both, starting from
+the observation that makes both answerable: they overlap much less than the question assumes.
+
+---
+
+## 1. GraphQL is four things; this is a fifth
+
+GraphQL bundles:
+
+1. **A type system with mandatory introspection.** SDL, plus a query every server must answer that
+   returns its own schema.
+2. **Client-specified projection.** The response contains the fields the client asked for and
+   nothing else. This is the feature GraphQL is adopted for.
+3. **Traversal.** Nested selections are joins, executed by resolvers.
+4. **A transport and execution contract.** One endpoint, variables, operations, an `errors` array
+   alongside partial `data`, subscriptions.
+
+**Filtering is not on that list.** The GraphQL specification says nothing about `where`. Every
+server invents its own input objects — Hasura's `_eq`/`_in`, Prisma's `equals`/`contains`,
+Postgraphile, Dgraph — with no shared vocabulary, no shared null semantics, and no portability
+between them. A client that knows GraphQL does not thereby know how to filter.
+
+That is the gap this specification occupies. [JSON:API](https://jsonapi.org/format/#fetching-filtering)
+has the same hole and says so explicitly: it reserves the `filter` query parameter and declines to
+define its contents. MCP tool definitions have it too — an agent is handed an `inputSchema` and
+left to infer a query syntax from prose.
+
+So the first answer is that **this is not GraphQL's competitor; it is the piece GraphQL left
+out.** A GraphQL server could adopt the grammar as the body of its `where` argument tomorrow and
+lose nothing.
+
+---
+
+## 2. Side by side
+
+The same request, filtering pets and taking three fields.
+
+**GraphQL** — projection is the point; the filter vocabulary is the server's invention:
+
+```graphql
+query {
+  pets(where: { _and: [
+    { status: { _eq: "available" } },
+    { born:   { _gte: "2020-01-01" } }
+  ]}, limit: 50) {
+    id
+    name
+    shelter { city }
+  }
+}
+```
+
+**OpenPredicate** — the filter is standard and schema-validated; projection, ordering and
+paging belong to the enclosing body, where each API defines them:
+
+```http
+QUERY /pets HTTP/1.1
+Content-Type: application/json
+```
+```json
+{
+  "filter": {
+    "status": "available",
+    "born": { "$gte": "2020-01-01" }
+  },
+  "fields": ["id", "name", "shelter.city"],
+  "limit": 50
+}
+```
+
+The differences that matter are not the syntax. In the GraphQL version the response type is known
+statically from the selection set, and the filter is unportable. In the second the filter is
+portable and machine-checkable, and `fields` is whatever that API decided it should be.
+
+---
+
+## 3. What GraphQL does that this does not
+
+Stated plainly, because these are the reasons to choose GraphQL and they are good ones.
+
+| | |
+| --- | --- |
+| **Response shape follows the request** | The single hardest thing to reproduce. See §5. |
+| **One round trip across many resources** | A GraphQL document fetches pets, their shelters and their vaccinations together. Per-resource search endpoints do not. |
+| **One mandatory introspection format** | Every GraphQL server answers the same introspection query, which is why GraphiQL, codegen and federation work everywhere. [SPEC.md §2.2](./SPEC.md#22-capability-discovery)'s capability document is RECOMMENDED, not required, and lives at an unspecified URL. |
+| **Federation** | Composing one graph from many services is a solved, productised problem there and an unsolved one here. |
+| **Subscriptions** | Out of scope entirely. |
+| **Mutations** | Out of scope entirely; this is a predicate language. |
+
+---
+
+## 4. What this does that GraphQL does not
+
+| | |
+| --- | --- |
+| **HTTP survives** | Cache-Control and ETags apply, `QUERY` and `GET` stay safe and cacheable, status codes mean what they say, and a rejected filter is a `400` naming which of five conditions failed, with an RFC 6901 pointer at the offending clause, in whatever error format the API already uses ([SPEC.md §8](./SPEC.md#8-errors)). GraphQL's single POST endpoint forfeits intermediary caching; `application/graphql-response+json` recovers status codes but not cache keys. |
+| **Null semantics are specified** | [SPEC.md §4.1](./SPEC.md#41-three-valued-logic) and [§4.2](./SPEC.md#42-missing-versus-null) pin down three-valued logic and the missing-versus-null distinction. GraphQL's null propagation is its most notorious sharp edge, and its filter semantics are per-vendor folklore. |
+| **Complexity limits are normative** | [SPEC.md §7](./SPEC.md#7-safety-limits) bounds depth, clause count, set length and regex execution, and requires rejection rather than truncation. GraphQL query cost is left to each shop to solve. |
+| **Honest partial implementations** | Profiles ([SPEC.md §2.1](./SPEC.md#21-profiles)) let a server advertise the subset it implements and reject the rest, instead of mistranslating it. |
+| **Incremental adoption** | One endpoint can adopt the filter grammar without the rest of the API changing. GraphQL is a parallel stack. |
+| **It is already in the toolchains** | JSON Schema is what OpenAPI 3.1 speaks and what an MCP `inputSchema` is. No new parser, client or IDE plugin. |
+
+That last row is worth more in 2026 than it was in 2016. An LLM agent gains little from
+client-specified projection — it did not want the other fields anyway — and a great deal from a
+grammar it can be handed, validated against, and corrected by in one round trip. See
+[README §*Exposing search to an agent*](./README.md#exposing-search-to-an-agent).
+
+---
+
+## 5. What a JSON-Schema-native alternative would actually require
+
+Taking the ambition seriously, layer by layer. Each of these is independently useful, which is the
+point: the reason to build this way rather than adopt GraphQL is that adopters can take one layer
+and leave the rest.
+
+| Layer | Status | The hard part |
+| --- | --- | --- |
+| **filter** | this specification | done |
+| **capabilities** | [SPEC.md §2.2](./SPEC.md#22-capability-discovery), RECOMMENDED | making it mandatory and locating it, so tooling can rely on it |
+| **select** | not started | deriving the *response* schema from a runtime selection set |
+| **expand / link** | not started | JSON Schema has no relationship vocabulary; [JSON Hyper-Schema](https://json-schema.org/draft/2019-09/json-hyper-schema) tried and stalled after draft-07 |
+| **order / page** | not started | little novelty; cursor opacity is the only real decision |
+| **envelope + errors** | [SPEC.md §8](./SPEC.md#8-errors) | done for filters; would need extending per layer |
+
+**The load-bearing difficulty is projection typing.** GraphQL's trick is that the client's query
+document is itself the input to type derivation — that is what Relay and graphql-codegen consume.
+JSON Schema cannot express "the response shape is a function of this request's selection set".
+There are two workable answers and they are not exclusive:
+
+- *Normatively:* the response schema is the resource schema with every non-selected property
+  optional. A selection then guarantees presence, not typing — the same bargain OData and
+  JSON:API's sparse fieldsets strike.
+- *In tooling:* derive the exact response schema client-side from `resource schema ∩ selection`.
+  This is codegen, and it is what GraphQL users are actually running anyway.
+
+**A relationship vocabulary is the second obstacle**, and the precedent is discouraging. JSON
+Hyper-Schema was the attempt and it did not reach 2019-09. Anything here would have to be new
+work, and cross-resource traversal is the point at which the N+1 problem, authorisation per hop
+and query cost all arrive at once — everything GraphQL servers spend their complexity budget on.
+
+---
+
+## 6. Where the generator fits
+
+The gap that most weakens the comparison today is that the published grammar shares one
+`Constraint` across every field, so it can validate that `{"status": "Available"}` is well-formed
+but not that `"Available"` is outside `status`'s domain. GraphQL does not have this problem: it
+*generates* `StringFilter`, `StatusEnumFilter` and so on per field, so the equivalent mistake is a
+compile-time error.
+
+[`tools/generate-filter-schema.mjs`](./tools/generate-filter-schema.mjs) closes it the same way,
+from the resource's own JSON Schema — see
+[README §*Generating a per-resource filter schema*](./README.md#generating-a-per-resource-filter-schema).
+`data schema → filter schema` is the same pipeline as GraphQL's `SDL → input types`, with JSON
+Schema as the source of truth instead of SDL. Extending that generator to emit a `select` schema
+and a response schema from the same input is what would turn the phrase "JSON-Schema-native
+alternative to GraphQL" into an architecture rather than a slogan.
+
+---
+
+## 7. Prior art
+
+Anyone building this should know what has already been tried.
+
+| | |
+| --- | --- |
+| [**OData**](https://www.odata.org/) | The dream, already attempted and standardised (OASIS, ISO/IEC 20802). `$filter`, `$select`, `$expand`, `$orderby`, `$top`/`$skip`, `$metadata`. Worth studying for why it did not displace GraphQL: a string-encoded `$filter` no schema can validate — precisely the defect this grammar fixes — an enormous surface, and CSDL metadata few enjoyed. |
+| [**JSON:API**](https://jsonapi.org/) | Sparse fieldsets and `include` are a working design for the `select` and `expand` layers. Its `filter` is deliberately unspecified. |
+| [**OGC CQL2**](https://docs.ogc.org/is/21-065r2/21-065r2.html) | Direct prior art for the predicate itself, including a JSON encoding. |
+| **MongoDB query language** | The obvious syntactic ancestor of `$eq`/`$in`. The divergences here are deliberate: no implicit coercion, specified three-valued logic, `$in` as whole-value comparison with element access spelled `$some`, and `$elemMatch` renamed to `$some` beside a `$every` MongoDB has no equivalent for. |
+| [**SCIM filters**](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2), [**AIP-160**](https://google.aip.dev/160) | String-encoded filter grammars, with the same unvalidatable-parameter problem as OData. |
+| [**JSONPath (RFC 9535)**](https://www.rfc-editor.org/rfc/rfc9535) | A standardised path grammar. [SPEC.md §3.2](./SPEC.md#32-path-grammar) uses a deliberately smaller one — smaller again since v0.4.0 dropped the `[*]` wildcard segment in favour of explicit quantifiers, which narrows the divergence to the non-wildcard subset. |
+| **JSON Hyper-Schema** | The cautionary tale for the `expand` layer. |
+| **Hasura / Prisma / Postgraphile `where`** | The de facto GraphQL filter dialects. Between them they are the closest thing to an existing standard, and none of them is one. |
+
+---
+
+## 8. Choosing between them
+
+- **Choose GraphQL** if clients need to shape their own responses, if one round trip across many
+  resources is a requirement, or if you need federation or subscriptions.
+- **Choose this** if you have HTTP endpoints that already work and want their filters to be
+  consistent, validated in CI, typed in generated clients, and usable by an agent — without
+  adopting a parallel stack.
+- **Choose both** if you run GraphQL: nothing stops the grammar being the body of your `where`
+  argument, and it would make your filter vocabulary portable to the REST endpoints beside it.
+
+The honest framing of the ambition: what is published here is one layer, and the most valuable one
+to standardise because it is the one everybody re-invents. Whether the layers above it get built
+is a separate question from whether this layer is worth adopting, and the answer to the second
+does not depend on the first.

package/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing
+
+**Disagreement is the most useful contribution at this stage.**
+
+That is not politeness. OpenPredicate is pre-1.0 with no known adopters, which means every design
+defect is still free to fix — and after adoption each one is permanent. The most valuable thing you
+can do is find the construct that will be regretted and say so while saying so is cheap.
+
+There is precedent. Three operator overlaps — `$in` against `$hasAny`, `$elemMatch` against wildcard
+paths, and three-valued `$not`/`$ne` silently excluding nulls — were removed in v0.4.0 because an
+external survey and this repository's own
+[`experiments/filter-to-sql`](https://github.com/OpenPredicate/open-predicate/tree/main/experiments/filter-to-sql) converged on the same three
+independently. Both reviews were unsolicited. See
+[`decisions/0001`](https://github.com/OpenPredicate/open-predicate/blob/main/decisions/0001-array-quantifiers-and-unknown-handling.md) for what happened to
+them.
+
+So: if something here looks wrong, file it. You do not need to propose a replacement, and you do not
+need to be sure.
+
+## Three entry points
+
+### 1. File a design objection
+
+Use the *design objection* issue template. A good objection names three things:
+
+- **The construct.** Quote the operator, the rule, or the section of [`SPEC.md`](./SPEC.md).
+- **The failure.** What goes wrong — a filter that cannot be expressed, two ways to write the same
+  thing, a semantic that surprises, a rule an implementation cannot enforce. A concrete filter and
+  the result you expected beats a description.
+- **What it should be instead**, if you have a view. Optional. "This is wrong and I do not know the
+  fix" is a legitimate and useful issue.
+
+The bar for *adding* an operator is deliberately high, and it is stated in `decisions/0001`:
+**a construct definable in terms of another does not earn a name.** That is why `$none` is not in
+the grammar — it is `$not` over `$some`. An objection that argues a construct is *hard to write
+correctly* in its definable form is the argument that can move this; an objection that it is merely
+absent will not.
+
+Out of scope by design, per [SPEC.md §1](./SPEC.md): projection, ordering, pagination, grouping and
+joins. Confining this schema to the predicate is what makes it reusable across endpoints, and
+[`COMPARISON.md`](./COMPARISON.md) §5 sets out what the layers above it would require if they are
+ever built. Proposals to add them now will be declined until the filter layer has external
+implementers.
+
+### 2. Build an implementation — or make implementing it cheaper
+
+The specification is written normatively so that independent implementations can agree, rather than
+deferring to a reference implementation. So a second implementation is worth more here than a
+feature, and the evidence says it is small work:
+[`experiments/filter-to-sql`](https://github.com/OpenPredicate/open-predicate/tree/main/experiments/filter-to-sql) covers 33 of 34 operators in one
+dependency-free file, and the part everyone worries about — UNKNOWN — is 23 lines of it.
+
+**Be aware of what the test assets currently are and are not.** This matters if you are planning to
+port them:
+
+- [`tests/fixtures/`](https://github.com/OpenPredicate/open-predicate/tree/main/tests/fixtures) holds 32 valid and 28 invalid filters as declarative JSON.
+  They are portable in shape, and there is a test asserting every operator in the grammar is
+  exercised by at least one of them — the operator table and the fixture set are the same list.
+- They check **schema well-formedness only.** There are no records and no expected results, so they
+  cannot tell you whether an *evaluator* is correct, which is the part you would actually be writing.
+- The `expectKeyword` member on invalid fixtures names a JSON Schema keyword and is therefore
+  ajv-flavoured, not portable.
+- `tests/` is excluded from the published npm package, so today the fixtures reach you only by
+  cloning.
+
+**The highest-value single contribution available is closing that gap**, and most of the raw material
+exists: `experiments/filter-to-sql/cases.mjs` is already 73 cases over 10 records in the shape
+`{group, id, title, filter, expect}` — an evaluation corpus in everything but name. It is currently
+labelled *"an exercise, not a deliverable"*. Promoting it into a versioned, language-agnostic
+conformance suite with portable rejection cases (keyed to the five error conditions in
+[SPEC.md §8](./SPEC.md) rather than to ajv keywords) and shipping it in the package is open work, and
+it is wanted. Say so in an issue before starting so the shape can be agreed.
+
+Where two implementations disagree about a case, that disagreement is a specification defect. Report
+it as a *spec ambiguity* — those are the most valuable issues this project can receive.
+
+### 3. Claim conformance for a library that already exists
+
+If you maintain a filter evaluator — anything in the `$eq`/`$in`/`$and` family — you may already be
+most of the way to conforming, and the specification is built to let you say so honestly rather than
+all-or-nothing. [SPEC.md §2.1](./SPEC.md) requires only that you:
+
+- implement the `core` profile in full;
+- advertise **only** the profiles you implement completely, stating anything partial per-field
+  through the `operators` member of §2.2 instead;
+- reject an operator you do not support with an `unsupported-operator` error — never silently drop
+  the clause, because dropping a predicate *widens* the result set, which is the most dangerous
+  possible failure mode for an authorization-adjacent filter.
+
+File an *implementation report* with what you support and what you had to leave out. The gaps are
+the useful half: a profile boundary that nobody can implement cleanly is a boundary drawn in the
+wrong place, and that is a specification bug.
+
+## Working in the repository
+
+```bash
+npm ci
+npm test          # 132 tests: schema meta-validation, fixtures, generator, narrowing property
+```
+
+CI additionally runs the suite on Node 20, 22 and 24, and lints both OpenAPI example documents with
+`@redocly/cli`. Everything is ESM JavaScript on Node with no runtime dependencies; the only
+dev-dependencies are `ajv` and `ajv-formats`. Please keep it that way — a specification repository
+that is expensive to check out is a specification with fewer implementations.
+
+A few invariants the tests enforce, so you find out from CI rather than from review: the schema
+meta-validates under `ajv` in strict mode; `x-profiles` covers exactly the operators the grammar
+defines; every operator has at least one valid fixture; the generator's committed output in
+`examples/` must not drift; and a narrowed `$defs/FieldPath` must restrict fields at every nesting
+depth.
+
+Commit messages are sentence-shaped and say what the change does to the project, not what was
+edited — *"Stop mandating an error format; mandate the error conditions"*, not *"update SPEC.md"*.
+Normative changes need a [decision record](./GOVERNANCE.md) and a `CHANGELOG.md` entry with a
+migration note; [`GOVERNANCE.md`](./GOVERNANCE.md) has the table of what each class of change costs.
+
+## Adding your own operators without waiting for us
+
+You do not need permission, and you should not wait. [SPEC.md §6](./SPEC.md) reserves the bare `$`
+namespace for the specification and gives you the rest: prefix your operator distinctly (`$x_`, or a
+vendor tag such as `$acme_geoWithin`) and document it. An endpoint that adds an operator no longer
+validates against the published schema, so it SHOULD publish an extended schema that `allOf`-composes
+or bundles this one, and MUST NOT advertise the unmodified `$id`.
+
+If a vendor-prefixed operator turns out to be one everybody needs, that is exactly the evidence a
+decision record wants, and it is a far stronger case than a proposal with no implementation behind
+it.
+
+## Conduct
+
+By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). It is short, and it makes
+one thing explicit that matters more here than in most projects: blunt technical disagreement is
+welcome and is not incivility. The distinction it draws is between attacking an argument and
+attacking a person.

package/GOVERNANCE.md

@@ -0,0 +1,127 @@
+# Governance
+
+This document says how decisions get made, who makes them, what earns someone a say, and
+what happens when people disagree. It exists because the [stated purpose](./README.md#about-openpredicate)
+of the OpenPredicate organisation is to take this grammar *from a single-author design to an
+open standard*, and a standard whose decision process is undocumented is still a single-author
+design no matter how the specification is written.
+
+## Current state, stated plainly
+
+**There is one maintainer:** Christos Gkoros ([@christosgkoros](https://github.com/christosgkoros)),
+who is also the specification editor. Every commit in the history is his. No external contributor
+has yet filed an issue or a pull request.
+
+That is a defect, not a design. It is the single largest obstacle to the word *standard* applying
+here, and it ranks above every feature on the roadmap. The rest of this document is written so
+that the process does not have to be invented at the moment a second person shows up.
+
+## Three classes of change
+
+What a change is determines what it costs to make. The dividing line is whether it can alter
+what a conforming implementation must do.
+
+| Class | Examples | Requires |
+| --- | --- | --- |
+| **Editorial** | Typos, clarifications that cannot change behaviour, examples, tooling, tests, site copy | A pull request. One maintainer approval. |
+| **Substantive, compatible** | A new optional profile member, a new capability-document field, generator features, new fixtures | An issue first, then a pull request that references it. A `CHANGELOG.md` entry. |
+| **Normative** | Adding, removing or renaming an operator; changing semantics, three-valued logic, coercion, error conditions or the safety limits; anything that changes what `MUST` happen | A **decision record** under [`decisions/`](https://github.com/OpenPredicate/open-predicate/tree/main/decisions), merged before or with the implementation. A `CHANGELOG.md` entry with a migration note. A `$id` version bump per [SPEC.md §9](./SPEC.md). |
+
+If it is unclear which class a change falls into, it is normative. The cost of over-documenting a
+change is a file nobody needed; the cost of under-documenting one is an implementer who cannot tell
+whether their implementation is still conforming.
+
+## Decision records are the mechanism
+
+Significant design decisions are argued in writing under [`decisions/`](https://github.com/OpenPredicate/open-predicate/tree/main/decisions) rather than
+settled by commit message. There is currently **exactly one record** —
+[`0001-array-quantifiers-and-unknown-handling.md`](https://github.com/OpenPredicate/open-predicate/blob/main/decisions/0001-array-quantifiers-and-unknown-handling.md).
+More are expected, and at least two are already owed: the resolution of
+[#1](https://github.com/OpenPredicate/open-predicate/issues/1) (scalar shorthand forcing `anyOf` on
+`Constraint`) and [#2](https://github.com/OpenPredicate/open-predicate/issues/2) (the capability
+document being RECOMMENDED at an unspecified location).
+
+A record is numbered, committed, and thereafter immutable in substance — it is superseded by a later
+record rather than edited, so the reasoning available at the time stays legible. `0001` is the
+worked example of the expected shape: **Context** (including what the record does *not* do),
+one section per **Decision**, **Migration** for anything breaking, **Costs and risks**,
+**Open question** for what it deliberately leaves unsettled, **Follow-ups, explicitly out of
+scope**, and **Results**.
+
+Two conventions in `0001` are load-bearing and carry forward:
+
+- **Record what you decided against, and why.** `0001` spends a section on why `$every` is included
+  and `$none` is not, and marks it as the one place its own two criteria pull against each other.
+  That is more useful to a future implementer than the decision itself.
+- **Name the evidence.** `0001` resolved three operator overlaps because an external survey and this
+  repository's own `experiments/filter-to-sql` converged on the same three independently. A record
+  that cites only taste is weaker than one that cites a measurement, and the project has a standing
+  bias toward building the measurement.
+
+## How a disputed design call is resolved
+
+The project's position is that [disagreement is the most useful contribution at this
+stage](./CONTRIBUTING.md), so the process is built to absorb it rather than to close it quickly.
+
+1. **The objection is filed** as an issue, using the *design objection* template.
+2. **It gets answered in writing.** A maintainer must respond on the substance — not merely close
+   it. "Working as intended" is not an answer unless it says why the intent is right.
+3. **If it survives that, it becomes a decision record**, and the objection is quoted in the
+   Context section in the objector's words rather than paraphrased.
+4. **Lazy consensus decides it.** A proposed record that has sat for **14 days** with no unresolved
+   objection from a maintainer is accepted. Any maintainer may extend that window once by asking.
+5. **If maintainers still disagree, the specification editor decides — and the dissent is recorded
+   in the record itself**, attributed, with its reasoning intact. A standard that hides its
+   disagreements makes its own history unusable.
+
+Nothing in this process applies to correctness. A demonstrated bug — a filter the schema accepts
+and the spec forbids, or vice versa — is fixed, not debated.
+
+## What earns commit rights
+
+Commit rights follow demonstrated judgement about *this* grammar, not volume. Any one of these is
+sufficient to be proposed as a maintainer:
+
+- **Two accepted substantive or normative contributions**, at least one of which changed the
+  specification text.
+- **An authored decision record that was accepted**, including one that argued successfully against
+  the editor.
+- **An independent implementation that is shipped and maintained**, and that passes the fixtures in
+  [`tests/fixtures/`](https://github.com/OpenPredicate/open-predicate/tree/main/tests/fixtures). Implementers are the constituency this specification exists
+  to serve, and their view of an ambiguity outranks the editor's intent about it.
+
+A maintainer is added by consensus of the existing maintainers, announced in a decision record, and
+listed below. Maintainers who have been inactive for twelve months move to emeritus, keeping
+attribution and losing the commit bit; this is bookkeeping, not a judgement, and it reverses on
+request.
+
+**Maintainers:** Christos Gkoros ([@christosgkoros](https://github.com/christosgkoros)),
+specification editor.
+
+## Intellectual property and patents
+
+The specification, the schema and this repository are [MIT](./LICENSE)-licensed, so the grammar can
+be implemented, vendored, extended and re-specified by anyone, commercially or otherwise, without
+permission and without royalty. MIT settles copyright. It says nothing about patents, and for a
+specification that silence is the thing an adopter's lawyer notices first — so the project's
+position is stated explicitly:
+
+**OpenPredicate is intended to be implementable royalty-free by anyone.** The maintainers are aware
+of no patent claims covering the grammar, and will not knowingly accept a contribution encumbered by
+one. By contributing, you confirm that you are entitled to submit the work, and you grant to anyone
+implementing this specification a perpetual, worldwide, non-exclusive, royalty-free licence under
+any patent claims you own or control that are necessarily infringed by implementing your
+contribution. If you know of a claim that would encumber an implementation — yours or anyone's —
+disclose it in the pull request. A contribution that cannot be implemented freely will be declined
+however good the design is.
+
+Should the specification enter a formal standards venue, the venue's IPR rules govern instead — for
+the IETF, that is [BCP 78](https://www.rfc-editor.org/info/bcp78) and
+[BCP 79](https://www.rfc-editor.org/info/bcp79) — and this section will be superseded rather than
+reinterpreted.
+
+## Changing this document
+
+This document is itself normative about process, so changing it is a normative change: it takes a
+decision record. The first genuinely useful amendment will be the one that removes "there is one
+maintainer" from the top.

package/README.md

@@ -24,12 +24,12 @@ One schema, two integration points, because JSON Schema is what both already spe
 - **Install** — `npm i @open-predicate/open-predicate` (Node >= 20.10) ([npmjs.com](https://www.npmjs.com/package/@open-predicate/open-predicate)). The package *is* the schema: `require()` it, or `import schema from '@open-predicate/open-predicate' with { type: 'json' }` — ESM needs that import attribute, and a bare `import` throws without it.
 - **Schema** — [`open-predicate-schema.json`](./open-predicate-schema.json) (JSON Schema draft 2020-12)
 - **Semantics** — [`SPEC.md`](./SPEC.md) — nulls, paths, coercion, errors, limits
-- **MCP server** — [`examples/mcp-server/`](./examples/mcp-server) — a search tool with the language as its `inputSchema`, runnable
-- **OpenAPI documents** — [`examples/`](./examples) — working 3.1 (`POST /…/search`) and 3.2 (`QUERY`) integrations
+- **MCP server** — [`examples/mcp-server/`](https://github.com/OpenPredicate/open-predicate/tree/main/examples/mcp-server) — a search tool with the language as its `inputSchema`, runnable
+- **OpenAPI documents** — [`examples/`](https://github.com/OpenPredicate/open-predicate/tree/main/examples) — working 3.1 (`POST /…/search`) and 3.2 (`QUERY`) integrations
 - **Generator** — [`tools/generate-filter-schema.mjs`](./tools/generate-filter-schema.mjs) — turns a resource's JSON Schema, plus the slice of the language you can serve, into a per-field filter schema
 - **Compared with GraphQL** — [`COMPARISON.md`](./COMPARISON.md) — what this overlaps with, what it does not, and what a JSON-Schema-native alternative would still need
 - **Stewardship** — the [OpenPredicate](https://openpredicate.tech) organisation — see [About OpenPredicate](#about-openpredicate)
-- **Version** — `0.6.1`. The schema's `$id` still names `v0.4.0`: the `$id` tracks the grammar, and neither 0.5.0 nor 0.6.0 touched it. See [`CHANGELOG.md`](./CHANGELOG.md) for this release, and [`decisions/0001`](./decisions/0001-array-quantifiers-and-unknown-handling.md) for the v0.4.0 migration.
+- **Version** — `0.6.2`. The schema's `$id` still names `v0.4.0`: the `$id` tracks the grammar, and neither 0.5.0 nor 0.6.0 touched it. See [`CHANGELOG.md`](./CHANGELOG.md) for this release, and [`decisions/0001`](https://github.com/OpenPredicate/open-predicate/blob/main/decisions/0001-array-quantifiers-and-unknown-handling.md) for the v0.4.0 migration.
 
 > **Pre-1.0, and installable.** The name is settled — *OpenPredicate*, stewarded by the [OpenPredicate](https://openpredicate.tech) organisation, with the repository, both package names, the schema `$id` and the problem-type URIs all derived from it — the package is on npm as [`@open-predicate/open-predicate`](https://www.npmjs.com/package/@open-predicate/open-predicate), and the schema is **served at its `$id`** — so `$ref` it by URL, or from a packaged copy, whichever suits. One thing is still provisional: the grammar may still break before 1.0, with each break recorded in [`CHANGELOG.md`](./CHANGELOG.md). See [Status](#status) for what is reachable today.
 
@@ -54,7 +54,7 @@ is `department = 'sales' AND age >= 18`. That holds for operators on one field t
 
 ## Operator reference
 
-Every operator below has a matching fixture in [`tests/fixtures/valid/`](./tests/fixtures/valid) — the table and the test suite are the same list. Full semantics in [SPEC.md §5](./SPEC.md#5-operator-semantics).
+Every operator below has a matching fixture in [`tests/fixtures/valid/`](https://github.com/OpenPredicate/open-predicate/tree/main/tests/fixtures/valid) — the table and the test suite are the same list. Full semantics in [SPEC.md §5](./SPEC.md#5-operator-semantics).
 
 ### Logical — profile `core`
 
@@ -165,7 +165,7 @@ A path addresses one position. To say something about an array's elements, quant
 
 ## Using it from OpenAPI
 
-One of the two integration paths this repo exists for; [Exposing search to an agent](#exposing-search-to-an-agent) covers the other. Complete, CI-linted documents live in [`examples/`](./examples).
+One of the two integration paths this repo exists for; [Exposing search to an agent](#exposing-search-to-an-agent) covers the other. Complete, CI-linted documents live in [`examples/`](https://github.com/OpenPredicate/open-predicate/tree/main/examples).
 
 ### OpenAPI 3.1 — `POST /…/search`
 
@@ -197,7 +197,7 @@ components:
         filter: { $ref: '#/components/schemas/Filter' }
 ```
 
-→ [`examples/openapi-3.1-post-search.yaml`](./examples/openapi-3.1-post-search.yaml)
+→ [`examples/openapi-3.1-post-search.yaml`](https://github.com/OpenPredicate/open-predicate/blob/main/examples/openapi-3.1-post-search.yaml)
 
 ### OpenAPI 3.2 — the `QUERY` method
 
@@ -222,7 +222,7 @@ paths:
                 schema: { type: string, format: uri-reference }
 ```
 
-→ [`examples/openapi-3.2-query-method.yaml`](./examples/openapi-3.2-query-method.yaml)
+→ [`examples/openapi-3.2-query-method.yaml`](https://github.com/OpenPredicate/open-predicate/blob/main/examples/openapi-3.2-query-method.yaml)
 
 `QUERY` ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)) is **safe and idempotent** and carries a request body — it says "this is a read" in a way `POST` cannot, so intermediaries may cache it and clients may retry it. Return `Content-Location` when the same representation is also reachable by `GET`.
 
@@ -306,7 +306,7 @@ node tools/generate-filter-schema.mjs examples/pet.schema.json \
   --out pet.filter.json
 ```
 
-Given [`examples/pet.schema.json`](./examples/pet.schema.json), the generated [`pet.filter.json`](./examples/pet.filter.json) turns each of these from an empty result set into a `400`:
+Given [`examples/pet.schema.json`](https://github.com/OpenPredicate/open-predicate/blob/main/examples/pet.schema.json), the generated [`pet.filter.json`](https://github.com/OpenPredicate/open-predicate/blob/main/examples/pet.filter.json) turns each of these from an empty result set into a `400`:
 
 | Filter | Rejected because |
 | --- | --- |
@@ -319,7 +319,7 @@ Given [`examples/pet.schema.json`](./examples/pet.schema.json), the generated [`
 
 It also writes the [SPEC.md §2.2](./SPEC.md#22-capability-discovery) capability document from the same source, so the schema and the published domains cannot drift apart.
 
-That file is also what [`examples/mcp-server`](./examples/mcp-server) hands a model: a resource schema in, a tool definition out, with nothing written by hand in between.
+That file is also what [`examples/mcp-server`](https://github.com/OpenPredicate/open-predicate/tree/main/examples/mcp-server) hands a model: a resource schema in, a tool definition out, with nothing written by hand in between.
 
 What it decides, and why:
 
@@ -377,7 +377,7 @@ The tool ships inside the package as a `bin` named `open-predicate-generate`, so
 
 ## Exposing search to an agent
 
-The other integration path, and a working server for it lives in [`examples/mcp-server/`](./examples/mcp-server) — one tool, real records, `node examples/mcp-server/demo.mjs` to watch it answer and reject.
+The other integration path, and a working server for it lives in [`examples/mcp-server/`](https://github.com/OpenPredicate/open-predicate/tree/main/examples/mcp-server) — one tool, real records, `node examples/mcp-server/demo.mjs` to watch it answer and reject.
 
 The integration is one property of one argument:
 
@@ -463,7 +463,7 @@ experiments/filter-to-sql/     an exercise: compile a filter to SQL, then judge
 | --- | --- |
 | `$id` / `$ref` — `https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json` | **Served**, as `application/schema+json`, with `Access-Control-Allow-Origin: *` and immutable caching, byte-identical to the copy in this repository. `$ref` it directly, as [Using it from OpenAPI](#using-it-from-openapi) and the capability document examples do. |
 | [`@open-predicate/open-predicate`](https://www.npmjs.com/package/@open-predicate/open-predicate) on npmjs.com | **Published**, from `v0.6.0` on. Public, no credential needed to install. |
-| `@openpredicate/open-predicate` on GitHub Packages | Not published yet — the first copy goes up with the next GitHub Release. Installing from it needs an `.npmrc` and a token even though it is public, so npmjs.com is the easier path. |
+| `@openpredicate/open-predicate` on GitHub Packages | **Published**, from `0.6.1` on — the first copy went up with that release. Installing from it needs an `.npmrc` and a token even though it is public, so npmjs.com is the easier path. |
 | The version line at the top, and the version inside the `$id` | May lag the latest tag. `CHANGELOG.md` is authoritative. |
 | `npx @open-predicate/open-predicate` | Works from `0.6.1`. **Broken in `0.6.0`**, where the `bin` exited 0 having printed nothing — the entry guard compared `process.argv[1]` against `import.meta.url`, and npm installs a `bin` as a *symlink*. Use the package name, not the bin name `open-predicate-generate`, which is not a package. |
 
@@ -488,10 +488,10 @@ npm i @open-predicate/open-predicate
 or with no package manager in the way — pinning a tag rather than `main`:
 
 ```bash
-curl -O https://raw.githubusercontent.com/OpenPredicate/open-predicate/v0.6.1/open-predicate-schema.json
+curl -O https://raw.githubusercontent.com/OpenPredicate/open-predicate/v0.6.2/open-predicate-schema.json
 ```
 
-The served copy and the packaged copy are the same bytes: the site vendors the schema out of this repository at a tag, so a release moves both together. See [`RELEASING.md`](./RELEASING.md).
+The served copy and the packaged copy are the same bytes: the site vendors the schema out of this repository at a tag, so a release moves both together. See [`RELEASING.md`](https://github.com/OpenPredicate/open-predicate/blob/main/RELEASING.md).
 
 **What is stable enough to review.** The grammar, the operator set and profile grouping, the null and three-valued semantics, and the error model. Those are what the schema, [`SPEC.md`](./SPEC.md) and the test suite pin down, and they are what feedback is most useful on. The grammar may still change before 1.0; each break is recorded in [`CHANGELOG.md`](./CHANGELOG.md) with a migration note.
 
@@ -499,7 +499,7 @@ The served copy and the packaged copy are the same bytes: the site vendors the s
 
 OpenPredicate is stewarded by the [**OpenPredicate**](https://openpredicate.tech) organisation, at [github.com/OpenPredicate](https://github.com/OpenPredicate). Its purpose is to take this predicate grammar from a single-author design to an **open standard**, and to push for its adoption at the places APIs are already described: `$ref`-ed from OpenAPI documents, inlined as MCP tool `inputSchema`s, and carried as the body of the HTTP `QUERY` method.
 
-That goal sets the terms of the work. The grammar is specified normatively in [`SPEC.md`](./SPEC.md) rather than left to a reference implementation, so that independent implementations can agree; every breaking change is recorded with a migration note; and each significant design decision is argued in writing under [`decisions/`](./decisions) rather than settled by commit. Adoption arguments belong in the open too — [`COMPARISON.md`](./COMPARISON.md) is where the case against the nearest alternative is made and its gaps admitted.
+That goal sets the terms of the work. The grammar is specified normatively in [`SPEC.md`](./SPEC.md) rather than left to a reference implementation, so that independent implementations can agree; every breaking change is recorded with a migration note; and each significant design decision is argued in writing under [`decisions/`](https://github.com/OpenPredicate/open-predicate/tree/main/decisions) rather than settled by commit. Adoption arguments belong in the open too — [`COMPARISON.md`](./COMPARISON.md) is where the case against the nearest alternative is made and its gaps admitted.
 
 [`GOVERNANCE.md`](./GOVERNANCE.md) is where that process is written down: what each class of change costs, how a disputed design call is resolved — including that dissent is recorded in the decision record rather than discarded — what earns commit rights, and the project's royalty-free patent posture. It also states plainly that there is currently one maintainer, and treats that as the defect it is.
 

package/SECURITY.md

@@ -0,0 +1,92 @@
+# Security policy
+
+## What this project is, and what that means for a report
+
+OpenPredicate is a **specification and a JSON Schema**, plus a generator and some examples. It has no
+runtime dependencies and executes nothing on a server. So a security report here is usually not
+"this code is exploitable" but one of two other things, and both are in scope:
+
+1. **A defect in the specification that makes conforming implementations unsafe.** A rule that, if
+   followed, produces a vulnerability. These are the serious ones, because they replicate into every
+   implementation.
+2. **A vulnerability in the shipped tooling** — `tools/generate-filter-schema.mjs`, the published npm
+   package, the examples, or the release pipeline.
+
+## In scope
+
+A filter is user-supplied input that becomes a query plan, and [SPEC.md §7](./SPEC.md) bounds it
+normatively. Reports that land squarely in scope include:
+
+- **A filter that stays within the §7 limits and is still superlinear.** The recommended defaults are
+  depth 10, 100 clauses, 1000 set members, 64 KiB body and 100 ms per `$regex` per record. A filter
+  that satisfies all five and still degrades a reasonable backend is a specification bug — the limits
+  are drawn in the wrong place.
+- **A `$regex` operand that defeats the 100 ms guidance**, or a case where the advice to prefer a
+  non-backtracking engine is insufficient rather than merely inconvenient.
+- **Anything that causes a predicate to be dropped, widened or truncated.** This is the failure mode
+  the specification treats as most dangerous: §2.1 forbids silently ignoring an unsupported operator
+  and §7 forbids truncating an over-limit filter, both because a filter that matches *more* than
+  asked is an authorization bypass wherever filters carry tenancy or visibility. If you find a path
+  through the spec where a conforming implementation ends up widening a result set, report it here
+  rather than as a design objection.
+- **An injection or escaping defect** in the filter-to-SQL compiler under
+  [`experiments/filter-to-sql/`](https://github.com/OpenPredicate/open-predicate/tree/main/experiments/filter-to-sql), even though it is explicitly an
+  exercise and not a deliverable. It is the thing people will read to learn how to compile a filter,
+  so an unsafe pattern in it propagates.
+- **Schema-level resource exhaustion**: a document that makes a conforming validator behave
+  pathologically, including through the recursive `$ref` structure or the generator's emitted output.
+- **Anything in the supply chain**: the trusted-publisher configuration, the release workflow, or a
+  published tarball that does not match the repository.
+
+## Out of scope
+
+- Vulnerabilities in *your* server that come from not implementing §7 at all. Bounding a filter is
+  `MUST`; not doing it is a bug in the implementation, and the answer is to implement the limits.
+- Denial of service from unindexed fields where the capability document was not used to restrict
+  expensive operators to indexed ones — §7 already says to do this. Report it if the guidance is
+  *wrong*, not if it was skipped.
+- Design objections with no safety consequence. Those are welcome, but as a
+  [design objection](./CONTRIBUTING.md) issue, in public.
+- Reports against `npm install open-predicate`, the unscoped deprecated placeholder, which holds two
+  files and no code.
+
+## Supported versions
+
+Pre-1.0, **only the latest release is supported.** Fixes land on `main` and ship in the next release;
+there are no backports. Versioned schema `$id`s are immutable by policy ([SPEC.md §9](./SPEC.md)), so
+a security fix that changes the grammar produces a *new* version rather than altering a published
+one — an implementation pinned to an old `$id` must move to get the fix, and the `CHANGELOG.md`
+migration note will say so.
+
+| Version | Supported |
+| --- | --- |
+| 0.6.x | Yes |
+| < 0.6 | No |
+
+## Reporting
+
+**Do not open a public issue for anything in the *In scope* list above.**
+
+Use GitHub's private vulnerability reporting —
+[**Report a vulnerability**](https://github.com/OpenPredicate/open-predicate/security/advisories/new)
+— which keeps the report private until an advisory is published. If that is unavailable to you, email
+**contact@openpredicate.tech**; say in the subject line that it is a security report, and do not
+include exploit details in the first message if you would rather establish the channel first.
+
+Please include the filter, the schema version, and what a conforming implementation does with it.
+A reproducing filter is worth more than a description of one.
+
+## What happens next
+
+- **Acknowledgement within 7 days**, and an initial assessment within 14. There is one maintainer;
+  if you have heard nothing after 14 days, send a reminder rather than assuming it was ignored.
+- **A fix or a decision, in writing.** If a report turns out to be a specification defect, the
+  resolution goes through a [decision record](./GOVERNANCE.md) like any other normative change — with
+  the difference that the record is published when the fix ships, not while it is embargoed.
+- **Coordinated disclosure.** We will agree a date with you, defaulting to 90 days or the fix,
+  whichever is sooner. Because this is a specification, a defect in class (1) above may need other
+  implementers notified before it is public; if that applies we will tell you, and say who.
+- **Credit** in the advisory and the changelog, under whatever name you choose, or none.
+
+There is no bug bounty. This is an unfunded single-maintainer project and pretending otherwise would
+waste your time.

package/SPEC.md

@@ -399,7 +399,7 @@ is TRUE only when a **single** item has both `qty > 2` and an `A` SKU.
 
 is TRUE when *some* item has `qty > 2` and *some* item has an `A` SKU — **possibly different items**, because each `$some` chooses its own element.
 
-Both readings are expressible and the nesting says which is meant. Versions before v0.4.0 offered a second mechanism for the second reading — a `[*]` wildcard path segment — which expressed nothing the two-clause form does not, could not be declined by a server through its profiles, and left the quantifier's scope to be inferred from a path shape. It was removed; see [`decisions/0001`](./decisions/0001-array-quantifiers-and-unknown-handling.md).
+Both readings are expressible and the nesting says which is meant. Versions before v0.4.0 offered a second mechanism for the second reading — a `[*]` wildcard path segment — which expressed nothing the two-clause form does not, could not be declined by a server through its profiles, and left the quantifier's scope to be inferred from a path shape. It was removed; see [`decisions/0001`](https://github.com/OpenPredicate/open-predicate/blob/main/decisions/0001-array-quantifiers-and-unknown-handling.md).
 
 ### 5.10 Presence and type — `$exists`, `$isNull`, `$type`
 

package/SUPPORT.md

@@ -0,0 +1,38 @@
+# Getting help
+
+**One maintainer, no service-level agreement.** Everything here is best-effort, usually within a week.
+Knowing that up front is more useful than a promise that does not hold.
+
+## Where to go
+
+| You want to | Go to |
+| --- | --- |
+| Try a filter and see it validate | The [playground](https://openpredicate.tech/playground/) — runs the real schema in your browser and shows the error a conforming server would return |
+| Know what an operator means, normatively | [`SPEC.md`](./SPEC.md), or the generated [operator reference](https://openpredicate.tech/operators/) |
+| Ask how to do something | [Discussions → Q&A](https://github.com/OpenPredicate/open-predicate/discussions) |
+| Argue that a design decision is wrong | An issue, using the *design objection* template — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) |
+| Report that the schema and the spec disagree | An issue, using the *spec ambiguity* template |
+| Report a security or denial-of-service concern | [`SECURITY.md`](./SECURITY.md) — **not** a public issue |
+| Say you have implemented it | An issue, using the *implementation report* template. These are the most welcome issues the project receives |
+| Understand why a decision was made | [`decisions/`](https://github.com/OpenPredicate/open-predicate/tree/main/decisions) and [`CHANGELOG.md`](./CHANGELOG.md), which carries a migration note for every break |
+| Know how this compares to GraphQL, OData, CQL2, Mongo or JSONPath | [`COMPARISON.md`](./COMPARISON.md), including the gaps it admits |
+
+## Questions that already have answers
+
+Three things surprise almost everyone, and all three are deliberate:
+
+- **Sibling members AND together, and a bare scalar means `$eq`.** `{"status": "open", "rank": 3}`
+  is `status = 'open' AND rank = 3`. You only need `$and` to repeat a field, or to nest inside `$or`.
+- **A comparison against `null` or an absent field is UNKNOWN, not FALSE — and only TRUE matches.**
+  So `{"status": {"$ne": "archived"}}` does **not** match a record whose status is missing. That is
+  SQL's behaviour. When you want those records, say so: `{"$ne": "archived", "$unknownAs": true}`.
+- **`$in` does not look inside arrays.** It is whole-value comparison. Element membership is
+  `{"tags": {"$some": {"$in": [...]}}}`. This differs from MongoDB on purpose — overloading `$in`
+  makes the meaning depend on data a validator cannot see.
+
+## Versions
+
+Pre-1.0: only the latest release is supported, and the grammar may still break before 1.0. Pin an
+exact version if you depend on it. The schema `$id` is versioned and immutable — `v0.4.0` will always
+return the bytes it returned the day it was published — so `$ref`-ing a versioned `$id` is the
+safe thing to do. There is deliberately no `latest` URL.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@open-predicate/open-predicate",
-  "version": "0.6.1",
-  "description": "OpenPredicate — an open standard for JSON-encoded, SQL-flavoured predicates, described by a single JSON Schema: $ref it from OpenAPI, or inline it into an MCP tool's inputSchema.",
+  "version": "0.6.2",
+  "description": "OpenPredicate \u2014 an open standard for JSON-encoded, SQL-flavoured predicates, described by a single JSON Schema: $ref it from OpenAPI, or inline it into an MCP tool's inputSchema.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -48,7 +48,13 @@
     "tools/",
     "SPEC.md",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "COMPARISON.md",
+    "CONTRIBUTING.md",
+    "GOVERNANCE.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "SUPPORT.md"
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",