]> dreyeck.freedombox.rocks Git - topic-maps.git/blobdiff - README.md
feat(ctm): read associations and roles with merge-safe topic references
[topic-maps.git] / README.md
index 08a5dad7e4ef9fd5382f5b061e260b976edef28a..1bbb48e3039c91fea62d251104f97940938db373 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,14 +1,30 @@
-# Common Lisp Topic Maps — Slice 0
-
-An independent foundation for implementing ISO/IEC 13250-6:2010 (CTM) in
-Common Lisp. **There is no CTM reader, TMDM model or CXTM canonicalizer yet.**
-HyperDoc may become a client later; it is neither the codebase nor a dependency.
-
-Only `topic-maps` (the actual test foundation) and `topic-maps/tests` exist.
-The future `topic-maps/tmdm`, `topic-maps/ctm` and `topic-maps/cxtm` systems are
-not defined. Loading the foundation does not pretend they are available.
-Runtime dependencies: Common Lisp, ASDF/UIOP. Integrity/acquisition tooling
-uses Python 3's standard library and Git. No Quicklisp packages are required.
+# Common Lisp Topic Maps — Slice 3
+
+A working ANSI Common Lisp reader for CTM identity/default-name syntax and
+unary/binary Associations, with same-map merging of Topics, Names, Associations
+and Roles in a bounded TMDM model. HyperDoc remains a possible future client
+and is neither the codebase nor a dependency. There is no CXTM canonicalizer,
+Template implementation or cross-document merge engine.
+
+Systems: `topic-maps` (the retained foundation), `topic-maps/tests`,
+`topic-maps/tmdm`, `topic-maps/ctm`, `topic-maps/ctm/tests` and
+`topic-maps/ctm/merging-tests` and `topic-maps/ctm/association-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.
+
+Start with [Reading the First CTM Associations](docs/reading-first-ctm-associations.md)
+for actual Association/Role items, late Topic merges and current subset boundaries.
+[Reading Topic Identity and Merging](docs/reading-topic-merging.md)
+for the current API, reference replacement, identifier tails and exact subset
+boundaries. See [Reading the First Five CTM Documents](docs/reading-first-five-ctm-documents.md)
+for original sources, actual objects, normative clauses, baseline evidence and
+copy-pasteable DESCRIBE forms. [API and boundaries](docs/slice-1-api-and-boundaries.md)
+document the accepted Slice 1 baseline; the Slice 2 document supersedes its
+statements about absent identity tails, merging and immutable Name references.
+The Slice 3 document supersedes historical statements about absent Associations/Roles.
+
+The pinned suite targets the **CTM draft dated 2010-03-31**. Passing it alone
+does not establish full ISO/IEC 13250-6:2010 conformity.
 
 ## Load and inspect
 
@@ -19,12 +35,16 @@ In a new Common Lisp process, with this checkout selected:
 (asdf:initialize-source-registry
  '(:source-registry :ignore-inherited-configuration))
 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
+(asdf:load-system "topic-maps/ctm")
 (asdf:load-system "topic-maps")
 (defparameter *corpus* (topic-maps.test-foundation:discover-corpus))
 (topic-maps.test-foundation:summarize-corpus *corpus*)
 (topic-maps.test-foundation:select-cases *corpus* :category :invalid)
 (topic-maps.test-foundation:select-cases *corpus* :id "ctm/in/simple.ctm")
 (asdf:test-system "topic-maps/tests")
+(asdf:test-system "topic-maps/ctm/tests")
+(asdf:test-system "topic-maps/ctm/merging-tests")
+(asdf:test-system "topic-maps/ctm/association-tests")
 (topic-maps.test-foundation:write-validation-report
  *corpus* #p"/tmp/topic-maps-inventory.json")
 ```
@@ -63,21 +83,32 @@ contents and verifies every file. Verification is offline. Valid CTM inputs
 are selected only under `ctm/in`, invalid ones only under `ctm/invalid`, and
 CXTM baselines only under `ctm/baseline`. Auxiliary files are reported separately.
 
-## Recorded result and authority
-
-The pinned corpus has 231 valid CTM inputs, 42 invalid inputs, 231 CXTM baselines
-and 22 auxiliary files in its CTM subtree, with no unmatched/missing baseline.
-All 273 imported CTM cases are **NOT-RUN**; none passes a nonexistent reader.
-Infrastructure fixtures exercise PASS, FAIL, UNSUPPORTED and NOT-RUN separately.
-
-The upstream CTM suite targets the **draft dated 2010-03-31**. Passing that suite
-alone would not establish full ISO/IEC 13250-6:2010 conformity. Published ISO
-standards are normative; this corpus and Ontopia are independent evidence.
-
-See [inventory and provenance](docs/inventory.md),
-[coverage and the first five proposed Slice 1 cases](docs/coverage.md),
-[architecture and Document-IRI policy](docs/architecture.md), and
-[execution evidence](docs/validation.md).
-The [machine-readable report](reports/validation.json) records actual imported
-case contracts and the passing infrastructure check names, without claiming
-CTM implementation. Nothing from Slice 1 is automatically started.
+## 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. Twenty-four selected semantic
+cases pass; their imported canonical contracts remain NOT-RUN. Only
+`ctm/invalid/prefix-undefined.ctm` is PASS under its CTM rejection contract;
+272 imported contracts remain NOT-RUN. Unsupported constructs and I/O errors
+cannot count as that required rejection.
+
+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. A report path also produces `<path>.semantics.json` with
+separate model observations, plus `<path>.merging.json` and `<path>.associations.json`.
+The merge checks include 128 graph/order variants with an independent reachability
+oracle. Reports are deterministic across the tested SBCL versions and checkout
+relocation. See [Slice 3 validation](docs/slice-3-validation.md),
+[imported contracts](reports/slice-1/validation.json) and
+[semantic observations](reports/slice-1/semantics.json).
+
+[Slice 0 inventory](docs/inventory.md), [architecture](docs/architecture.md),
+[coverage](docs/coverage.md) and [validation](docs/validation.md) remain historical
+foundation records. Their original report/logs are preserved. Their statements
+about absent reader/model systems describe Slice 0, not the current branch.
+Slice 1 is built from `9c83db34eb1ba8091b004433f088056717dbaa7e` on
+`codex/ctm-slice-1`. Slice 2 starts from the accepted Slice 1a commit
+`fb60afd548d679d83fd8ec76bc5ff384c1e23e5f` on `codex/ctm-slice-2`.
+Slice 3 starts from accepted `66664dbff6275d60dab1bc6a232fa70f7b916b8c` on
+`codex/ctm-slice-3`. Await review before continuing to the next slice.