@rsconcept/rstool 0.2.0 → 0.2.1
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/docs/CONCEPTUAL-SCHEMA.md +168 -0
- package/docs/CONSTITUENTA.md +7 -0
- package/docs/DOMAIN.md +28 -28
- package/docs/README.md +1 -0
- package/docs/TYPIFICATION.md +6 -6
- package/package.json +1 -1
- package/skills/rstool-helper/GUIDE.md +8 -0
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Conceptual schema (КС) — agent recommendations
|
|
2
|
+
|
|
3
|
+
This note complements the mechanistic references:
|
|
4
|
+
|
|
5
|
+
- `CONSTITUENTA.md` — how to upsert constituents correctly (fields, order, validation)
|
|
6
|
+
- `SYNTAX.md` / `TYPIFICATION.md` — how to construct correct RS expressions
|
|
7
|
+
|
|
8
|
+
Here we focus on **how to design and analyse a conceptual schema as a system of constituents**.
|
|
9
|
+
|
|
10
|
+
## What makes a schema valuable
|
|
11
|
+
|
|
12
|
+
The value of a conceptual schema is the **diversity of concepts expressed in it**.
|
|
13
|
+
|
|
14
|
+
- A good schema forms a **domain thesaurus**: a stable set of terms and distinctions that people can use for communication and decision-making.
|
|
15
|
+
- “Diversity” is not the same as “many aliases”. Prefer concepts that introduce **new distinctions** (new criteria, roles, constraints, invariants) instead of synonyms.
|
|
16
|
+
|
|
17
|
+
Practical agent heuristic:
|
|
18
|
+
|
|
19
|
+
- If you can remove a derived concept `D#` and lose no important language for reasoning, it is probably redundant.
|
|
20
|
+
- If stakeholders keep rephrasing the same thing in different words, the schema likely misses one or more constituents that capture the missing distinction.
|
|
21
|
+
|
|
22
|
+
## Rule for text fields (term / definitionText / convention)
|
|
23
|
+
|
|
24
|
+
When you write natural-language text in a schema, follow this strict rule:
|
|
25
|
+
|
|
26
|
+
- **Use only terms that are introduced in the schema itself.**
|
|
27
|
+
|
|
28
|
+
Rationale:
|
|
29
|
+
|
|
30
|
+
- Text definitions that rely on “external vocabulary” quietly import unstated assumptions and weaken the schema as a shared thesaurus.
|
|
31
|
+
|
|
32
|
+
Agent checklist:
|
|
33
|
+
|
|
34
|
+
- When you add a new `definitionText`, scan it for nouns/terms. If a term is essential, introduce it explicitly (typically as `N#`, `X#`, `S#`, or a derived `D#`).
|
|
35
|
+
- Prefer short “closed-world” definitions: explain a concept using already-introduced schema terms plus logical connectives (“and”, “or”, “not”), quantifiers (“for all”, “exists”), and references to RS expressions.
|
|
36
|
+
|
|
37
|
+
## Modeling genus structures (родовые структуры) as `S#`
|
|
38
|
+
|
|
39
|
+
`S#` constituents represent **base structured concepts**: their `definitionFormal` is a **typification** (grade), and their meaning is set by `convention` plus axioms.
|
|
40
|
+
|
|
41
|
+
### Define structure components explicitly
|
|
42
|
+
|
|
43
|
+
For a genus structure `S#`, it is often useful to define **all components** as named derived terms.
|
|
44
|
+
|
|
45
|
+
Why:
|
|
46
|
+
|
|
47
|
+
- It gives names to projections / reduced parts of a structure, making the thesaurus usable.
|
|
48
|
+
- It shortens later formulas and prevents agents from repeating long projection chains differently in different places.
|
|
49
|
+
|
|
50
|
+
Typical pattern for a binary relation over a base set:
|
|
51
|
+
|
|
52
|
+
- `X1` — base set (undefined)
|
|
53
|
+
- `S1 : ℬ(X1×X1)` — relation as a structure (undefined, meaning via convention)
|
|
54
|
+
- Component terms:
|
|
55
|
+
- `D_dom := Pr1(S1)` — “domain” / “left elements”
|
|
56
|
+
- `D_cod := Pr2(S1)` — “codomain” / “right elements”
|
|
57
|
+
- `D_pairs := red(bool(S1))` is usually nonsense; instead name the parts you truly use
|
|
58
|
+
- For higher-arity structures, define `Pr1`, `Pr2`, … and relevant multi-projections (`Pr1,3`, etc.)
|
|
59
|
+
|
|
60
|
+
More generally:
|
|
61
|
+
|
|
62
|
+
- **Projections** (`Pr*`, `pr*`) are the main tool for naming components.
|
|
63
|
+
- **Reduce** (`red`) is useful when a component is a set-of-sets and you need a flattened union; introduce a named `D#` when you use `red` in more than one place.
|
|
64
|
+
|
|
65
|
+
### Avoid “anonymous structure usage”
|
|
66
|
+
|
|
67
|
+
If later definitions repeatedly use expressions like `Pr2(Fi1[D](S7))`, it is usually a sign that:
|
|
68
|
+
|
|
69
|
+
- the schema is missing a named constituent for that concept, or
|
|
70
|
+
- the structure `S7` is underspecified (needs conventions/axioms).
|
|
71
|
+
|
|
72
|
+
Prefer to introduce:
|
|
73
|
+
|
|
74
|
+
- an intermediate derived term `D#` for the filtered relation/set, and
|
|
75
|
+
- separate terms for the projections you interpret in text.
|
|
76
|
+
|
|
77
|
+
## Axioms as semantic direction
|
|
78
|
+
|
|
79
|
+
An axiom `A#` is a **true statement** that:
|
|
80
|
+
|
|
81
|
+
- defines the intended semantics of genus structures, and
|
|
82
|
+
- enables safe derivations (“in a certain direction”) by providing guarantees needed for operations.
|
|
83
|
+
|
|
84
|
+
Think of axioms as giving you _permission to use certain operators_ without risking typification/runtime failures or semantic ambiguity.
|
|
85
|
+
|
|
86
|
+
### Example: singleton guarantee for `debool`
|
|
87
|
+
|
|
88
|
+
`debool(S)` is only meaningful when `S` is guaranteed to be a **singleton**.
|
|
89
|
+
|
|
90
|
+
In practice, when you build `S` as a projection/filter result, you often need an axiom that guarantees uniqueness.
|
|
91
|
+
|
|
92
|
+
For example, for a binary relation `S1 : ℬ(X1×X1)` you may want to define a function-like choice:
|
|
93
|
+
|
|
94
|
+
- `D_childOf(x) := debool(Pr2(Fi1[bool(x)](S1)))`
|
|
95
|
+
|
|
96
|
+
This is only valid if for every `x` the filtered projection yields exactly one element.
|
|
97
|
+
That guarantee is provided by an axiom of **right-uniqueness** (functional dependency) for the relation (written in RS logic for your specific structure).
|
|
98
|
+
|
|
99
|
+
Agent rule:
|
|
100
|
+
|
|
101
|
+
- If you see `debool(...)` in a definition, ensure there is an axiom that makes the inner set a singleton on the intended domain.
|
|
102
|
+
- If the axiom is absent, either (a) add the axiom, (b) replace `debool` by keeping the set-valued result, or (c) restrict the domain explicitly so the singleton property holds.
|
|
103
|
+
|
|
104
|
+
## Expression hygiene: avoid tautological membership checks
|
|
105
|
+
|
|
106
|
+
In well-typed/correct RS expressions, you should avoid adding membership predicates that only restate what is already guaranteed by typification and by the correctness model.
|
|
107
|
+
|
|
108
|
+
Specifically, avoid “sanity checks” like:
|
|
109
|
+
|
|
110
|
+
- `x ∈ X1`
|
|
111
|
+
- `x ∈ ℬ(X1)` (and other plain grade constructions such as `X1×X2`, `B(X1)`, etc.)
|
|
112
|
+
|
|
113
|
+
when `x` is already bound/typed as an element compatible with `X1` (or with the intended element structure induced by `ℬ(X1)`, `X1×X2`, …).
|
|
114
|
+
|
|
115
|
+
Why this is usually meaningless:
|
|
116
|
+
|
|
117
|
+
- `AnalysisResult` checks expressions in a **global context** where identifiers must have known typifications and must satisfy **bijective portability**.
|
|
118
|
+
- Under these guarantees, values of an element grade “already belong” to the corresponding set/grade in the semantic sense; so the predicate becomes (effectively) TRUE and adds no discriminating information.
|
|
119
|
+
|
|
120
|
+
Agent rule:
|
|
121
|
+
|
|
122
|
+
- Use membership (`∈` / `Fi*`) to express *nontrivial* schema semantics (e.g. defining/characterising derived sets), not to re-check that a value matches its own typification.
|
|
123
|
+
|
|
124
|
+
## Bijective portability (биективная переносимость)
|
|
125
|
+
|
|
126
|
+
**Bijective portability** means that a formal meaning/definition of a constituent depends only on the *structure* that the schema intends, and not on arbitrary “names” of undefined-concept interpretations.
|
|
127
|
+
|
|
128
|
+
Concretely, if you replace interpretations of undefined concepts by a bijective renaming (structure-preserving renaming), then:
|
|
129
|
+
|
|
130
|
+
- the evaluation result of every bijectively portable definition is unchanged up to the same renaming,
|
|
131
|
+
- therefore definitions are stable and reusable across equivalent models.
|
|
132
|
+
|
|
133
|
+
In rstool’s correctness model this property is not optional for the formal part:
|
|
134
|
+
|
|
135
|
+
- all formal definitions are required to be **bijectively portable**,
|
|
136
|
+
- expression checking assumes bijective portability for every referenced identifier.
|
|
137
|
+
|
|
138
|
+
Because of this, membership checks against base sets/grades become redundant in correct expressions: the type discipline plus portability already guarantee the relevant “belonging” constraints.
|
|
139
|
+
|
|
140
|
+
## Analysis: how to review a schema as a system
|
|
141
|
+
|
|
142
|
+
### Thesaurus health
|
|
143
|
+
|
|
144
|
+
- **Coverage**: do core domain nouns/roles appear as constituents (`N#`, `X#`, `S#`, `D#`)?
|
|
145
|
+
- **Non-synonymy**: if two terms are interchangeable in all axioms/definitions, collapse or differentiate them.
|
|
146
|
+
- **Naming stability**: avoid renaming “public” terms frequently; prefer adding refined terms and marking old ones as deprecated in text (if your workflow supports that).
|
|
147
|
+
|
|
148
|
+
### Term graph health (dependencies)
|
|
149
|
+
|
|
150
|
+
- Prefer a **layered graph**: bases/constants → core structures → derived projections/components → higher-level derived concepts → axioms/statements.
|
|
151
|
+
|
|
152
|
+
### Axiom health
|
|
153
|
+
|
|
154
|
+
- Every axiom should have a clear intent: uniqueness, totality, disjointness, ordering, invariance, domain/range constraints, etc.
|
|
155
|
+
- Prefer a small set of high-leverage axioms that unlock safe derivations, rather than many weak axioms with overlapping meaning.
|
|
156
|
+
- If axioms regularly fail in model evaluation, either the interpretation data violates the intended semantics or the semantics are wrong — in both cases the schema needs revision.
|
|
157
|
+
|
|
158
|
+
## Practical workflow for agents (recommended)
|
|
159
|
+
|
|
160
|
+
1. **Start with a vocabulary list** (domain nouns, roles, relations) → introduce `N#` for stable names when formalisation is not ready yet.
|
|
161
|
+
2. **Introduce bases/constants** (`X#`, `C#`) early with conventions.
|
|
162
|
+
3. **Introduce core structures** (`S#`) with typifications + conventions; immediately add the most important component terms (`Pr*`, `red`-based terms).
|
|
163
|
+
4. **Add derived concepts** (`D#`, `F#`, `P#`) incrementally; keep definitions short by using named components.
|
|
164
|
+
5. **Add axioms** (`A#`) that:
|
|
165
|
+
- encode intended semantics of structures,
|
|
166
|
+
- justify `debool`/functional choices, and
|
|
167
|
+
- restrict domains/ranges so derived concepts remain meaningful.
|
|
168
|
+
6. Run analysis on scratch expressions before committing, and keep text definitions closed-world (schema terms only).
|
package/docs/CONSTITUENTA.md
CHANGED
|
@@ -16,6 +16,13 @@ Use this when upserting constituents via `addOrUpdateConstituenta`.
|
|
|
16
16
|
|
|
17
17
|
Omitted text fields default to `''` in stored state.
|
|
18
18
|
|
|
19
|
+
## Language of text fields
|
|
20
|
+
|
|
21
|
+
The natural-language fields `term`, `definitionText`, and `convention` should be written in **one consistent language**:
|
|
22
|
+
|
|
23
|
+
- When editing/extending an existing schema, keep the **same language** that is already used in the schema’s text fields.
|
|
24
|
+
- When creating a new schema from scratch, use the **language of the user’s request**.
|
|
25
|
+
|
|
19
26
|
## `cstType` table
|
|
20
27
|
|
|
21
28
|
| `cstType` (value) | Prefix | Formal definition | Notes |
|
package/docs/DOMAIN.md
CHANGED
|
@@ -18,18 +18,18 @@ A **constituent** is the atomic building block of a conceptual schema. Each cons
|
|
|
18
18
|
|
|
19
19
|
Constituent aliases follow a strict prefix scheme:
|
|
20
20
|
|
|
21
|
-
| Alias prefix | Role
|
|
22
|
-
|
|
23
|
-
| `N#`
|
|
24
|
-
| `X#`
|
|
25
|
-
| `C#`
|
|
26
|
-
| `S#`
|
|
27
|
-
| `D#`
|
|
28
|
-
| `F#`
|
|
29
|
-
| `P#`
|
|
30
|
-
| `A#`
|
|
31
|
-
| `T#`
|
|
32
|
-
| `R#`
|
|
21
|
+
| Alias prefix | Role | Notes |
|
|
22
|
+
| ------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
23
|
+
| `N#` | Nominoid | Free vocabulary item, no formal definition |
|
|
24
|
+
| `X#` | Base set | Undefined concept, set of elements |
|
|
25
|
+
| `C#` | Constant set | Undefined concept, set of elements, allows arithmetic predicates and operations |
|
|
26
|
+
| `S#` | Structured concept (**genus structure**) | Undefined concept; `definitionFormal` gives **typification**; meaning via `convention` / axioms |
|
|
27
|
+
| `D#` | Term | Derived concept; `definitionFormal` is the **definition**; value computed in a model |
|
|
28
|
+
| `F#` | Term-function | Parameterised derived concept yielding an STE |
|
|
29
|
+
| `P#` | Predicate-function | Parameterised derived concept yielding a logical expression |
|
|
30
|
+
| `A#` | Axiom | Logical statement asserting requirements |
|
|
31
|
+
| `T#` | Statement | Logical assertion about the model |
|
|
32
|
+
| `R#` | Radical | Template placeholder for arbitrary typification |
|
|
33
33
|
|
|
34
34
|
**Undefined concepts** (`X#`, `C#`, `S#`) are introduced by conventions (and optional axioms). For `S#`, the formal field states **typification** (the grade of elements), not a defining construction. **Derived concepts** (`D#`, `F#`, `P#`, `A#`, `T#`) carry a formal **definition** and must follow declaration order — every referenced constituent must already exist; their model values are obtained by evaluation.
|
|
35
35
|
|
|
@@ -41,27 +41,27 @@ A **crucial constituent** is marked as content-bearing for filtering / focus; it
|
|
|
41
41
|
|
|
42
42
|
Each constituent has one of the following correctness statuses:
|
|
43
43
|
|
|
44
|
-
| Status
|
|
45
|
-
|
|
46
|
-
| Unknown
|
|
47
|
-
| OK
|
|
48
|
-
| Error
|
|
49
|
-
| Property
|
|
50
|
-
| Incalculable | Cannot be evaluated directly (e.g. expected exponential blow-up)
|
|
44
|
+
| Status | Meaning |
|
|
45
|
+
| ------------ | ------------------------------------------------------------------ |
|
|
46
|
+
| Unknown | Not yet validated |
|
|
47
|
+
| OK | Validated as correct |
|
|
48
|
+
| Error | Validation failed |
|
|
49
|
+
| Property | Defines a non-computable set; only membership tests are admissible |
|
|
50
|
+
| Incalculable | Cannot be evaluated directly (e.g. expected exponential blow-up) |
|
|
51
51
|
|
|
52
52
|
## RSModel evaluation states
|
|
53
53
|
|
|
54
54
|
In a conceptual model each item has one of the following evaluation statuses:
|
|
55
55
|
|
|
56
|
-
| Status
|
|
57
|
-
|
|
58
|
-
| `NO_EVAL` (1)
|
|
59
|
-
| `NOT_PROCESSED` (2) | Interpretation has not been computed yet
|
|
60
|
-
| `INVALID_DATA` (3)
|
|
61
|
-
| `EVAL_FAIL` (4)
|
|
62
|
-
| `AXIOM_FALSE` (5)
|
|
63
|
-
| `EMPTY` (6)
|
|
64
|
-
| `HAS_DATA` (7)
|
|
56
|
+
| Status | Meaning |
|
|
57
|
+
| ------------------- | ----------------------------------------------- |
|
|
58
|
+
| `NO_EVAL` (1) | Not evaluated (definition is not interpretable) |
|
|
59
|
+
| `NOT_PROCESSED` (2) | Interpretation has not been computed yet |
|
|
60
|
+
| `INVALID_DATA` (3) | Provided data is invalid |
|
|
61
|
+
| `EVAL_FAIL` (4) | Evaluation raised an error |
|
|
62
|
+
| `AXIOM_FALSE` (5) | Axiom evaluated to FALSE |
|
|
63
|
+
| `EMPTY` (6) | Result is the empty set |
|
|
64
|
+
| `HAS_DATA` (7) | Interpretation computed and non-empty |
|
|
65
65
|
|
|
66
66
|
## Synthesis and OSS
|
|
67
67
|
|
package/docs/README.md
CHANGED
|
@@ -5,6 +5,7 @@ Standalone English reference distilled from the Portal manuals and `CONTEXT.md`.
|
|
|
5
5
|
| File | Read when |
|
|
6
6
|
|------|-----------|
|
|
7
7
|
| [`DOMAIN.md`](DOMAIN.md) | You need the Concept Portal vocabulary (constituenta, conceptual schema/model, OSS, synthesis). |
|
|
8
|
+
| [`CONCEPTUAL-SCHEMA.md`](CONCEPTUAL-SCHEMA.md) | You are designing/reviewing a conceptual schema as a system (thesaurus value, closed-world text definitions, genus structures, axioms). |
|
|
8
9
|
| [`CONSTITUENTA.md`](CONSTITUENTA.md) | You are upserting constituents — fields, `cstType` table, validation rules, recommended order. |
|
|
9
10
|
| [`SYNTAX.md`](SYNTAX.md) | You are constructing RSLang expressions — operators, quantifiers, parameterised functions, examples. |
|
|
10
11
|
| [`TYPIFICATION.md`](TYPIFICATION.md) | You are interpreting `AnalysisResult.type` / `valueClass` or constructing template expressions with radicals. |
|
package/docs/TYPIFICATION.md
CHANGED
|
@@ -6,12 +6,12 @@ Distilled from `help-rslang-typification`, `help-rslang-expression-structure`, a
|
|
|
6
6
|
|
|
7
7
|
A genus-structure expression `ξ` has typification (a _structure_) if `ξ ∈ H` holds, where `H` is a valid **grade**. Grades are built recursively:
|
|
8
8
|
|
|
9
|
-
| Grade | Form | Notes
|
|
10
|
-
| ---------------- | -------------------- |
|
|
11
|
-
| Element | `Xi`, `Ci` | grade of
|
|
12
|
-
| Integer | `Z` | grade of integer
|
|
13
|
-
| Tuple of arity n | `(H1 × H2 × … × Hn)` | ordered structured grade
|
|
14
|
-
| Set | `ℬ(H)` | set of values of grade `H`
|
|
9
|
+
| Grade | Form | Notes |
|
|
10
|
+
| ---------------- | -------------------- | ------------------------------------ |
|
|
11
|
+
| Element | `Xi`, `Ci` | grade of a basic concept's elements |
|
|
12
|
+
| Integer | `Z` | grade of integer |
|
|
13
|
+
| Tuple of arity n | `(H1 × H2 × … × Hn)` | ordered structured grade |
|
|
14
|
+
| Set | `ℬ(H)` | unordered set of values of grade `H` |
|
|
15
15
|
|
|
16
16
|
The empty set `∅` has typification `ℬ(R0)` — a set with arbitrary element structure. The radical `R0` ensures it conforms to any element grade in context.
|
|
17
17
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rsconcept/rstool",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract and stdio wrapper.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "IRBorisov",
|
|
@@ -17,6 +17,7 @@ Paths below are relative to **this file** (`skills/rstool-helper/GUIDE.md`).
|
|
|
17
17
|
| rstool API, methods, error codes | [REFERENCE.md](REFERENCE.md) |
|
|
18
18
|
| Worked examples, common mistakes | [EXAMPLES.md](EXAMPLES.md) |
|
|
19
19
|
| Domain vocabulary (English) | [../../docs/DOMAIN.md](../../docs/DOMAIN.md) |
|
|
20
|
+
| Designing/reviewing conceptual schemas (agent recommendations) | [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md) |
|
|
20
21
|
| Constituenta fields, validation, ordering | [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md) |
|
|
21
22
|
| RSLang syntax (operators, quantifiers) | [../../docs/SYNTAX.md](../../docs/SYNTAX.md) |
|
|
22
23
|
| Typification grades, radicals | [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md) |
|
|
@@ -122,6 +123,13 @@ Don't infer types—always read tool output.
|
|
|
122
123
|
3. Topological: dependencies before dependents (e.g. `D1` before `D2` if `D2` refers to `D1`)
|
|
123
124
|
4. Derived right after their sources
|
|
124
125
|
|
|
126
|
+
## Natural-language fields: keep one language
|
|
127
|
+
|
|
128
|
+
When you create new constituents (concepts) or build a schema from scratch, the fields `term`, `definitionText`, and `convention` must be written **in one consistent natural language**:
|
|
129
|
+
|
|
130
|
+
- If you are extending an existing schema/session, write these fields in the **same language that is already used** in the schema’s text fields.
|
|
131
|
+
- If you are creating a new schema from zero, write these fields in the **language of the user’s request**.
|
|
132
|
+
|
|
125
133
|
## Checklist
|
|
126
134
|
|
|
127
135
|
- [ ] `sessionId` obtained & tracked
|