elementary-assertions 1.0.1

package/docs/DEV_TOOLING.md

@@ -0,0 +1,98 @@
+# Developer Tooling (Non-Public)
+
+This document describes repository developer tooling only.  
+It is not part of the npm package contract and can change between releases.
+
+## Scope
+
+These scripts are intended for internal quality analysis and regression triage:
+
+- `npm run dev:check`
+- `npm run dev:report:metrics`
+- `npm run dev:report:hotspots`
+- `npm run dev:report:maturity`
+- `npm run dev:diagnose:wiki-upstream`
+- `npm run dev:diagnose:wti-wiring`
+- `npm run dev:diagnose:coverage-audit`
+- `npm run dev:reports`
+
+They read from committed artifact references under `test/artifacts/*/result-reference/` and emit JSON reports to stdout.
+
+`npm run dev:reports` is an aggregate maintainer command that executes:
+- metrics
+- hotspots
+- maturity
+- wikipedia-upstream diagnostics (`dev:diagnose:wiki-upstream`)
+- WTI wiring diagnostics
+- coverage-audit diagnostics
+
+`npm run dev:check` runs strict validation (`validateElementaryAssertions(..., { strict: true })`) across:
+- a single file via `--in <path>`, or
+- all artifact golden YAML files under `test/artifacts/` (default).
+
+## Common script options
+
+Most `dev:*` scripts support:
+- `--seed <name>` to run on one artifact seed only
+- `--artifacts-root <path>` to override the default `test/artifacts` root
+
+`npm run dev:check` additionally supports:
+- `--in <path>` to validate one explicit document instead of artifact references
+
+`npm run dev:diagnose:wiki-upstream` additionally supports:
+- `--upstream <path>` (JSON/YAML) to correlate uncovered mentions between EA output and accepted upstream dependency endpoints
+
+Wikipedia-upstream diagnostics report depth:
+- upstream wikipedia field-path inventory by object family
+- categorized missing-field samples (`missing_upstream_acceptance` vs `present_upstream_dropped_downstream`)
+- stratified representative samples by role class and mention kind
+
+Maintainer triage scope:
+- upstream diagnostics include bounded field-inventory examples and predicate-level coverage summaries
+- `dev:check` is a maintainer triage tool and should emit invariant-family failure context when strict checks fail
+
+`npm run dev:diagnose:wiki-upstream` report contracts used for maintainer triage:
+- `correlation.upstream_wikipedia_field_inventory.object_families[*].field_paths[*]` includes:
+  - `path`
+  - `count`
+  - bounded `example`
+  - deterministic `example_source_id`
+- `correlation.predicate_wikipedia_coverage_summary` includes:
+  - total predicates considered
+  - predicates with wikipedia signal
+  - predicates missing wikipedia signal
+  - cause split:
+    - accepted predicate but missing wikipedia payload
+    - predicate not present/eligible in accepted relations
+
+`npm run dev:check` failure output contract for strict mode:
+- emits deterministic `invariant_family` grouping per failing code family
+- includes minimal reproducer pointer (`seed_id`, `segment_id`, `mention_id`/`assertion_id`)
+- includes deterministic `recommended_next_command` for follow-up diagnostics
+
+`npm run dev:diagnose:wti-wiring` additionally supports:
+- `--runtime-probe` to enforce runtime wiring checks
+- `--wti-endpoint <url>` (required in runtime probe mode)
+- `--wti-timeout-ms <ms>` (optional override for runtime probe health timeout)
+
+WTI wiring diagnostics report depth:
+- non-probe mode includes explicit wiring attribution:
+  - endpoint configured / mandatory endpoint behavior active
+  - per-step requested vs observed signal families
+- runtime probe remains authoritative for wiring truth and fail-fast behavior
+
+Runtime probe mode intentionally fails on wiring-contract violations (for example missing endpoint or no positive pass-through signals).
+
+Fragment hotspot diagnostics report depth:
+- primary lens: clause-local lexical host + evidence containment
+- secondary lens (triage-only): segment-level host availability and containment
+
+## Contract boundary
+
+- Public/stable interfaces remain:
+  - `require("elementary-assertions")`
+  - `require("elementary-assertions/validate")`
+  - `require("elementary-assertions/render")`
+  - `require("elementary-assertions/tools")`
+  - `require("elementary-assertions/schema")`
+- `npm run dev:*` scripts are non-public workflow tooling and are not a compatibility guarantee.

package/docs/NPM_RELEASE.md

@@ -0,0 +1,177 @@
+# NPM_RELEASE.md
+
+This document defines the release flow for `elementary-assertions`.
+
+Current distribution status (until npmjs publish is executed): consumers install as a Git dependency pinned to a tag (or commit).
+After npmjs publication: publish to npmjs while keeping Git-tag installs supported.
+`files` is used to keep both Git installs and npm tarballs deterministic.
+
+Examples (consumer `package.json`):
+
+- SSH:
+  - `"elementary-assertions": "git+ssh://git@github.com:svenschaefer/elementary-assertions.git#v1.2.3"`
+- HTTPS:
+  - `"elementary-assertions": "git+https://github.com/svenschaefer/elementary-assertions.git#v1.2.3"`
+
+Consumers MUST pin to tags or commits, not branches.
+
+## Core rule
+
+A release is defined by:
+- version bump in `package.json`
+- a commit on `main`
+- an annotated Git tag `vX.Y.Z` pointing at that commit
+
+## Packaging rule for Git dependencies
+
+Even though installs come from Git, the repository MUST remain a valid Node package.
+Golden baseline freeze metadata is maintained in `test/artifacts/README.md`.
+
+- `npm pack --dry-run` MUST succeed.
+- `package.json` `files` is the primary packlist control.
+- `.npmignore` is an additional safeguard for local non-package files.
+
+## 0) Preconditions
+
+- Working tree clean.
+- `npm test` passes.
+- If `runElementaryAssertions` is used in smoke tests, ensure any required `wikipedia-title-index` endpoint is reachable.
+
+## 1) Prepare release branch
+
+```powershell
+git checkout main
+git pull
+git checkout -b release/vX.Y.Z
+```
+
+## 2) Implement + test
+
+* Make the change.
+* Add/update regression tests.
+* Run:
+
+```powershell
+npm test
+```
+
+## 3) Bump version (no auto-tag)
+
+```powershell
+npm version X.Y.Z --no-git-tag-version
+```
+
+If a lockfile exists and changes, keep it consistent with your npm version.
+
+## 4) Pack sanity
+
+```powershell
+npm pack --dry-run
+```
+
+Optional: build the tarball locally (not uploaded anywhere):
+
+```powershell
+npm pack
+```
+
+Cleanup after local pack steps:
+
+```powershell
+Remove-Item -Force .\elementary-assertions-*.tgz
+```
+
+## 5) Smoke install checks (pre-tag)
+
+Create a clean workspace and install from the commit hash you intend to tag.
+Use the shared smoke script so API/CLI checks and render parity are enforced together.
+The smoke script verifies parity for `txt/compact`, `md/table`, and `md/meaning`.
+
+Smoke workspace rule:
+- Use `C:\code\elementary-assertions-smoke-test\`.
+- Create one folder per clean install.
+- Folder name MUST include the target version and the reason for the install (for example `v1.2.3-pretag-smoke-20260214-113000`).
+
+```powershell
+$SmokeRoot = "C:\code\elementary-assertions-smoke-test\vX.Y.Z-pretag-smoke-$(Get-Date -Format yyyyMMdd-HHmmss)"
+New-Item -ItemType Directory -Path $SmokeRoot -Force | Out-Null
+Set-Location $SmokeRoot
+npm init -y | Out-Null
+
+# Replace <COMMIT> with the commit you intend to tag
+npm install "git+ssh://git@github.com:svenschaefer/elementary-assertions.git#<COMMIT>"
+
+node C:\code\elementary-assertions\scripts\release-smoke-check.js --repo-root C:\code\elementary-assertions --smoke-root $SmokeRoot --out-root (Join-Path $SmokeRoot "rendered")
+npm ls elementary-assertions
+```
+
+If the smoke test exercises `runElementaryAssertions`, also ensure the environment provides whatever endpoint configuration your CLI/tooling expects for `wikipedia-title-index`.
+
+## 6) Commit + merge to main
+
+For release commits, prefer explicit staging paths to avoid unintended additions, for example:
+`git add src docs test scripts package.json README.md CHANGELOG.md`.
+
+```powershell
+Set-Location C:\code\elementary-assertions
+git add src docs test scripts package.json README.md CHANGELOG.md
+git commit -m "release: vX.Y.Z"
+git push -u origin release/vX.Y.Z
+```
+
+Merge the release branch to `main` (PR merge or fast-forward merge), then:
+
+```powershell
+git checkout main
+git pull
+git merge --ff-only release/vX.Y.Z
+git push origin main
+```
+
+## 7) Tag + push
+
+Tag only after the release commit is on `main`:
+
+```powershell
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+## 8) Post-tag verification (install from tag)
+
+```powershell
+$SmokeRoot = "C:\code\elementary-assertions-smoke-test\vX.Y.Z-posttag-smoke-$(Get-Date -Format yyyyMMdd-HHmmss)"
+New-Item -ItemType Directory -Path $SmokeRoot -Force | Out-Null
+Set-Location $SmokeRoot
+npm init -y | Out-Null
+
+npm install "git+ssh://git@github.com:svenschaefer/elementary-assertions.git#vX.Y.Z"
+node C:\code\elementary-assertions\scripts\release-smoke-check.js --repo-root C:\code\elementary-assertions --smoke-root $SmokeRoot --out-root (Join-Path $SmokeRoot "rendered")
+npm ls elementary-assertions
+```
+
+## 9) npmjs publication step (`1.0.0+` only)
+
+When shipping `1.0.0` (or later) to npmjs:
+
+- Ensure `package.json` is publishable (`"private": false`).
+- Keep `license`, `files`, and `exports` consistent with package contract tests.
+- Publish from the release commit already tagged on `main`:
+
+```powershell
+npm publish --access public
+npm view elementary-assertions version
+npm view elementary-assertions dist-tags.latest
+```
+
+- Run a clean-install smoke check from npmjs package after publish (same smoke-root naming convention).
+
+## Failure rule
+
+If anything is wrong after tagging, do not move or delete the tag.
+Ship a new patch version with a new tag.
+
+## Release notes
+
+Create/update release notes using:
+- `docs/RELEASE_NOTES_TEMPLATE.md`

package/docs/OPERATIONAL.md

@@ -0,0 +1,159 @@
+# elementary-assertions - Operational Guide
+
+This document describes operational usage in the npm package context:
+- CLI commands
+- file I/O behavior
+- service requirements (WTI)
+- rendering defaults
+- determinism rules
+- repository-layout convenience options (seed-id, artifacts-root)
+
+The authoritative interface remains the core library API. Tooling is a consumer layer and is view-only.
+
+## Runtime dependencies
+
+Upstream linguistic pipeline (`linguistic-enricher`)  
+The default run path executes `linguistic-enricher` up to accepted relations (typically `relations_extracted`).
+
+Wikipedia Title Index service (WTI)  
+A WTI endpoint is required for the default run path (`run --text` / `run --in`).
+
+- the endpoint is passed to the upstream pipeline as `services["wikipedia-title-index"].endpoint`
+- a fail-fast `GET /health` check is performed before execution
+- positive upstream WTI evidence is required after pipeline execution (endpoint health alone is insufficient)
+- elementary-assertions performs no Wikipedia lookups itself
+- all wiki title signals are consumed as upstream evidence
+
+Endpoint source precedence (CLI):
+1. `--wti-endpoint`
+2. environment `WIKIPEDIA_TITLE_INDEX_ENDPOINT`
+
+If the endpoint is missing or blank, the CLI fails explicitly.
+
+WTI health-check contract (default run path):
+- Request: `GET /health`
+- Success: HTTP `200` only
+- Timeout: `2000` ms default
+- Retries: none (fail-fast)
+- Auth headers: none by default
+
+## CLI
+
+The CLI is a thin wrapper around the library plus tooling modules.
+CLI file-origin inputs preserve provenance metadata in output `sources.inputs[]`:
+- `--in` -> `artifact: "seed.txt"` with `origin.kind: "file"`
+- `--relations` -> `artifact: "seed.relations.yaml"` with `origin.kind: "file"`
+
+### Commands
+
+- `run` - produce `elementary_assertions` output from text or file input
+- `run` also supports offline/replay from relations input (`--relations`)
+- `validate` - schema + integrity + determinism checks
+- `render` - view-only rendering (txt or md) with layouts
+
+Examples:
+
+```bash
+npx elementary-assertions run --text "A webshop is an online store." --wti-endpoint http://localhost:3000 --wti-timeout-ms 2000 --out out.yaml
+npx elementary-assertions run --in input.txt --wti-endpoint http://localhost:3000 --out out.yaml
+npx elementary-assertions run --relations relations.yaml --out out.yaml
+npx elementary-assertions validate --in out.yaml
+npx elementary-assertions render --in out.yaml --format md --layout table --out out.md
+```
+
+### Generic I/O flags (preferred)
+
+Run:
+- exactly one of `--text <string>`, `--in <path>`, or `--relations <path>` is required; providing multiple is an explicit error, and providing none is an explicit error
+- `--out <path>` (optional, defaults to stdout)
+- `--timeout-ms <ms>` (optional)
+- `--wti-endpoint <url>` (required unless env provides it for `--text` / `--in`; not required for `--relations`)
+- `--wti-timeout-ms <ms>` (optional, default: 2000)
+
+Validate:
+- `--in <path>`
+
+Render:
+- `--in <path>`
+- `--out <path>` (optional, defaults to stdout)
+- `--format <txt|md>`
+- `--layout <compact|readable|table|meaning>`
+- `--segments <true|false>`
+- `--mentions <true|false>`
+- `--coverage <true|false>`
+- `--debug-ids <true|false>`
+- `--normalize-determiners <true|false>` (default: true)
+- `--render-uncovered-delta <true|false>` (default: false)
+
+Boolean flag parsing is strict:
+- accepted lexical forms: `true|false` (case-insensitive)
+- internal normalization target: lowercase (`true` or `false`)
+- rejected forms: `1/0`, `yes/no`, and bare flags without explicit values
+
+### Validation error contract
+
+- `elementary-assertions/validate` throws `ValidationError` for contract violations.
+- `ValidationError.code` is stable and intended for consumer branching.
+- Consumers should branch on `err.code`, not on free-text message matching.
+
+## Repository layout convenience (optional)
+
+If you operate within a repo that follows the conventional seed layout, the CLI may offer convenience flags:
+
+- `--seed-id <id>`
+- `--artifacts-root <path>`
+
+Conventional paths:
+- input: `artifacts/<seed-id>/seed/seed.txt`
+- output: `artifacts/<seed-id>/seed/seed.elementary-assertions.yaml`
+
+These flags are convenience helpers only. They are not required for generic package usage.
+
+## Rendering
+
+The renderer is view-only. It does not modify extraction results.
+
+Layouts:
+- `compact` - one-line assertions
+- `readable` - multi-line blocks
+- `table` - Markdown-safe table; includes inline evidence
+- `meaning` - grouped semantic display for readability only (non-normative, view-only)
+
+Renderer contract-lock scope:
+- Contract-locked by parity tests: `txt/compact`, `md/table`, `md/meaning`.
+- Other layout/format combinations are best-effort and may evolve.
+- Release smoke currently verifies install-time wiring for: `txt/compact`, `md/table`, `md/meaning`.
+
+Renderer integrity validation (before emitting output):
+- tokens must exist for all mentions
+- mentions must exist for all assertions
+- evidence references must resolve
+- coverage references must resolve
+
+Rendered files are not specifications and carry no authoritative semantics.
+
+## Determinism rules (operational)
+
+Deterministic ordering rules are enforced by core + validation tooling.
+Scope:
+- `runFromRelations(...)`: byte-stable for identical input and options within the same `elementary-assertions` version.
+- `run` (upstream-running path): byte-stable only with pinned dependency versions (`elementary-assertions` and `linguistic-enricher`) and stable WTI service state/behavior for identical requests.
+
+- Mention token order: by `token.i`
+- Mention order: `(segment_id, span.start, span.end, kind, id)`
+- Assertion order: `(segment_id, predicate head token.i, id)`
+- View slot print order (renderer projection only): `actor`, `theme`, `attr`, `topic`, `location`, `other`
+- Mention text reconstruction: single-space join of `token.surface`
+- Segment text reconstruction: exact `canonical_text` slicing by segment span
+- Identical input + identical flags produce byte-stable output within the determinism scope above
+
+## Non-goals (operational restatement)
+
+Tooling and core MUST NOT:
+- normalize into high-level semantic frames
+- perform concept identity mapping
+- convert to normative keywords
+- invent missing roles or attachments
+- use model calls or probabilistic filling
+
+This package is the first formal meaning layer, not final semantic normalization.

package/docs/RELEASE_NOTES_TEMPLATE.md

@@ -0,0 +1,37 @@
+# RELEASE_NOTES_TEMPLATE.md
+
+Use this template for each release note entry.
+
+## Release
+
+- Version: `vX.Y.Z`
+- Date: `YYYY-MM-DD`
+- Release commit: `<commit-sha>`
+- Tag: `vX.Y.Z`
+
+## CI Evidence
+
+- Workflow: `CI`
+- Run id: `<github-actions-run-id>`
+- Result: `success|failure`
+
+## Smoke Evidence
+
+- Pre-tag smoke root: `C:\code\elementary-assertions-smoke-test\vX.Y.Z-pretag-smoke-<timestamp>`
+- Post-tag smoke root: `C:\code\elementary-assertions-smoke-test\vX.Y.Z-posttag-smoke-<timestamp>`
+- Pre-tag rendered root: `...\rendered`
+- Post-tag rendered root: `...\rendered`
+
+## Contract Notes
+
+- API surface check summary:
+- CLI help check summary:
+- Render parity check summary:
+
+## Changes Summary
+
+- Added:
+- Changed:
+- Fixed:
+- Removed:
+

package/docs/REPO_WORKFLOWS.md

@@ -0,0 +1,48 @@
+# Repository Workflow Policies
+
+This document defines repository workflow policies. These policies are not part of the npm package contract.
+
+## Timestamp invariants (repository workflow only)
+
+When workflow automation writes rendered artifacts next to the YAML output, enforce:
+- `seed.elementary-assertions.md` newer than `seed.elementary-assertions.yaml`
+- `seed.elementary-assertions.meaning.md` newer than `seed.elementary-assertions.yaml`
+- `seed.elementary-assertions.txt` newer than `seed.elementary-assertions.yaml`
+
+These constraints apply to repository workflow only and do not define runtime behavior of `elementary-assertions` as a package.
+
+## Performance baseline (manual repo workflow)
+
+Use the benchmark helper to keep a coarse local baseline for `runFromRelations` performance:
+
+```powershell
+npm run benchmark:core
+```
+
+Optional iterations override:
+
+```powershell
+npm run benchmark:core -- 1000
+```
+
+Optional dense scenario override:
+
+```powershell
+npm run benchmark:core -- 1000 dense
+```
+
+This benchmark is advisory for repo workflow only (trend watching) and is not a package contract gate.
+
+## CI gates (repo workflow)
+
+Current CI workflow gates on:
+- `npm install`
+- `npm test`
+- dev report script execution:
+  - `npm run dev:report:metrics`
+  - `npm run dev:report:hotspots`
+  - `npm run dev:report:maturity`
+- `npm pack --dry-run`
+- packed-tarball clean-install smoke check via `scripts/release-smoke-check.js`
+
+These are repository quality gates and release hygiene checks, not package runtime contract.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "elementary-assertions",
+  "version": "1.0.1",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./validate": "./src/validate/index.js",
+    "./render": "./src/render/index.js",
+    "./tools": "./src/tools/index.js",
+    "./schema": "./src/schema/seed.elementary-assertions.schema.json"
+  },
+  "bin": {
+    "elementary-assertions": "bin/elementary-assertions.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:unit": "node --test \"test/unit/**/*.test.js\"",
+    "test:integration": "node --test \"test/integration/**/*.test.js\"",
+    "benchmark:core": "node scripts/benchmark-run-from-relations.js",
+    "dev:check": "node scripts/dev-check.js",
+    "dev:report:metrics": "node scripts/dev-report-metrics.js",
+    "dev:report:hotspots": "node scripts/dev-report-fragment-hotspots.js",
+    "dev:report:maturity": "node scripts/dev-report-maturity.js",
+    "dev:diagnose:wiki-upstream": "node scripts/dev-diagnose-wiki-upstream.js",
+    "dev:diagnose:wti-wiring": "node scripts/dev-diagnose-wti-wiring.js",
+    "dev:diagnose:coverage-audit": "node scripts/dev-diagnose-coverage-audit.js",
+    "dev:reports": "node scripts/dev-reports.js"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.1",
+    "linguistic-enricher": "1.1.35"
+  }
+}

package/src/core/accepted-annotations.js

@@ -0,0 +1,44 @@
+const { findSelector, normalizeIds } = require("./determinism");
+
+function toAnnotationSummary(annotation) {
+  const tokenSelector = findSelector(annotation, "TokenSelector");
+  const textPos = findSelector(annotation, "TextPositionSelector");
+  return {
+    id: typeof annotation.id === "string" ? annotation.id : "",
+    kind: String(annotation.kind || ""),
+    status: String(annotation.status || ""),
+    label: typeof annotation.label === "string" ? annotation.label : undefined,
+    token_ids: tokenSelector && Array.isArray(tokenSelector.token_ids) ? normalizeIds(tokenSelector.token_ids) : [],
+    span:
+      textPos && textPos.span && typeof textPos.span.start === "number" && typeof textPos.span.end === "number"
+        ? { start: textPos.span.start, end: textPos.span.end }
+        : undefined,
+    source_names: normalizeIds(
+      (Array.isArray(annotation.sources) ? annotation.sources : [])
+        .map((s) => (s && typeof s.name === "string" ? s.name : ""))
+        .filter(Boolean)
+    ),
+  };
+}
+
+function buildAcceptedAnnotationsInventory(relationsSeed) {
+  const annotations = Array.isArray(relationsSeed && relationsSeed.annotations) ? relationsSeed.annotations : [];
+  return annotations
+    .filter((annotation) => annotation && annotation.status === "accepted")
+    .map(toAnnotationSummary)
+    .sort((a, b) => {
+      if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
+      if ((a.span && a.span.start) !== (b.span && b.span.start)) {
+        return (a.span ? a.span.start : -1) - (b.span ? b.span.start : -1);
+      }
+      if ((a.span && a.span.end) !== (b.span && b.span.end)) {
+        return (a.span ? a.span.end : -1) - (b.span ? b.span.end : -1);
+      }
+      return a.id.localeCompare(b.id);
+    });
+}
+
+module.exports = {
+  toAnnotationSummary,
+  buildAcceptedAnnotationsInventory,
+};