eyeprolog 1.5.53 → 1.5.54

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.5.53",
+  "version": "1.5.54",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/test/conformance/ISO-IMPLEMENTATION-DEFINED.md

@@ -131,10 +131,9 @@ Normal mode provides documented module and DCG compatibility profiles whose
 features overlap standardized Part 2 and Part 3 facilities. They are extensions
 relative to the Part 1 strict-core boundary and are tested separately; this
 ledger does not assert complete Part 2 or Part 3 conformance. The concrete
-compatibility boundary, including the normal-profile `phrase/2-3` terminal-sequence
-error choice, is recorded in `ISO-PART2-PART3-SCOPE.md`. The requirements
-clarified by the 2013 Part 2 amendment are tracked separately in the executable
-`ISO-PART2-AMENDMENT-2013.md` ledger.
+per-directive and per-predicate boundary is recorded in `ISO-PART2.md` and
+`ISO-PART3.md`, including the 2013 module-amendment evidence and the
+normal-profile `phrase/2-3` terminal-sequence error choice.
 
 ## Important implementation-dependent behavior (not the 5.4 mandatory table)
 

package/test/conformance/ISO-PART2.md

@@ -0,0 +1,117 @@
+# ISO/IEC 13211-2:2000 (Modules) — implementation status
+
+This document records, predicate by predicate and directive by directive, what
+EyeProlog implements of Prolog Part 2 (Modules). It is a status ledger, not a
+conformance claim.
+
+**EyeProlog does not claim Part 2 conformance.** What normal mode provides is a
+procedure-oriented module *compatibility layer* built around the widespread
+Quintus-style syntax. The ISO interface/body directive surface is not
+implemented. `--iso-strict` targets Part 1 + Corrigenda 1-3 only and excludes
+module directives and the `:` operator entirely.
+
+## Interface and body directives (ISO form)
+
+Part 2 separates a module *interface* from one or more module *bodies*. None of
+this surface is implemented; EyeProlog accepts only the compatibility syntax in
+the next section.
+
+| Directive | Part 2 role | Status |
+| --- | --- | --- |
+| `module/1` | begin the interface for a named module | **not implemented** |
+| `export/1` | export locally defined procedures | **not implemented** |
+| `reexport/2` | selectively import from another module and export again | **not implemented** |
+| `reexport/1` | re-export the exports of named modules | **not implemented** |
+| `metapredicate/1` | declare and export context-sensitive procedures (ISO spelling, no underscore) | **not implemented** |
+| `op/3` in an interface | initial operators for this module's bodies only | **not implemented** — operator state is global |
+| `char_conversion/2` in an interface | initial character conversions for this module's bodies only | **not implemented** — conversion state is global |
+| `set_prolog_flag/2` in an interface | initial flag values for this module's bodies only | **not implemented** — flag state is global |
+| `end_module/1` | end the interface | **not implemented** |
+| `body/1` | begin a body of an already interfaced module | **not implemented** |
+| `import/2` | selectively import exported procedures | **not implemented** |
+| `import/1` | import all exports of named modules | **not implemented** |
+| `end_body/1` | end the module body | **not implemented** |
+
+## Compatibility directives (what EyeProlog actually accepts)
+
+| Directive | Status | Notes |
+| --- | --- | --- |
+| `module/2` | **implemented** | `:- module(Name, Exports).` Records the named module and its export map. Non-terminal indicators `A//N` are accepted in the export list. |
+| `use_module/1` | **implemented** | Imports the full export map of the source module. |
+| `use_module/2` | **implemented** | Selective import, validated against the source module's exports. |
+| `meta_predicate/1` | **implemented** | Both `:- meta_predicate p(:).` and the parenthesized spelling. Numeric closure modes are a further EyeProlog extension. |
+| `ensure_loaded/1` | **implemented** | Imports a module's public predicates while keeping source loading idempotent. |
+
+Only one module body is supported per Prolog text: a second `module/2` in the
+same text is rejected rather than switching modules mid-text. Part 2 allows a
+module to have several non-contiguous bodies.
+
+## Built-in predicates
+
+| Predicate | Part 2 requirement | Status |
+| --- | --- | --- |
+| `current_module/1` | enumerate existing modules and test a supplied name; `user` must exist | **not implemented** — raises `existence_error(procedure, current_module/1)` |
+| `predicate_property/2` | module-aware predicate-property model | **not implemented** — raises `existence_error(procedure, predicate_property/2)` |
+| `clause/2` | module-aware redefinition | **partial** — qualification is resolved, but against the compatibility model rather than Part 2 lookup/defining-module rules |
+| `current_predicate/1` | module-aware redefinition | **partial** — as above |
+| `asserta/1` | module-aware redefinition | **partial** — as above |
+| `assertz/1` | module-aware redefinition | **partial** — as above |
+| `retract/1` | module-aware redefinition | **partial** — as above |
+| `abolish/1` | module-aware redefinition | **partial** — as above |
+
+The six *partial* rows share one cause: EyeProlog resolves `Module:Goal` and
+tracks a single module per goal, whereas Part 2 distinguishes defining module,
+lookup module, qualifying module, and calling context. Ordinary calls make
+these coincide, so the difference shows up in meta-calls and nested
+qualification rather than in everyday use.
+
+## Operators and flags
+
+| Item | Part 2 requirement | Status |
+| --- | --- | --- |
+| `:` operator | added to the initial operator table as `op(600, xfy, :)` | **implemented** in normal mode (`current_op(600, xfy, ':')`); deliberately absent from the Part 1 strict initial table |
+| `colon_sets_calling_context` | a Boolean flag governing whether explicit qualification establishes calling context | **not implemented** — `current_prolog_flag/2` raises `domain_error(prolog_flag, colon_sets_calling_context)` |
+
+## 2013 amendment (WG17 N251) coverage
+
+The requirements clarified by the 2013 amendment draft have executable evidence
+in `test/run-iso-part2-amendment.mjs`, which is part of `npm test` and the
+conformance aggregate. This is the one part of the Part 2 surface that is
+release-gated.
+
+| Amendment clause | Required behaviour | EyeProlog behaviour / evidence |
+| --- | --- | --- |
+| 6.2.4.1 | A `module(Name, Exports)` directive identifies a named module and its public predicate indicators. | `Program.defineModule()` records the named module and export map. The focused suite checks that public predicates import and private predicates stay module-local. |
+| 6.2.5 | A module body is a Prolog text beginning with its `module/2` directive and extending to the end of that text. | Files named by `use_module/1-2` are accepted as module sources only when their first read term is `module/2`. A second `module/2` in the same text is rejected; a distinct text may begin a distinct module body. |
+| 6.2.5.5 | `use_module(F, L)` selectively imports the predicates in `L` from the exports of the module defined by `F`. | `Program.importModule()` validates requested indicators against the source module's export map and installs only those imports. |
+| 6.2.5.6 | `use_module(F)` imports all exported predicates; the amendment also aligns the public-predicate effect of `ensure_loaded(F)` for a module source. | `use_module/1` imports the full export map. `ensure_loaded/1` imports a module's public predicates while retaining idempotent source loading, including when the module was already loaded for another caller. |
+| 6.2.5.7 | `meta_predicate/1` marks context-sensitive arguments; `:` arguments carry the current source/calling module. | Normal parsing accepts `:- meta_predicate p(:).`. Colon-mode arguments are represented as an observable `Module:Goal` term, including when the argument is a variable. |
+| 6.4.4.3 | Imported metapredicates preserve the caller's module context for their meta-arguments. | The focused suite verifies both visible `Module:Goal` decomposition and execution of a caller-private predicate through a variable meta-argument. Explicit `Module:Goal` calls set their stated module context. |
+
+## Known gaps
+
+Beyond the *not implemented* rows above, four structural gaps stand between the
+current compatibility layer and a Part 2 claim.
+
+1. **Module-local reader/writer state.** Part 2 makes a calling context include
+   the operator table, character-conversion mapping, and relevant flag values,
+   not just a set of visible procedures. EyeProlog keeps operators, conversions,
+   and flags in one global program state, so interface-local environment
+   settings cannot be expressed. This is the largest single item.
+2. **Four separate module notions.** Defining, lookup, qualifying, and calling
+   context are collapsed into one module field per goal.
+3. **Re-export and visibility conflicts.** There is no re-export model, and no
+   preparation-time rejection of a second import that would make a *different*
+   procedure visible under the same unqualified indicator.
+4. **Introspection.** `current_module/1` and `predicate_property/2` are absent,
+   so the module structure is not observable from within a program.
+
+Interoperability with Scryer, Trealla, or Logtalk is not treated as evidence of
+Part 2 coverage.
+
+## See also
+
+- `ISO-PART3.md` — Part 3 (definite clause grammar rules) status
+- `ISO-COMPLIANCE.md` — the Part 1 review that carries the release-facing claim
+- `ISO-IMPLEMENTATION-DEFINED.md` — implementation-defined choices, including
+  the module-qualification error choice

package/test/conformance/ISO-PART3.md

@@ -0,0 +1,99 @@
+# ISO/IEC 13211-3 (Definite clause grammar rules) — implementation status
+
+This document records what EyeProlog implements of Prolog Part 3, non-terminal
+by non-terminal and predicate by predicate. It is a status ledger, not a
+conformance claim.
+
+Normal mode implements the whole grammar surface below. `--iso-strict` leaves
+`-->/2` as ordinary Part 1 operator syntax and excludes grammar expansion and
+`phrase/2-3` from the strict registry, so `phrase/2` there raises
+`existence_error(procedure, phrase/2)`.
+
+## Grammar control constructs (clause 7.14)
+
+| Clause | Construct | Status |
+| --- | --- | --- |
+| 7.14.1 | `[]//0` — empty terminal-sequence | **implemented** |
+| 7.14.2 | `('.')//2` — terminal sequence | **implemented** |
+| 7.14.3 | `(',')//2` — concatenation | **implemented** |
+| 7.14.4 | `(;)//2` — alternative | **implemented** |
+| 7.14.5 | `(;)//2` with `(->)//2` — if-then-else | **implemented** |
+| 7.14.6 | `('\|')//2` — second form of alternative | **implemented** |
+| 7.14.7 | `{}//1` — grammar-body-goal | **implemented** |
+| 7.14.8 | `call//1` | **implemented** |
+| 7.14.9 | `phrase//1` | **implemented** |
+| 7.14.10 | `!//0` — grammar-body-cut | **implemented** |
+| 7.14.11 | `(\+)//1` — grammar-body-not | **implemented** |
+| 7.14.12 | `(->)//2` — if-then | **implemented** |
+
+## Built-in predicates (clause 8.18)
+
+| Clause | Predicate | Status |
+| --- | --- | --- |
+| 8.18.1 | `phrase/3` | **implemented** |
+| 8.18.1.3 | `phrase/2` (bootstrapped as `phrase(GRBody, S0, [])`) | **implemented** |
+
+### Prescribed errors (8.18.1.4)
+
+| Error | Requirement | EyeProlog |
+| --- | --- | --- |
+| a) `GRBody` is a variable | `instantiation_error` | **matches** |
+| b) `GRBody` is neither a variable nor callable | `type_error(callable, GRBody)` | **matches** |
+| c) `S0` is not a terminal-sequence | `type_error(terminal_sequence, S0)` — implementation-defined for `phrase/3`, **required for `phrase/2`** | **diverges**: EyeProlog raises `type_error(list, S0)` |
+| d) `S` is not a terminal-sequence | `type_error(terminal_sequence, S)` — implementation-defined | **diverges**: EyeProlog raises `type_error(list, S)` |
+
+**Open divergence.** EyeProlog performs both optional checks — which the draft
+permits, and which for `phrase/2` clause c it requires — but reports
+`type_error(list, Culprit)` where the 2023-08-14 draft specifies
+`type_error(terminal_sequence, Culprit)`. The draft is explicit that if a
+processor offers these errors, "their form and consequence must be the
+following", so the *form* is not left open even though performing the check is.
+
+This appears to track an earlier edition, in which these clauses were numbered
+8.18.1.3 g and h and specified `list`. The behaviour is deliberate and covered
+by a dedicated regression matrix, so changing the error term is a decision to
+take explicitly rather than a bug to patch silently. Until it is taken, this
+row is the one known Part 3 deviation.
+
+What the regression matrix does pin, independently of the error term: the same
+diagnostic across both arities, both sequence positions, atomic and compound
+non-lists, and improper lists at several depths; the culprit is the whole
+invalid argument, including an improper list, not just its tail; variables,
+proper lists, and partial lists are accepted; and for otherwise valid grammar
+bodies, validation precedes execution even when the grammar would fail or
+produce a side effect. The upstream phrase quads permit both checking and
+non-checking outcomes and so do not establish this consistency on their own.
+
+## Language concepts
+
+| Clause | Concept | Status |
+| --- | --- | --- |
+| 7.4.4 | grammar rules in Prolog text | **implemented** |
+| 7.5.1 | grammar-rule expansion during preparation | **implemented** |
+| 7.13.1 | terminals and non-terminals | **implemented** |
+| 7.13.2 | format of grammar rules | **implemented** |
+| 7.13.3 | semicontext (pushback) | **implemented** — `head, [Pushback] --> Body` |
+| 7.13.4 | non-terminal indicator `A//N` | **implemented** — accepted in module export lists |
+| 7.15 | executing clauses expanded from grammar rules | **implemented** |
+| 5.5.2 | predefined operators | **implemented** — `-->` is predeclared in both profiles; it is grammar syntax only in normal mode |
+
+`predicate_property/2` does not appear in the 2023-08-14 draft, so no Part 3
+predicate-property extension is claimed here. See `ISO-PART2.md` for the Part 2
+status of that predicate.
+
+## Executable evidence
+
+Grammar expansion, sequence validation, grammar-body callability, variable-body
+instantiation errors, and `phrase/3` steadfastness are under focused tests in
+`test/run-regression.mjs` and the conformance corpus. The live Neumerkel gate
+covers the upstream phrase quads.
+
+Changes intended to advance a formal Part 3 claim should update this ledger and
+the corresponding error cases rather than silently changing the compatibility
+profile.
+
+## See also
+
+- `ISO-PART2.md` — Part 2 (modules) status
+- `ISO-COMPLIANCE.md` — the Part 1 review that carries the release-facing claim
+- `NEUMERKEL-LIVE.md` — the live upstream gate

package/test/conformance/README.md

@@ -16,10 +16,11 @@ closes 7.9/Clause 9, and [ISO-PROCESSOR-REQUIREMENTS.md](ISO-PROCESSOR-REQUIREME
 decomposes the Clause 5 processor obligations.
 [ISO-CORRIGENDA-MATRIX.md](ISO-CORRIGENDA-MATRIX.md) gives every published
 Corrigenda amendment cluster an executable, editorial, or superseded
-disposition. [ISO-PART2-AMENDMENT-2013.md](ISO-PART2-AMENDMENT-2013.md) maps the
-2013 module-amendment requirements to executable evidence, while
-[ISO-PART2-PART3-SCOPE.md](ISO-PART2-PART3-SCOPE.md) records the broader
-normal-profile module/DCG compatibility boundary and known non-claims. Built-in rows may group closely related conditions only when the
+disposition. [ISO-PART2.md](ISO-PART2.md) and [ISO-PART3.md](ISO-PART3.md) record,
+directive by directive and predicate by predicate, what the normal profile
+implements of Part 2 (modules) and Part 3 (definite clause grammar rules),
+including the 2013 module-amendment evidence and the known gaps and deviations.
+Neither part carries a conformance claim. Built-in rows may group closely related conditions only when the
 row names every grouped condition and its executable evidence.
 The exit checklist is embedded in [ISO-COMPLIANCE.md](ISO-COMPLIANCE.md). [WG17-SYNTAX-STATUS.md](WG17-SYNTAX-STATUS.md) records the
 complete one-to-one trace for the vendored active upstream WG17 syntax cases.

package/the-art-of-eyeprolog.md

@@ -5883,7 +5883,9 @@ Variables, proper lists, and partial lists pass these checks. Validation
 precedes grammar execution; an otherwise valid failing grammar does not
 suppress the diagnostic. Dedicated regressions enforce this policy separately
 from the portable quads, which accept both checking and non-checking outcomes. See
-[`ISO-PART2-PART3-SCOPE.md`](test/conformance/ISO-PART2-PART3-SCOPE.md).
+[`ISO-PART3.md`](test/conformance/ISO-PART3.md), which also records that the
+2023-08-14 working draft specifies `type_error(terminal_sequence, Culprit)` for
+this condition.
 
 #### A bidirectional expression grammar
 

package/test/conformance/ISO-PART2-AMENDMENT-2013.md

@@ -1,36 +0,0 @@
-# ISO/IEC 13211-2 module amendment (2013) coverage
-
-This ledger maps EyeProlog's normal module profile to the requirements clarified
-by the attached 2013 ISO/IEC 13211-2 amendment draft (WG17 N251). It is narrowly
-scoped to that amendment. It does **not** turn the broader ISO/IEC 13211-2:2000
-base document into a release-facing certification claim; unchanged Part 2
-facilities outside the amendment still need their own clause-by-clause review.
-
-Executable evidence lives in `test/run-iso-part2-amendment.mjs` and is included
-in both `npm test` and the conformance aggregate.
-
-| Amendment clause | Required behavior | EyeProlog behavior / evidence |
-| --- | --- | --- |
-| 6.2.4.1 | A `module(Name, Exports)` directive identifies a named module and its public predicate indicators. | `Program.defineModule()` records the named module and export map. The focused suite checks that public predicates import and private predicates remain module-local. |
-| 6.2.5 | A module body is a Prolog text beginning with its `module/2` directive and extending to the end of that text. | Files designated by `use_module/1-2` are accepted as module sources only when their first read term is `module/2`. A second `module/2` later in the same Prolog text is rejected rather than switching modules mid-text, while a distinct Prolog text may begin a distinct module body. |
-| 6.2.5.5 | `use_module(F, L)` selectively imports the predicates in `L` from the exports of the module defined by `F`. | `Program.importModule()` validates requested indicators against the source module's export map and installs only those imports. The focused suite verifies selective import. |
-| 6.2.5.6 | `use_module(F)` imports all exported predicates; the amendment also aligns the public-predicate effect of `ensure_loaded(F)` for a module source. | `use_module/1` imports the full export map. `ensure_loaded/1` now imports a module's public predicates while retaining idempotent source loading, including when the same module was already loaded for another caller. |
-| 6.2.5.7 | `meta_predicate/1` marks context-sensitive arguments; `:` arguments carry the current source/calling module. | Normal parsing accepts the amendment spelling `:- meta_predicate p(:).`. Colon-mode arguments are represented as an observable `Module:Goal` term, including when the argument is a variable. Numeric closure modes remain a separate compatibility extension. |
-| 6.4.4.3 | Imported metapredicates preserve the caller's module context for their meta-arguments. | The focused suite verifies both visible `Module:Goal` decomposition and execution of a caller-private predicate through a variable meta-argument. Explicit `Module:Goal` calls continue to set their stated module context. |
-
-## Operator boundary
-
-ISO/IEC 13211-2 adds `:` as the module-qualification operator relative to the
-Part 1 initial operator table. EyeProlog therefore predeclares `:` only in its
-normal module profile; `--iso-strict` no longer includes it in the Part 1
-initial table. Normal mode also predeclares `meta_predicate` as a directive
-operator so the amendment's source spelling is accepted, while the parenthesized
-`meta_predicate(...)` compatibility spelling remains valid.
-
-## Remaining Part 2 scope
-
-The amendment coverage above is executable and release-gated. EyeProlog still
-describes the overall Part 2 surface as a compatibility profile until the
-unchanged portions of ISO/IEC 13211-2:2000 - including its broader module
-interface and re-export model - have a complete processor/semantics ledger.
-See `ISO-PART2-PART3-SCOPE.md` for that release boundary.

package/test/conformance/ISO-PART2-PART3-SCOPE.md

@@ -1,71 +0,0 @@
-# ISO Part 2 and Part 3 compatibility scope
-
-EyeProlog's release-facing `--iso-strict` claim is deliberately limited to
-ISO/IEC 13211-1:1995 together with Technical Corrigenda 1:2007, 2:2012, and
-3:2017. This note records the separate status of the normal-profile facilities
-that overlap ISO/IEC 13211-2:2000 (modules) and ISO/IEC TS 13211-3:2025 (definite
-clause grammar rules). It is a scope ledger, not an independent certification.
-
-## Part 2 modules
-
-Normal mode implements a procedure-oriented module compatibility layer:
-`module/2`, `use_module/1-2`, `meta_predicate/1`, explicit `Module:Goal`
-qualification, exports/imports, nonterminal indicators, and module-aware meta
-calls are covered by the regression and conformance corpora.
-
-The requirements clarified by the 2013 ISO/IEC 13211-2 module amendment draft
-(WG17 N251) now have a dedicated executable ledger in
-`ISO-PART2-AMENDMENT-2013.md`: module/2 exports, selective and full imports, the
-module-source behavior of ensure_loaded/1, the amendment's meta_predicate
-directive spelling, and visible caller-module qualification of `:`
-meta-arguments. The focused runner is part of the release gate.
-
-This amendment coverage is intentionally narrower than a complete Part 2
-conformance claim. In particular, the Part 1 strict registry does not enable
-module directives or the Part 2 `:` operator, and the project does not infer
-full Part 2 coverage from interoperability with Scryer, Trealla, or Logtalk. A
-future complete Part 2 claim would require a clause-by-clause review of the
-unchanged ISO/IEC 13211-2:2000 module-interface and re-export facilities as well
-as the amendment.
-
-## Part 3 definite clause grammars
-
-Normal mode expands grammar rules to ordinary predicates and supports terminal
-sequences, sequencing, alternatives, semicontexts, embedded goals, cut,
-`call//1`, `phrase//1`, `phrase/2-3`, module-qualified nonterminals, and the
-implementation-dependent negation/if-then choices documented in the reference.
-`--iso-strict` leaves `-->/2` as ordinary Part 1 operator syntax and excludes
-Part 3 grammar expansion and `phrase/2-3` from the strict registry.
-
-EyeProlog elects to perform both implementation-defined terminal-sequence
-checks in ISO/IEC TS 13211-3:2025, 8.18.1.3 g and h. The checks are optional;
-when performed, their specified error type is `list`. EyeProlog consistently
-raises `type_error(list, Culprit)` for a non-list input to `phrase/2` or
-`phrase/3`, and for a non-list remainder to `phrase/3`. The culprit is the
-whole invalid argument, including an improper list, not just its tail.
-Variables, proper lists, and partial lists are accepted by these checks.
-For otherwise valid grammar bodies, validation precedes execution, even when
-the grammar would fail or produce a side effect.
-
-The upstream phrase quads permit both checking and non-checking outcomes and
-therefore do not establish this consistency. A dedicated regression matrix in
-`test/run-regression.mjs` requires the exact diagnostic across both arities,
-both sequence positions, atomic and compound non-lists, improper lists at
-several depths, and several grammar bodies. Positive cases protect variables,
-proper lists, and partial lists. These are policy checks, not a relaxation of
-the unmodified upstream corpus.
-
-The Part 3 implementation otherwise keeps sequence validation, grammar-body
-callability, variable-body instantiation errors, `phrase/3` steadfastness, and
-grammar expansion under focused executable tests. Changes intended to advance a
-formal Part 3 claim should update this ledger and the corresponding error cases
-rather than silently changing the compatibility profile.
-
-## Release boundary
-
-- Part 1 + Corrigenda 1-3: release-facing strict-core conformance target.
-- Part 2: 2013 amendment requirements release-gated; broader Part 2 remains a normal-mode compatibility profile, not a complete certification.
-- Part 3: normal-mode compatibility profile, tested but not certified complete.
-
-This separation keeps Part 1 conformance evidence independent of useful module
-and DCG extensions while making known Part 2/Part 3 scope limits visible.