]> dreyeck.freedombox.rocks Git - topic-maps.git/blobdiff - README.md
feat(ctm): support triple-quoted strings and four originals
[topic-maps.git] / README.md
index 0b32bd5e8d13e28f58faefa28317529fb6ace19b..cd0258875e12be3c46ccd9ac18a848cd3079cb70 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,11 +1,67 @@
-# Common Lisp Topic Maps — Slice 16A
+# Common Lisp Topic Maps — Slice 19D2
+
+Slice 19D2 adds the explicit **`topic-maps/ctm/xtm`** adapter for `%mergemap`
+with `http://psi.topicmaps.org/iso13250/xtm`. The existing resolver passes raw
+bytes to the qualified XTM reader; existing TMDM Map-content import transfers
+its result. The unchanged 1,519-byte original baseline matches end-to-end.
+CTM now has **205 PASS / 4 known FAIL / 64 NOT-RUN** with the adapter loaded;
+the separate XTM corpus has **6 PASS / 0 FAIL / 118 NOT-RUN**.
+See [XTM Mergemap: API, objects, diagnostics and reproduction](docs/slice-19d2-xtm-mergemap.md).
+
+
+Slice 19D1 adds **`topic-maps/xtm`**, an XTM 2.0 identity/`instanceOf` subset.
+Six unchanged XTM sources match their original CXTM baselines byte-for-byte;
+results are separate from the unchanged **204 PASS / 4 FAIL / 65 NOT-RUN** CTM
+contracts. No CTM XTM-Mergemap integration or full XTM conformance is claimed.
+See [the XTM API, model and reproduction guide](docs/slice-19d1-xtm-identity.md).
+
+
+Slice 19D0B qualifies local, versioned CXML/closure-common encoding corrections:
+**58 original and 88 additional XML checks PASS** in fresh offline SBCL 2.5.4.
+The required entry point is `topic-maps.xml:parse-octets` after offline source
+patch preparation; it enforces external-resource denial. Slice 19D1 uses that boundary for its independent XTM 2.0 identity reader. See [encoding qualification](docs/slice-19d0b-cxml-encoding.md).
+
+Slice 19D0 made pinned CXML sources available to ASDF through the Nix source
+environment. Its initial parser qualification failed on UTF-16 supplementary
+characters and invalid UTF-8; those historical failures are retained. See
+[CXML provisioning and qualification](docs/slice-19d0-cxml.md) for exact hashes,
+offline loading, external-entity policy, the failing probes and retained regression.
+
+Slice 19C adds `%include` with controlled resources, per-level Topic-II aliases,
+immediate-parent Document/Wildcard environments, Counter propagation and
+source-preserving Template import. Imported bodies execute in the caller's
+identity/Prefix environment while errors preserve definition and invocation
+sources. See [Reading CTM Include](docs/reading-ctm-include.md) and
+[Slice 19C validation](docs/slice-19c-validation.md).
+The registered corpus is **204 PASS, 4 FAIL, 65 NOT-RUN**. All twelve Include
+contracts execute: seven byte-equal positives, three intended rejections, two
+explicit normative/baseline mismatches. The two earlier DateTime FAILs remain.
+
+Slice 19B adds CTM `%mergemap` with the CTM notation and an explicit
+`:resource-resolver` on `deserialize-string` / `deserialize-file`. Resources are
+supplied as bytes by the caller, deserialized with independent environments,
+and transferred by Slice 19A's TMDM content import. No implicit file/network
+retrieval is provided (Include is added by Slice 19C). XTM Mergemap is added by the explicit Slice 19D2 adapter.
+See [Reading CTM Mergemap](docs/reading-ctm-mergemap.md) and
+[Slice 19B validation](docs/slice-19b-validation.md).
+The registered corpus now has **194 PASS, 2 known DateTime FAIL, 77 NOT-RUN**:
+four new byte-exact positive contracts and three intended negative rejections.
+
+Slice 19A adds `topic-maps.tmdm:import-map-content`: source-preserving copying
+of Topics, Associations and their children into a target Map, followed by the
+existing same-map identity and structural merging. Both original graphs remain
+unchanged on semantic rejection. The returned resolver tracks canonical target
+representatives. Source Map identifiers/reifier are excluded.
+See [Reading Map Content Import](docs/reading-map-content-import.md) for the API,
+object references and inspection forms, and [Slice 19A validation](docs/slice-19a-validation.md)
+for fresh offline execution evidence. This adds no CTM import contracts:
+**187 PASS, 2 known DateTime FAIL, 84 NOT-RUN** remain unchanged.
 
 A working ANSI Common Lisp reader for CTM identity/name syntax and
-unary/binary Associations, with same-map merging of Topics, Names, Associations
+Associations with one or more Roles, with same-map merging of Topics, Names, Associations
 and Roles, plus string/IRI-valued Occurrences, in a bounded TMDM model. HyperDoc remains a possible future client
 and is neither the codebase nor a dependency. Slice 4 adds a pure, independent
-CXTM canonicalizer for this model. Templates and cross-document merging remain
-outside the implementation. Slice 5 adds Occurrence items and replacement merging
+CXTM canonicalizer for this model. Controlled Include/Mergemap and Map content import are described above. Slice 5 adds Occurrence items and replacement merging
 without expanding Scope, Reification or Variants. Slice 6 adds document-local
 prefixes, QName resolution and explicit datatype locators on quoted Occurrence
 values. Unknown datatypes retain their lexical values; Date timezone CXTM rules
@@ -29,9 +85,36 @@ supersets, canonical merge handles and pure CXTM output. Slice 15 adds per-docum
 Wildcards and recursive Embedded Topics through the shared Topic reference reader.
 Slice 16A adds general Item Identifiers for all seven existing information-item
 kinds, including metadata-preserving replacement merges and pure CXTM output.
-Reification remains outside this slice.
+Slice 16B adds same-map Reification, full merge cascades, atomic semantic
+preflight and all six CTM Reifier attachment positions.
+Slice 17A removes the two-Role CTM limit, preserving the existing model and
+canonicalizer. Slice 17B adds `isa`/`ako` using ordinary Associations and protects
+the distinct Core Subjects defined by TMDM 2006 §7. Atomic merge preflight uses
+the existing disposable TMDM graph. No inference engine is introduced.
+
+Slice 18 adds grammar-checked Templates, contextual positional arguments,
+global/Tail/nested Invocations, invocation-local Wildcards and canonical handles
+through existing model operations. Seven explicitly documented grammar contracts
+remain open; no extra TMDM item kind or Lisp evaluation is introduced.
+
+Start with [CTM Templates and Invocations](docs/reading-ctm-templates.md) for
+representation, diagnostics, open grammar cases and executable inspection forms.
+See [Slice 18 validation](docs/slice-18-validation.md) for the full offline run,
+57 additional byte-exact original contracts and ten specific rejection contracts.
+
+Start with [isa/ako and Core Subject Consistency](docs/reading-type-relationships.md)
+for the exact vocabulary, object relations, normative distinctions and inspection.
+See [Slice 17B validation](docs/slice-17b-validation.md) for the complete offline
+regression and thirteen new original byte-exact comparisons.
+
+Start with [Associations with Arbitrarily Many Roles](docs/reading-association-arity.md)
+for the actual seven-Topic/three-Role example and executable inspection forms.
+See [Slice 17A validation](docs/slice-17a-validation.md) for the full offline run
+and the single new byte-exact original contract.
 
-Start with [General Item Identifiers](docs/reading-item-identifiers.md) for the
+Start with [Reification](docs/reading-reification.md) for actual Reifier/Reified
+objects, normative clauses, cascade handling and inspection forms.
+See [General Item Identifiers](docs/reading-item-identifiers.md) for the
 uniform API, retained handles, exact boundaries and executable inspection forms.
 
 Systems: `topic-maps` (the retained foundation), `topic-maps/tests`,
@@ -40,7 +123,12 @@ Systems: `topic-maps` (the retained foundation), `topic-maps/tests`,
 `topic-maps/cxtm/tests`, `topic-maps/ctm/occurrence-tests` and `topic-maps/ctm/prefix-tests` and `topic-maps/ctm/integer-tests`, plus `topic-maps/ctm/decimal-tests` and `topic-maps/ctm/date-tests` and `topic-maps/ctm/datetime-tests` and `topic-maps/ctm/timezone-tests`, `topic-maps/ctm/typed-name-tests` and `topic-maps/ctm/scope-tests`, plus `topic-maps/ctm/variant-tests` and `topic-maps/ctm/reference-tests`.
 The core reader/model uses ANSI Common Lisp; the foundation/tooling uses
 ASDF/UIOP and Python's standard library. No Quicklisp packages are required.
-`topic-maps/tmdm/identifier-tests` adds the general identifier regression suite.
+`topic-maps/tmdm/identifier-tests` and `topic-maps/tmdm/reification-tests` add the
+general identifier and Reification regression suites.
+`topic-maps/ctm/association-arity-tests` adds n-ary syntax, merge/handle checks
+and the original `association-duplicate-role.ctm` comparison.
+`topic-maps/ctm/type-relationship-tests` adds Core consistency, atomic failure
+and isa/ako model/reference-graph checks.
 
 Start with [Reading Topic References](docs/reading-topic-references.md) for Wildcard
 IRIs/counters, recursive Embedded Topics and actual object relationships.
@@ -140,10 +228,10 @@ CXTM baselines only under `ctm/baseline`. Auxiliary files are reported separatel
 ## Current validation and historical foundation
 
 The complete pinned corpus remains unchanged: 231 valid CTM inputs, 42 invalid
-inputs, 231 CXTM baselines and 22 CTM auxiliary files. Eighty-three selected positive
-cases pass actual CXTM byte comparisons. Ten specific rejection contracts pass.
+inputs, 231 CXTM baselines and 22 CTM auxiliary files. One hundred sixty-five selected positive
+cases pass actual CXTM byte comparisons. Twenty-two specific rejection contracts pass.
 Two executed DateTime contracts remain FAIL because of documented normative
-baseline discrepancies; 178 contracts remain NOT-RUN. A green regression run
+baseline discrepancies; 84 contracts remain NOT-RUN. A green regression run
 preserves those two FAILs and never changes an upstream baseline. Unsupported
 constructs and I/O errors cannot count as the required CTM rejection.
 
@@ -151,7 +239,8 @@ The full launcher runs the retained 54 foundation checks, two Python integrity
 fixtures, 123 retained identity checks, 646 merge checks, 657 Association checks,
 imported-report validation and selected baseline
 property evidence, 445 retained CXTM checks, 1,101 Occurrence checks, 150 prefix/datatype checks, 665 integer checks, 715 Decimal checks, 1,806 Date checks, 217 DateTime checks, 1,944 timezone checks, 106 typed-name checks, 293 Scope checks, 324 Variant checks and 238 Topic Reference checks, plus
-16,294 independent Unicode NFC oracle
+244 general Item Identifier checks, 236 Reification checks, 337 n-ary Association
+checks, 1,016 Core Subject/type-relationship checks, 297 Template checks and 16,294 independent Unicode NFC oracle
 comparisons. The oracle needs Python UCD 15.0 or 15.1 (tables use UCD 15.1.0).
 A report path also produces `<path>.semantics.json` with
 separate model observations, plus `<path>.merging.json`, `<path>.associations.json`
@@ -166,12 +255,18 @@ models, 45 independent lexical/canonical probes and two executed baseline
 discrepancies. `<path>.timezones.json` adds exact UTC, fraction and model-purity
 probes, including every one of the 1681 permitted signed offset minutes.
 The merge checks include 128 graph/order variants with an independent reachability
-oracle. Reports are deterministic across the tested SBCL versions and checkout
-relocation. `<path>.typed-names.json` records Name value/Parent/Type relations;
+oracle. Earlier slices recorded version/relocation comparisons; Slice 17A uses
+the existing single-runtime environment. `<path>.typed-names.json` records Name value/Parent/Type relations;
 `<path>.scopes.json` records Scope object relations and an ordering witness.
 `<path>.variants.json` records Variant/Parent/Scope observations and XML ordering.
 `<path>.references.json` records the new source/counter/model observations.
-See [Slice 15 validation](docs/slice-15-validation.md) for current evidence.
+`<path>.identifiers.json` and `<path>.reification.json` retain their model evidence;
+`<path>.arity.json` adds actual Role references and twelve canonical XML witnesses.
+`<path>.relationships.json` records the thirteen original reference graphs and
+atomic Core Subject conflict observations.
+`<path>.templates.json` records the 57 model observations and ten specific
+rejections, including original positions and invocation contexts.
+See [Slice 19B validation](docs/slice-19b-validation.md) for current evidence.
 [Slice 12A validation](docs/slice-12a-validation.md) records explicit Name types.
 [Slice 11 validation](docs/slice-11-validation.md) preserves the prior timezone evidence.
 [Slice 10 validation](docs/slice-10-validation.md) preserves the earlier DateTime baseline.