@mailwoman/geographic-model 10.3.0 → 10.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -16
- package/lib/packaged.ts +1 -1
- package/out/packaged.d.ts +1 -1
- package/out/packaged.js +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @mailwoman/geographic-model
|
|
2
2
|
|
|
3
|
-
Authored geographic semantics for the [mailwoman](https://www.npmjs.com/package/mailwoman) geocoder: stable concepts (`pharmacy`, `obtain_medication`), the relations a curator can state between them (`pharmacy affords obtain_medication`), mappings into external vocabularies, source observations, and derived facts. Every record
|
|
3
|
+
Authored geographic semantics for the [mailwoman](https://www.npmjs.com/package/mailwoman) geocoder: stable concepts (`pharmacy`, `obtain_medication`), the relations a curator can state between them (`pharmacy affords obtain_medication`), mappings into external vocabularies, source observations, and derived facts. Every record states its provenance, and the package compiles all of it deterministically into a lookup artifact that the runtime reads.
|
|
4
4
|
|
|
5
5
|
A geocoder benefits from knowing that a pharmacy is a place where you obtain medication. Once that knowledge becomes a ranking rule, however, authored opinion starts overriding what the models learned from data. This package stores the knowledge in a shape that cannot become ranking policy. The schema has no numeric field, and the compiled artifact answers lookups and never orderings.
|
|
6
6
|
|
|
@@ -16,19 +16,19 @@ You probably should not install it directly yet.
|
|
|
16
16
|
|
|
17
17
|
One document holds six tables, and all six are required. A hand-authored file writes `"derivedFacts": []` instead of leaving the table out, because an absent table and an empty table make different claims.
|
|
18
18
|
|
|
19
|
-
| Table | Record | What it is
|
|
20
|
-
| -------------- | --------------------------------------- |
|
|
21
|
-
| `relations` | `RelationRecord` | Vocabulary: what a relation means,
|
|
22
|
-
| `concepts` | `ConceptRecord` + `RelationAssertion[]` | Authored semantics: a concept, its broader concepts, and the claims a curator states about it
|
|
23
|
-
| `mappings` | `ExternalMappingRecord` | Translation into an external vocabulary — today `@mailwoman/poi-taxonomy` category identifiers
|
|
24
|
-
| `observations` | `SourceObservationRecord` | What a
|
|
25
|
-
| `derivedFacts` | `DerivedFactRecord` | What a
|
|
19
|
+
| Table | Record | What it is |
|
|
20
|
+
| -------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| `relations` | `RelationRecord` | Vocabulary: what a relation means, the concept kinds allowed on each side, whether it is transitive or symmetric, and its inverse |
|
|
22
|
+
| `concepts` | `ConceptRecord` + `RelationAssertion[]` | Authored semantics: a concept, its broader concepts, and the claims a curator states about it |
|
|
23
|
+
| `mappings` | `ExternalMappingRecord` | Translation into an external vocabulary — today `@mailwoman/poi-taxonomy` category identifiers |
|
|
24
|
+
| `observations` | `SourceObservationRecord` | What a cited external source states, recorded in this vocabulary and kept out of the concept table |
|
|
25
|
+
| `derivedFacts` | `DerivedFactRecord` | What a cited procedure computed, with every record it read listed as an input. Written by the compiler, never by hand |
|
|
26
26
|
|
|
27
27
|
Three properties hold by construction:
|
|
28
28
|
|
|
29
29
|
- **The schema has no numeric field.** It has no strength, confidence, or count. `Modality` is an ordinal vocabulary of words (`necessary`, `prohibited`, `strongly_expected`, … `strongly_unusual`), and the package exports no order over it, because a number on an authored relationship acts as a ranking weight whatever it is called.
|
|
30
|
-
- **Authored, observed, and derived records are three distinct types.** Their identifiers
|
|
31
|
-
- **A derived fact
|
|
30
|
+
- **Authored, observed, and derived records are three distinct types.** Their identifiers have separate brands, so one cannot be assigned where another is expected. They live in separate tables, so a curator must make each curation decision deliberately instead of relying on where a record happens to sit.
|
|
31
|
+
- **A derived fact records its provenance in its structure.** It has no `source` field. Its `derivation` and its `inputs` form the provenance, and every input records source provenance in turn. A source string can be copied onto a record that did not come from that source, but an input list must resolve or the document fails validation.
|
|
32
32
|
|
|
33
33
|
Identifiers are branded through `type-fest`'s `Tagged` and converted explicitly with `toConceptID`, `toRelationID`, `toRuleID`, `toMappingID`, `toObservationID`, and `toDerivedFactID`. The brands exist only at compile time, and the strings pass through JSON unchanged.
|
|
34
34
|
|
|
@@ -44,13 +44,13 @@ The validator is plain deterministic TypeScript with no I/O. It uses no reasoner
|
|
|
44
44
|
|
|
45
45
|
## The loader, the compiler, and the artifact
|
|
46
46
|
|
|
47
|
-
`loadGeographicModelDirectory(root)` reads every `*.json` file under a directory and merges them into one document. It lives in the `./load` subpath and is the only module here that touches a filesystem. The file layout is an authoring convenience and
|
|
47
|
+
`loadGeographicModelDirectory(root)` reads every `*.json` file under a directory and merges them into one document. It lives in the `./load` subpath and is the only module here that touches a filesystem. The file layout is an authoring convenience and has no meaning. Enumeration order cannot affect the output, and every validation issue identifies the file it came from.
|
|
48
48
|
|
|
49
|
-
`compileGeographicModel(input)` delegates validation and then compiles.
|
|
49
|
+
`compileGeographicModel(input)` delegates validation and then compiles. **Only `isA` defines semantic inheritance.** The artifact stores every concept's transitive ancestors, and it copies every ancestor's assertions onto descendants as derived facts that record their derivation and inputs. The compiler does **not** compute closures for a relation that declares `transitive` or `inverse`. Those fields describe what the relation means, and general reasoning is excluded from this package for its lifetime.
|
|
50
50
|
|
|
51
51
|
`serializeCompiledModel(model)` produces canonical bytes. Keys appear in code-point order at every depth, tables are ordered by identifier, and no field records when compilation ran. Two builds of one document are byte-identical, so regenerating produces a diff only when the records changed.
|
|
52
52
|
|
|
53
|
-
`createGeographicModelIndex(model)` in the `./lookup` subpath is the read interface: `concept`, `relation`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`. It supports lookups only, without walks, cursors, or a query language, because the artifact exists to remove query-time traversal. Two kinds of absence stay distinguishable. A concept that the artifact does not
|
|
53
|
+
`createGeographicModelIndex(model)` in the `./lookup` subpath is the read interface: `concept`, `relation`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`. It supports lookups only, without walks, cursors, or a query language, because the artifact exists to remove query-time traversal. Two kinds of absence stay distinguishable. A concept that the artifact does not contain answers `undefined`, and a stored concept with no derived facts answers an empty list.
|
|
54
54
|
|
|
55
55
|
## What is authored today
|
|
56
56
|
|
|
@@ -89,9 +89,9 @@ Each of these concerns belongs to another package. The ownership list prevents a
|
|
|
89
89
|
| Dataset identity and coverage epistemics | `@mailwoman/core/layers` |
|
|
90
90
|
| Empirical, spatial activity-affordance statistics | Fitted from data elsewhere in the program, against the identifiers owned here |
|
|
91
91
|
|
|
92
|
-
Tests enforce two rules. First, `@mailwoman/core` must not depend on this package. Core ships the pipeline interface plus ~9 MB of reference data to every consumer, so every drop-in API would inherit a world-semantics dependency added there. Second, the public API
|
|
92
|
+
Tests enforce two rules. First, `@mailwoman/core` must not depend on this package. Core ships the pipeline interface plus ~9 MB of reference data to every consumer, so every drop-in API would inherit a world-semantics dependency added there. Second, the public API exposes no ranking policy. A binding whose name suggests a boost, penalty, weight, rank, score, or ordering fails the suite.
|
|
93
93
|
|
|
94
|
-
One rule governs the whole boundary: **knowledge creates observations
|
|
94
|
+
One rule governs the whole boundary: **knowledge creates observations, and it never overrides learned interpretation.** A record here may create a fact, an anomaly, a contradiction, or a coverage-qualified absence. It may not create an imperative.
|
|
95
95
|
|
|
96
96
|
The package architecture excludes the following for its whole life: an OWL/DL reasoner, a SPARQL endpoint, a triplestore, a general-purpose knowledge-graph service, and any query-time traversal of the authoring JSON. Authored records are source material that compiles into artifacts, and the package provides no service.
|
|
97
97
|
|
|
@@ -104,7 +104,7 @@ This README is the package-local summary. The authoritative documents are in the
|
|
|
104
104
|
|
|
105
105
|
## Layout
|
|
106
106
|
|
|
107
|
-
Source lives at the workspace root. Each test sits beside the module it covers under `lib/`. The manifest's `files` array declares `data/**/*.json` explicitly. `**/*.ts` does not match JSON, and a data file missing from `files` would leave the installed package without the data it exists to
|
|
107
|
+
Source lives at the workspace root. Each test sits beside the module it covers under `lib/`. The manifest's `files` array declares `data/**/*.json` explicitly. `**/*.ts` does not match JSON, and a data file missing from `files` would leave the installed package without the data it exists to ship.
|
|
108
108
|
|
|
109
109
|
## License
|
|
110
110
|
|
package/lib/packaged.ts
CHANGED
|
@@ -15,7 +15,7 @@ import { type CompiledGeographicModel, parseCompiledGeographicModel } from "#art
|
|
|
15
15
|
/**
|
|
16
16
|
* The authoring directory and the artifact it compiles to.
|
|
17
17
|
*
|
|
18
|
-
* Probes for `model/model.json`, so a
|
|
18
|
+
* Probes for `model/model.json`, so a missing `data/` throws naming the path.
|
|
19
19
|
*/
|
|
20
20
|
export async function packagedModelPaths(): Promise<{ source: string; artifact: string }> {
|
|
21
21
|
const candidates = [resolvePackagePath("@mailwoman/geographic-model", "data")]
|
package/out/packaged.d.ts
CHANGED
|
@@ -8,7 +8,7 @@ import { type CompiledGeographicModel } from "#artifact";
|
|
|
8
8
|
/**
|
|
9
9
|
* The authoring directory and the artifact it compiles to.
|
|
10
10
|
*
|
|
11
|
-
* Probes for `model/model.json`, so a
|
|
11
|
+
* Probes for `model/model.json`, so a missing `data/` throws naming the path.
|
|
12
12
|
*/
|
|
13
13
|
export declare function packagedModelPaths(): Promise<{
|
|
14
14
|
source: string;
|
package/out/packaged.js
CHANGED
|
@@ -12,7 +12,7 @@ import { parseCompiledGeographicModel } from "#artifact";
|
|
|
12
12
|
/**
|
|
13
13
|
* The authoring directory and the artifact it compiles to.
|
|
14
14
|
*
|
|
15
|
-
* Probes for `model/model.json`, so a
|
|
15
|
+
* Probes for `model/model.json`, so a missing `data/` throws naming the path.
|
|
16
16
|
*/
|
|
17
17
|
export async function packagedModelPaths() {
|
|
18
18
|
const candidates = [resolvePackagePath("@mailwoman/geographic-model", "data")];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mailwoman/geographic-model",
|
|
3
|
-
"version": "10.
|
|
3
|
+
"version": "10.4.0",
|
|
4
4
|
"description": "Stable geographic concepts, relations, mappings, source observations, derived facts, and their provenance — authored records compiled deterministically into runtime artifacts.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"affordance",
|
|
@@ -98,8 +98,8 @@
|
|
|
98
98
|
}
|
|
99
99
|
},
|
|
100
100
|
"dependencies": {
|
|
101
|
-
"@mailwoman/core": "10.
|
|
102
|
-
"@mailwoman/poi-taxonomy": "10.
|
|
101
|
+
"@mailwoman/core": "10.4.0",
|
|
102
|
+
"@mailwoman/poi-taxonomy": "10.4.0",
|
|
103
103
|
"type-fest": "^5.10.0"
|
|
104
104
|
},
|
|
105
105
|
"devDependencies": {
|