eyeling 1.13.6 → 1.13.7

package/README.md

@@ -2,9 +2,9 @@
 
 A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
-- Single self-contained bundle (`eyeling.js`), no external runtime deps
-- Forward (`=>`) + backward (`<=`) chaining over Horn-style rules
-- **CLI / npm `reason()` output is mode-dependent by default**: **newly derived forward facts** in normal mode, or — when top-level `{ ... } log:query { ... }.` directives are present — the **unique instantiated conclusion triples** of those queries (a forward-rule-like projection), optionally with compact proof comments
+- Single self-contained bundle (`eyeling.js`), no external runtime dependencies
+- Forward (`=>`) and backward (`<=`) chaining over Horn-style rules
+- **CLI / npm `reason()` output is mode-dependent by default**: it prints **newly derived forward facts** in normal mode, or (when top-level `{ ... } log:query { ... }.` directives are present) the **unique instantiated conclusion triples** of those queries, optionally with compact proof comments
 - Works in Node.js and fully client-side (browser/worker)
 
 ## Links
@@ -15,9 +15,7 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 - **Notation3 test suite:** [https://codeberg.org/phochste/notation3tests](https://codeberg.org/phochste/notation3tests)
 - **Eyeling conformance report:** [https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)
 
-Eyeling is regularly checked against the community Notation3 test suite; the report above tracks current pass/fail results.
-
-If you want to understand how the parser, unifier, proof search, skolemization, scoped closure, and builtins are implemented, start with the handbook.
+Eyeling is regularly checked against the community Notation3 test suite. If you want implementation details (parser, unifier, proof search, skolemization, scoped closure, builtins), start with the handbook.
 
 ## Quick start
 
@@ -31,7 +29,7 @@ If you want to understand how the parser, unifier, proof search, skolemization,
 npm i eyeling
 ```
 
-### CLI
+## CLI usage
 
 Run on a file:
 
@@ -39,23 +37,33 @@ Run on a file:
 npx eyeling examples/socrates.n3
 ```
 
-See all options:
+Show all options:
 
 ```bash
 npx eyeling --help
 ```
 
-### log:query output selection
+Useful flags include `--proof-comments`, `--stream`, `--strings`, and `--enforce-https`.
+
+## What gets printed?
+
+### Normal mode (default)
+
+Without top-level `log:query` directives, Eyeling prints **newly derived forward facts** by default.
+
+### `log:query` mode (output selection)
 
-If your input contains one or more **top-level** directives of the form:
+If the input contains one or more **top-level** directives of the form:
 
 ```n3
 { ?x a :Human. } log:query { ?x a :Mortal. }.
 ```
 
-Eyeling will still compute the saturated forward closure, but it will **print only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of printing all newly derived forward facts).
+Eyeling still computes the saturated forward closure, but it **prints only** the **unique instantiated conclusion triples** of those `log:query` directives (instead of all newly derived forward facts).
 
-### JavaScript API
+## JavaScript API
+
+### npm helper: `reason()`
 
 CommonJS:
 
@@ -69,7 +77,7 @@ const input = `
 :Socrates a :Human.
 :Human rdfs:subClassOf :Mortal.
 
-{ ?S a ?A. ?A rdfs:subClassOf ?B } => { ?S a ?B }.
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
 `;
 
 console.log(reason({ proofComments: false }, input));
@@ -79,37 +87,57 @@ ESM:
 
 ```js
 import eyeling from 'eyeling';
+
 console.log(eyeling.reason({ proofComments: false }, input));
 ```
 
-Streaming / in-process reasoning (browser/worker, direct `eyeling.js`):
+Notes:
+
+- `reason()` returns the same textual output you would get from the CLI for the same input/options.
+- By default, the npm helper keeps output machine-friendly (`proofComments: false`).
+- The npm helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
+
+### Direct bundle / browser-worker API: `reasonStream()`
+
+For in-process reasoning (browser, worker, or direct use of `eyeling.js`):
 
 ```js
-const { closureN3 } = eyeling.reasonStream(input, {
+const result = eyeling.reasonStream(input, {
   proof: false,
   onDerived: ({ triple }) => console.log(triple),
+  // includeInputFactsInClosure: false,
 });
 
-// `closureN3` is also mode-dependent:
-// - normal forward mode: closure (input facts + derived facts) by default
-// - `log:query` mode: the query-selected triples
-// To exclude input facts from the normal-mode closure, pass:
-//   includeInputFactsInClosure: false
-// The return value also includes `queryMode`, `queryTriples`, and `queryDerived`.
+console.log(result.closureN3);
 ```
 
-> Note: the npm `reason()` helper shells out to the bundled `eyeling.js` CLI for simplicity and robustness.
+#### `reasonStream()` output behavior
+
+`closureN3` is also mode-dependent:
+
+- **Normal mode:** by default, `closureN3` is the closure (**input facts + derived facts**)
+- **`log:query` mode:** `closureN3` is the **query-selected triples**
+
+To exclude input facts from the normal-mode closure, pass:
+
+```js
+includeInputFactsInClosure: false;
+```
+
+The returned object also includes `queryMode`, `queryTriples`, and `queryDerived` (and in normal mode, `onDerived` fires for newly derived facts; in `log:query` mode it fires for the query-selected derived triples).
 
 ## Builtins
 
-Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).
+Builtins are defined in [eyeling-builtins.ttl](https://github.com/eyereasoner/eyeling/blob/main/eyeling-builtins.ttl) and described in the [Handbook (Chapter 11)](https://eyereasoner.github.io/eyeling/HANDBOOK#ch11).
 
-## Testing (repo checkout)
+## Development and testing (repo checkout)
 
 ```bash
 npm test
 ```
 
+You can also inspect the `examples/` directory for many small and large N3 programs.
+
 ## License
 
-MIT (see [LICENSE](https://github.com/eyereasoner/eyeling/blob/main/LICENSE.md)).
+MIT — see [LICENSE.md](https://github.com/eyereasoner/eyeling/blob/main/LICENSE.md).

package/examples/odrl-dpv-campaign-audit.n3

@@ -0,0 +1,195 @@
+# ===================================================================================
+# odrl-dpv-campaign-audit.n3
+#
+# A "reasoning about reasoning" example using both ODRL and DPV.
+#
+# What this demonstrates
+# ----------------------
+# 1) Object-level reasoning inside a quoted policy theory:
+#    - ODRL permissions specify who may read which dataset
+#    - DPV annotations specify policy purpose and data category
+#    - local rules translate ODRL + DPV metadata into effective access summaries
+#
+# 2) Meta-level reasoning outside that quoted theory:
+#    - compute the closure of the quoted policy theory
+#    - inspect what the policy theory entails
+#    - derive an audit decision based on those entailed consequences
+#
+# Why this is "reasoning about reasoning"
+# ---------------------------------------
+# The final audit decision is derived from statements ABOUT the closure of the quoted
+# policy theory (what the policy entails), not directly from the raw asserted policy.
+#
+# Modeling note
+# -------------
+# This is a pedagogical example:
+# - ODRL is used for policy structure (permission/assignee/target/action)
+# - DPV is used for privacy semantics (purpose, personal data categories)
+# - local rules map the combination into audit-friendly facts
+# ===================================================================================
+
+@prefix :     <http://example.org/#>.
+@prefix ey:   <https://eyereasoner.github.io/ns#>.
+@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
+@prefix dpv:  <http://www.w3.org/ns/dpv#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# -----------------------------------------------
+# OBJECT THEORY (QUOTED ODRL + DPV POLICY THEORY)
+# -----------------------------------------------
+
+:case :policyTheory {
+  # ---- Request context (inside the quoted theory)
+  :ticket-99 :request :PublishCampaignAccessSummary.
+
+  # ---- Recipients (local classification for audit decisions)
+  :adVendor a :ExternalRecipient.
+  :marketingTeam a :InternalRecipient.
+
+  # ---- Datasets (annotated with DPV data category)
+  :AudienceList dpv:hasPersonalData dpv:PersonalData.
+  :ProductCatalog a :NonPersonalDataset.
+
+  # ---- ODRL policy A (benign-ish): internal team reads product catalog for service provision
+  :policy-internal a odrl:Set;
+    dpv:hasPurpose dpv:ServiceProvision;
+    odrl:permission [
+      odrl:assignee :marketingTeam;
+      odrl:target :ProductCatalog;
+      odrl:action odrl:read
+    ].
+
+  # ---- ODRL policy B (risky for publication): external vendor reads audience list for marketing
+  :policy-external a odrl:Set;
+    dpv:hasPurpose dpv:Marketing;
+    odrl:permission [
+      odrl:assignee :adVendor;
+      odrl:target :AudienceList;
+      odrl:action odrl:read
+    ].
+
+  # --------------------------------------------------------------------
+  # Object-level translation / normalization rules (pedagogical mapping)
+  # --------------------------------------------------------------------
+
+  # ODRL read permission -> effective read access
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :canRead ?Dataset.
+  }.
+
+  # Lift policy purpose to the recipient (summary view used by the audit layer)
+  {
+    ?Policy dpv:hasPurpose ?Purpose.
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :authorisedPurpose ?Purpose.
+  }.
+
+  # Combine ODRL permission target with DPV data-category annotation on the dataset
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+    ?Dataset dpv:hasPersonalData ?Category.
+  }
+  =>
+  {
+    ?Recipient :authorisedReadCategory ?Category.
+  }.
+}.
+
+# --------------------------
+# META-LEVEL POLICY ANALYSIS
+# --------------------------
+
+# 1) Compute the closure of the quoted ODRL+DPV policy theory.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:conclusion ?PolicyClosure.
+}
+=>
+{
+  :case :policyClosure ?PolicyClosure.
+}.
+
+# 2) Record a witness if the policy closure entails:
+#    external recipient + marketing purpose + personal-data access.
+#
+#    This is a statement ABOUT what the quoted theory entails.
+{
+  :case :policyClosure ?C.
+  ?C log:includes {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :authorisedPurpose dpv:Marketing.
+    ?Recipient :authorisedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :entails {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :authorisedPurpose dpv:Marketing.
+    ?Recipient :authorisedReadCategory dpv:PersonalData.
+  }.
+  :case :risk :ThirdPartyMarketingPersonalDataAccessEntailed.
+}.
+
+# 3) If the request is to publish the campaign access summary and the closure entails the
+#    risky pattern above, require manual review.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-99 :request :PublishCampaignAccessSummary.
+  }.
+  :case :risk :ThirdPartyMarketingPersonalDataAccessEntailed.
+}
+=>
+{
+  :case :decision :ManualReviewRequired.
+}.
+
+# 4) Otherwise, if the same request is present but the closure does NOT entail any external
+#    recipient with marketing-purpose personal-data access, auto-approve.
+#
+#    Important: log:notIncludes applies to FORMULAS, so it is applied to ?C (the closure).
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-99 :request :PublishCampaignAccessSummary.
+  }.
+  :case :policyClosure ?C.
+  ?C log:notIncludes {
+    [] a :ExternalRecipient.
+    [] :authorisedPurpose dpv:Marketing.
+    [] :authorisedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :decision :AutoApprove.
+}.
+
+# ------------
+# QUERY INTENT
+# ------------
+
+# These top-level log:query directives define the query-projected outputs.
+{ :case :decision ?Decision. } log:query { :case :decision ?Decision. }.
+{ :case :entails ?Witness. }  log:query { :case :entails ?Witness. }.
+

package/examples/odrl-dpv-conflict-audit.n3

@@ -0,0 +1,264 @@
+# =========================================================================================
+# odrl-dpv-conflict-audit.n3
+#
+# A "reasoning about reasoning" example using ODRL + DPV with conflict detection.
+#
+# What this demonstrates
+# ----------------------
+# 1) Object-level reasoning inside a quoted policy theory:
+#    - ODRL permission/prohibition rules specify allowed/forbidden reads
+#    - DPV annotations specify purpose and personal-data involvement
+#    - local translation rules derive normalized access summaries
+#
+# 2) Meta-level reasoning outside that quoted theory:
+#    - compute the closure of the quoted theory
+#    - inspect what the quoted theory entails
+#    - detect a conflict pattern (permission + prohibition) in the closure
+#    - derive an audit decision from that detected conflict
+#
+# Why this is "reasoning about reasoning"
+# ---------------------------------------
+# The final audit decision is based on a pattern found in the closure of the quoted policy
+# theory (i.e., what the policy *entails*), not merely on directly asserted source triples.
+#
+# Modeling note
+# -------------
+# This is a pedagogical example, not a full ODRL evaluator:
+# - ODRL is used for policy structure (permission/prohibition/assignee/target/action)
+# - DPV is used for purpose and personal-data semantics
+# - local rules translate the combination into audit-friendly facts
+# =========================================================================================
+
+@prefix :     <http://example.org/#>.
+@prefix ey:   <https://eyereasoner.github.io/ns#>.
+@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
+@prefix dpv:  <http://www.w3.org/ns/dpv#>.
+@prefix pd:   <https://w3id.org/dpv/pd#>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ------------------------------------------------------
+# OBJECT THEORY (QUOTED ODRL + DPV POLICY / AUDIT INPUT)
+# ------------------------------------------------------
+
+:case :policyTheory {
+  # ---- Request context (inside the quoted theory)
+  :ticket-314 :request :PublishPartnerCampaignPolicy.
+
+  # ---- Local recipient classification used by audit reasoning
+  :adVendor a :ExternalRecipient.
+  :analyticsTeam a :InternalRecipient.
+
+  # ---- Dataset classification / DPV semantics
+  #
+  # We include both a concrete PD category and a generic PersonalData category so the
+  # example can query either level without depending on external DPV taxonomy inference.
+  :AudienceList dpv:hasPersonalData pd:EmailAddress.
+  :AudienceList dpv:hasPersonalData dpv:PersonalData.
+
+  :ProductCatalog a :NonPersonalDataset.
+
+  # ---- ODRL policy A: PERMIT external vendor to read audience list for marketing
+  :policy-allow-external a odrl:Set;
+    dpv:hasPurpose dpv:Marketing;
+    odrl:permission [
+      odrl:assignee :adVendor;
+      odrl:target :AudienceList;
+      odrl:action odrl:read
+    ].
+
+  # ---- ODRL policy B: PROHIBIT the same external vendor from reading the same dataset
+  #      for the same purpose (intentional conflict for audit demonstration)
+  :policy-deny-external a odrl:Set;
+    dpv:hasPurpose dpv:Marketing;
+    odrl:prohibition [
+      odrl:assignee :adVendor;
+      odrl:target :AudienceList;
+      odrl:action odrl:read
+    ].
+
+  # ---- ODRL policy C: benign internal permission (noise / contrast)
+  :policy-allow-internal a odrl:Set;
+    dpv:hasPurpose dpv:ServiceProvision;
+    odrl:permission [
+      odrl:assignee :analyticsTeam;
+      odrl:target :ProductCatalog;
+      odrl:action odrl:read
+    ].
+
+  # ----------------------------------------------
+  # Object-level translation / normalization rules
+  # ----------------------------------------------
+
+  # Permission(read) -> normalized permission fact
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :permittedRead ?Dataset.
+  }.
+
+  # Prohibition(read) -> normalized prohibition fact
+  {
+    ?Policy odrl:prohibition [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :prohibitedRead ?Dataset.
+  }.
+
+  # Lift policy purpose to recipient (permission side)
+  {
+    ?Policy dpv:hasPurpose ?Purpose.
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :permittedPurpose ?Purpose.
+  }.
+
+  # Lift policy purpose to recipient (prohibition side)
+  {
+    ?Policy dpv:hasPurpose ?Purpose.
+    ?Policy odrl:prohibition [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?Recipient :prohibitedPurpose ?Purpose.
+  }.
+
+  # Combine permission target with DPV personal-data category annotation
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+    ?Dataset dpv:hasPersonalData ?Category.
+  }
+  =>
+  {
+    ?Recipient :permittedReadCategory ?Category.
+  }.
+
+  # Combine prohibition target with DPV personal-data category annotation
+  {
+    ?Policy odrl:prohibition [
+      odrl:assignee ?Recipient;
+      odrl:target ?Dataset;
+      odrl:action odrl:read
+    ].
+    ?Dataset dpv:hasPersonalData ?Category.
+  }
+  =>
+  {
+    ?Recipient :prohibitedReadCategory ?Category.
+  }.
+}.
+
+# --------------------------
+# META-LEVEL POLICY ANALYSIS
+# --------------------------
+
+# 1) Compute the closure of the quoted ODRL+DPV policy theory.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:conclusion ?PolicyClosure.
+}
+=>
+{
+  :case :policyClosure ?PolicyClosure.
+}.
+
+# 2) Detect a conflict witness by inspecting the policy closure.
+#
+#    Conflict pattern:
+#    - same external recipient
+#    - marketing purpose permitted AND prohibited
+#    - personal-data access category permitted AND prohibited
+#
+#    This rule does NOT inspect raw asserted policy statements directly;
+#    it inspects normalized consequences entailed by the quoted theory's closure.
+{
+  :case :policyClosure ?C.
+  ?C log:includes {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :permittedPurpose dpv:Marketing.
+    ?Recipient :prohibitedPurpose dpv:Marketing.
+    ?Recipient :permittedReadCategory dpv:PersonalData.
+    ?Recipient :prohibitedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :entails {
+    ?Recipient a :ExternalRecipient.
+    ?Recipient :permittedPurpose dpv:Marketing.
+    ?Recipient :prohibitedPurpose dpv:Marketing.
+    ?Recipient :permittedReadCategory dpv:PersonalData.
+    ?Recipient :prohibitedReadCategory dpv:PersonalData.
+  }.
+  :case :risk :PermissionProhibitionConflictEntailed.
+}.
+
+# 3) If the request is to publish the partner campaign policy and a conflict is entailed,
+#    require manual review.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-314 :request :PublishPartnerCampaignPolicy.
+  }.
+  :case :risk :PermissionProhibitionConflictEntailed.
+}
+=>
+{
+  :case :decision :ManualReviewRequired.
+}.
+
+# 4) Otherwise, if the request is present but the closure does NOT entail the conflict
+#    pattern, auto-approve.
+#
+#    Important: log:notIncludes applies to FORMULAS, so it is applied to ?C (the closure).
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes {
+    :ticket-314 :request :PublishPartnerCampaignPolicy.
+  }.
+  :case :policyClosure ?C.
+  ?C log:notIncludes {
+    [] a :ExternalRecipient.
+    [] :permittedPurpose dpv:Marketing.
+    [] :prohibitedPurpose dpv:Marketing.
+    [] :permittedReadCategory dpv:PersonalData.
+    [] :prohibitedReadCategory dpv:PersonalData.
+  }.
+}
+=>
+{
+  :case :decision :AutoApprove.
+}.
+
+# ------------
+# QUERY INTENT
+# ------------
+
+# Top-level query directives define what is printed in query mode.
+{ :case :decision ?Decision. } log:query { :case :decision ?Decision. }.
+{ :case :entails ?Witness. }  log:query { :case :entails ?Witness. }.
+

package/examples/odrl-policy-audit.n3

@@ -0,0 +1,147 @@
+# ==========================================================================================
+# odrl-policy-audit.n3
+#
+# A "reasoning about reasoning" example using ODRL policies.
+#
+# What this demonstrates
+# ----------------------
+# 1) Object-level reasoning (inside a quoted ODRL policy theory):
+#    - ODRL permissions (assignee/target/action) are translated into effective access facts
+#
+# 2) Meta-level reasoning (outside that quoted theory):
+#    - compute the closure of the quoted policy theory
+#    - inspect what the policy theory entails
+#    - derive an audit decision based on entailed consequences
+#
+# Why this is "reasoning about reasoning"
+# ---------------------------------------
+# The audit decision is not derived directly from the asserted ODRL policy statements.
+# It is derived from statements ABOUT what the quoted ODRL policy theory entails
+# (i.e., from the closure of that quoted theory).
+# ==========================================================================================
+
+@prefix :     <http://example.org/#>.
+@prefix ey:   <https://eyereasoner.github.io/ns#>.
+@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------------------------------
+# OBJECT THEORY (QUOTED ODRL POLICY)
+# ----------------------------------
+
+# The ODRL policy and object-level translation rules live inside a quoted formula so that
+# the surrounding (meta-level) rules can reason about its semantics (its closure) as data.
+:case :policyTheory {
+  # ---- Context / request (asserted input within the quoted theory)
+  :ticket-42 :request :PublishPolicySnapshot.
+
+  # ---- ODRL policy statements
+  #
+  # This policy grants Alice permission to read two assets:
+  # - a general handbook (benign)
+  # - the payroll ledger (sensitive for publication audits)
+  :policy-1 a odrl:Set;
+    odrl:permission [
+      odrl:assignee :alice;
+      odrl:target :EmployeeHandbook;
+      odrl:action odrl:read
+    ];
+    odrl:permission [
+      odrl:assignee :alice;
+      odrl:target :PayrollLedger;
+      odrl:action odrl:read
+    ].
+
+  # ---- Domain classification
+  :PayrollLedger a :SensitiveAsset.
+  :PayrollLedger a :PayrollAsset.
+  :EmployeeHandbook a :PublicAsset.
+
+  # ---- Object-level reasoning rules over ODRL permissions
+  #
+  # Translate a simple ODRL permission statement into an effective access fact.
+  # (This is a minimal pedagogical mapping, not a complete ODRL evaluator.)
+  {
+    ?Policy odrl:permission [
+      odrl:assignee ?User;
+      odrl:target ?Asset;
+      odrl:action odrl:read
+    ].
+  }
+  =>
+  {
+    ?User :canRead ?Asset.
+  }.
+
+  # Normalize "canRead" into a generic access predicate used by the audit layer.
+  {
+    ?User :canRead ?Asset.
+  }
+  =>
+  {
+    ?User :canAccess ?Asset.
+  }.
+}.
+
+# --------------------------
+# META-LEVEL POLICY ANALYSIS
+# --------------------------
+
+# 1) Compute the closure of the quoted ODRL policy theory.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:conclusion ?PolicyClosure.
+}
+=>
+{
+  :case :policyClosure ?PolicyClosure.
+}.
+
+# 2) Record a witness if the quoted policy theory entails access to the payroll ledger.
+#    This is a statement ABOUT what the policy theory entails.
+{
+  :case :policyClosure ?C.
+  ?C log:includes { ?User :canAccess :PayrollLedger. }.
+}
+=>
+{
+  :case :entails { ?User :canAccess :PayrollLedger. }.
+  :case :risk :SensitiveAccessEntailed.
+}.
+
+# 3) If a publication request is present in the quoted theory AND sensitive access is
+#    entailed by the quoted theory, require manual review.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes { :ticket-42 :request :PublishPolicySnapshot. }.
+  :case :risk :SensitiveAccessEntailed.
+}
+=>
+{
+  :case :decision :ManualReviewRequired.
+}.
+
+# 4) Otherwise, if the publication request is present but NO payroll-ledger access is
+#    entailed by the policy closure, the case can be auto-approved.
+#
+#    Important: log:notIncludes applies to FORMULAS, so we test absence on ?C (the closure),
+#    not on a regular resource like :case.
+{
+  :case :policyTheory ?PolicyTheory.
+  ?PolicyTheory log:includes { :ticket-42 :request :PublishPolicySnapshot. }.
+  :case :policyClosure ?C.
+  ?C log:notIncludes { _:user :canAccess :PayrollLedger. }.
+}
+=>
+{
+  :case :decision :AutoApprove.
+}.
+
+# ------------
+# QUERY INTENT
+# ------------
+
+# These top-level log:query statements describe the intended outputs.
+{ :case :decision ?Decision. } log:query { :case :decision ?Decision. }.
+{ :case :entails ?Witness. }  log:query { :case :entails ?Witness. }.
+

package/examples/output/odrl-dpv-campaign-audit.n3

@@ -0,0 +1,10 @@
+@prefix : <http://example.org/#> .
+@prefix dpv: <http://www.w3.org/ns/dpv#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+
+:case :decision :ManualReviewRequired .
+:case :entails {
+    :adVendor a :ExternalRecipient .
+    :adVendor :authorisedPurpose dpv:Marketing .
+    :adVendor :authorisedReadCategory dpv:PersonalData .
+} .

package/examples/output/odrl-dpv-conflict-audit.n3

@@ -0,0 +1,12 @@
+@prefix : <http://example.org/#> .
+@prefix dpv: <http://www.w3.org/ns/dpv#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+
+:case :decision :ManualReviewRequired .
+:case :entails {
+    :adVendor a :ExternalRecipient .
+    :adVendor :permittedPurpose dpv:Marketing .
+    :adVendor :prohibitedPurpose dpv:Marketing .
+    :adVendor :permittedReadCategory dpv:PersonalData .
+    :adVendor :prohibitedReadCategory dpv:PersonalData .
+} .

package/examples/output/odrl-policy-audit.n3

@@ -0,0 +1,6 @@
+@prefix : <http://example.org/#> .
+
+:case :decision :ManualReviewRequired .
+:case :entails {
+    :alice :canAccess :PayrollLedger .
+} .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.13.6",
+  "version": "1.13.7",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/examples.test.js

@@ -30,17 +30,6 @@ function run(cmd, args, opts = {}) {
   });
 }
 
-function hasGit() {
-  const r = run('git', ['--version']);
-  return r.status === 0;
-}
-
-function inGitWorktree(cwd) {
-  if (!hasGit()) return false;
-  const r = run('git', ['rev-parse', '--is-inside-work-tree'], { cwd });
-  return r.status === 0 && String(r.stdout).trim() === 'true';
-}
-
 // Normalize output for comparison.
 // Eyeling (and other N3 tools) may emit the same closure with different
 // triple ordering. Examples tests should verify content, not presentation.
@@ -83,26 +72,10 @@ function rmrf(p) {
   } catch {}
 }
 
-function showDiff({ IN_GIT, examplesDir, expectedPath, generatedPath, relExpectedPosix }) {
-  if (hasGit()) {
-    if (IN_GIT) {
-      // Show repo diff for the overwritten golden file
-      const d = run('git', ['diff', '--', relExpectedPosix], { cwd: examplesDir });
-      if (d.stdout) process.stdout.write(d.stdout);
-      if (d.stderr) process.stderr.write(d.stderr);
-    } else {
-      // Show no-index diff between packaged golden and generated tmp
-      const d = run('git', ['diff', '--no-index', expectedPath, generatedPath], { cwd: examplesDir });
-      // Replace tmp path in output (nice UX)
-      if (d.stdout) process.stdout.write(String(d.stdout).replaceAll(generatedPath, 'generated'));
-      if (d.stderr) process.stderr.write(String(d.stderr).replaceAll(generatedPath, 'generated'));
-    }
-  } else {
-    // Fallback: diff -u
-    const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
-    if (d.stdout) process.stdout.write(d.stdout);
-    if (d.stderr) process.stderr.write(d.stderr);
-  }
+function showDiff({ examplesDir, expectedPath, generatedPath }) {
+  const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
+  if (d.stdout) process.stdout.write(d.stdout);
+  if (d.stderr) process.stderr.write(d.stderr);
 }
 
 function main() {
@@ -124,14 +97,12 @@ function main() {
     process.exit(1);
   }
 
-  const IN_GIT = inGitWorktree(root);
-
   const files = fs
     .readdirSync(examplesDir)
     .filter((f) => f.endsWith('.n3'))
     .sort((a, b) => a.localeCompare(b));
 
-  info(`Running ${files.length} examples tests (${IN_GIT ? 'git worktree mode' : 'npm-installed mode'})`);
+  info(`Running ${files.length} examples tests`);
   console.log(`${C.dim}${getEyelingVersion(nodePath, eyelingJsPath, root)}; node ${process.version}${C.n}`);
 
   if (files.length === 0) {
@@ -139,9 +110,6 @@ function main() {
     process.exit(0);
   }
 
-  // In maintainer mode we overwrite tracked goldens in examples/output/
-  if (IN_GIT) fs.mkdirSync(outputDir, { recursive: true });
-
   let passed = 0;
   let failed = 0;
 
@@ -156,7 +124,6 @@ function main() {
 
     const filePath = path.join(examplesDir, file);
     const expectedPath = path.join(outputDir, file);
-    const relExpectedPosix = path.posix.join('output', file); // for git diff inside examplesDir
 
     let n3Text;
     try {
@@ -171,34 +138,19 @@ function main() {
 
     const expectedRc = expectedExitCode(n3Text);
 
-    // Snapshot expected output before we potentially overwrite it in git worktree mode.
-    // This lets us compare content ignoring ordering, while still allowing the script
-    // to regenerate output/ files in-place when working from a repo checkout.
-    let expectedBeforeText = null;
-    if (IN_GIT && fs.existsSync(expectedPath)) {
-      try {
-        expectedBeforeText = fs.readFileSync(expectedPath, 'utf8');
-      } catch {
-        expectedBeforeText = null;
-      }
+    // Always write generated output to a temp file. This avoids mutating tracked
+    // examples/output/* during normal test runs and makes timing behavior more
+    // comparable across environments.
+    if (!fs.existsSync(expectedPath)) {
+      const ms = Date.now() - start;
+      fail(`${idx} ${file} ${msTag(ms)}`);
+      fail(`Missing expected output/${file}`);
+      failed++;
+      continue;
     }
 
-    // Decide where generated output goes
-    let tmpDir = null;
-    let generatedPath = expectedPath;
-
-    if (!IN_GIT) {
-      // npm-installed / no .git: never modify output/ in node_modules
-      if (!fs.existsSync(expectedPath)) {
-        const ms = Date.now() - start;
-        fail(`${idx} ${file} ${msTag(ms)}`);
-        fail(`Missing expected output/${file}`);
-        failed++;
-        continue;
-      }
-      tmpDir = mkTmpDir();
-      generatedPath = path.join(tmpDir, 'generated.n3');
-    }
+    const tmpDir = mkTmpDir();
+    const generatedPath = path.join(tmpDir, 'generated.n3');
 
     // Run eyeling on this file (cwd examplesDir so relative behavior matches old script)
     const outFd = fs.openSync(generatedPath, 'w');
@@ -219,7 +171,7 @@ function main() {
     // Compare output (order-insensitive)
     let diffOk = false;
     try {
-      const expectedText = IN_GIT ? expectedBeforeText : fs.readFileSync(expectedPath, 'utf8');
+      const expectedText = fs.readFileSync(expectedPath, 'utf8');
       const generatedText = fs.readFileSync(generatedPath, 'utf8');
       if (expectedText == null) throw new Error('missing expected output');
       diffOk = normalizeForCompare(expectedText) === normalizeForCompare(generatedText);
@@ -245,13 +197,11 @@ function main() {
         fail('Output differs');
       }
 
-      // Show diffs (both modes), because this is a test runner
+      // Show diffs, because this is a test runner
       showDiff({
-        IN_GIT,
         examplesDir,
         expectedPath,
         generatedPath,
-        relExpectedPosix,
       });
 
       failed++;

package/test/n3gen.test.js

@@ -2,14 +2,9 @@
 'use strict';
 
 // Convert examples/input/*.{ttl,trig} -> examples/*.n3 using n3gen.js
-// Designed to work both in a git checkout (maintainer mode) and in an npm-installed package.
 //
-// In git mode:
-//   - overwrites examples/<name>.n3
-//   - uses `git diff` to validate + show diffs
-// In non-git mode:
-//   - writes to a temp dir
-//   - compares against packaged examples/<name>.n3 without modifying it
+// For reproducibility and to avoid mutating tracked files during tests, generated output
+// is always written to a temporary file and compared against examples/<name>.n3.
 
 const fs = require('node:fs');
 const os = require('node:os');
@@ -39,23 +34,6 @@ function run(cmd, args, opts = {}) {
   });
 }
 
-function hasGit() {
-  const r = run('git', ['--version']);
-  return r.status === 0;
-}
-
-function inGitWorktree(cwd) {
-  if (!hasGit()) return false;
-  const r = run('git', ['rev-parse', '--is-inside-work-tree'], { cwd });
-  return r.status === 0 && String(r.stdout).trim() === 'true';
-}
-
-function isTracked(cwd, relPathPosix) {
-  if (!hasGit()) return false;
-  const r = run('git', ['ls-files', '--error-unmatch', relPathPosix], { cwd });
-  return r.status === 0;
-}
-
 function mkTmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'eyeling-n3-'));
 }
@@ -66,29 +44,10 @@ function rmrf(p) {
   } catch {}
 }
 
-function showDiff({ IN_GIT, examplesDir, expectedPath, generatedPath, relExpectedPosix }) {
-  if (hasGit()) {
-    if (IN_GIT) {
-      // If tracked: show repo diff; if untracked: show addition via no-index diff against /dev/null.
-      if (isTracked(examplesDir, relExpectedPosix)) {
-        const d = run('git', ['diff', '--', relExpectedPosix], { cwd: examplesDir });
-        if (d.stdout) process.stdout.write(d.stdout);
-        if (d.stderr) process.stderr.write(d.stderr);
-      } else {
-        const d = run('git', ['diff', '--no-index', '--', '/dev/null', expectedPath], { cwd: examplesDir });
-        if (d.stdout) process.stdout.write(String(d.stdout).replaceAll(expectedPath, relExpectedPosix));
-        if (d.stderr) process.stderr.write(String(d.stderr).replaceAll(expectedPath, relExpectedPosix));
-      }
-    } else {
-      const d = run('git', ['diff', '--no-index', expectedPath, generatedPath], { cwd: examplesDir });
-      if (d.stdout) process.stdout.write(String(d.stdout).replaceAll(generatedPath, 'generated'));
-      if (d.stderr) process.stderr.write(String(d.stderr).replaceAll(generatedPath, 'generated'));
-    }
-  } else {
-    const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
-    if (d.stdout) process.stdout.write(d.stdout);
-    if (d.stderr) process.stderr.write(d.stderr);
-  }
+function showDiff({ examplesDir, expectedPath, generatedPath }) {
+  const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
+  if (d.stdout) process.stdout.write(d.stdout);
+  if (d.stderr) process.stderr.write(d.stderr);
 }
 
 function main() {
@@ -114,14 +73,12 @@ function main() {
     process.exit(1);
   }
 
-  const IN_GIT = inGitWorktree(root);
-
   const inputs = fs
     .readdirSync(inputDir)
     .filter((f) => /\.(ttl|trig)$/i.test(f))
     .sort((a, b) => a.localeCompare(b));
 
-  info(`Running n3 conversions for ${inputs.length} inputs (${IN_GIT ? 'git worktree mode' : 'npm-installed mode'})`);
+  info(`Running n3 conversions for ${inputs.length} inputs`);
   console.log(`${C.dim}node ${process.version}${C.n}`);
 
   if (inputs.length === 0) {
@@ -142,23 +99,18 @@ function main() {
     const outFile = `${base}.n3`;
 
     const expectedPath = path.join(examplesDir, outFile);
-    const relExpectedPosix = outFile; // relative to examplesDir
-
-    let tmpDir = null;
-    let generatedPath = expectedPath;
-
-    if (!IN_GIT) {
-      if (!fs.existsSync(expectedPath)) {
-        const ms = Date.now() - start;
-        fail(`${idx} ${inFile} -> ${outFile} (${ms} ms)`);
-        fail(`Missing expected examples/${outFile}`);
-        failed++;
-        continue;
-      }
-      tmpDir = mkTmpDir();
-      generatedPath = path.join(tmpDir, outFile);
+
+    if (!fs.existsSync(expectedPath)) {
+      const ms = Date.now() - start;
+      fail(`${idx} ${inFile} -> ${outFile} (${ms} ms)`);
+      fail(`Missing expected examples/${outFile}`);
+      failed++;
+      continue;
     }
 
+    const tmpDir = mkTmpDir();
+    const generatedPath = path.join(tmpDir, outFile);
+
     // Run converter (stdout -> file; stderr captured)
     const outFd = fs.openSync(generatedPath, 'w');
     const r = cp.spawnSync(nodePath, [n3GenJsPath, inPath], {
@@ -177,29 +129,13 @@ function main() {
       fail(`Converter exit code ${rc}`);
       if (r.stderr) process.stderr.write(String(r.stderr));
       failed++;
-      if (tmpDir) rmrf(tmpDir);
+      rmrf(tmpDir);
       continue;
     }
 
-    // Compare output
-    let diffOk = false;
-    if (IN_GIT) {
-      if (isTracked(examplesDir, relExpectedPosix)) {
-        const d = run('git', ['diff', '--quiet', '--', relExpectedPosix], { cwd: examplesDir });
-        diffOk = d.status === 0;
-      } else {
-        // Untracked file counts as a diff (work to do)
-        diffOk = false;
-      }
-    } else {
-      if (hasGit()) {
-        const d = run('git', ['diff', '--no-index', '--quiet', expectedPath, generatedPath], { cwd: examplesDir });
-        diffOk = d.status === 0;
-      } else {
-        const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
-        diffOk = d.status === 0;
-      }
-    }
+    // Compare output (always compare expected vs generated temp file)
+    const d = run('diff', ['-u', expectedPath, generatedPath], { cwd: examplesDir });
+    const diffOk = d.status === 0;
 
     if (diffOk) {
       ok(`${idx} ${inFile} -> ${outFile} (${ms} ms)`);
@@ -207,11 +143,11 @@ function main() {
     } else {
       fail(`${idx} ${inFile} -> ${outFile} (${ms} ms)`);
       fail('Output differs');
-      showDiff({ IN_GIT, examplesDir, expectedPath, generatedPath, relExpectedPosix });
+      showDiff({ examplesDir, expectedPath, generatedPath });
       failed++;
     }
 
-    if (tmpDir) rmrf(tmpDir);
+    rmrf(tmpDir);
   }
 
   console.log('');