@rsconcept/rstool 0.2.1 → 0.3.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.
Files changed (16) hide show
  1. package/docs/CONCEPTUAL-SCHEMA.md +50 -140
  2. package/docs/CONSTITUENTA.md +37 -62
  3. package/docs/DIAGNOSTICS.md +85 -130
  4. package/docs/DOMAIN.md +68 -91
  5. package/docs/GRAMMAR-REF.md +35 -86
  6. package/docs/MODEL-TESTING.md +57 -0
  7. package/docs/PORTAL-API.md +22 -36
  8. package/docs/README.md +14 -13
  9. package/docs/SYNTAX.md +49 -104
  10. package/docs/TYPIFICATION.md +41 -60
  11. package/package.json +1 -1
  12. package/skills/README.md +6 -8
  13. package/skills/rstool-helper/EXAMPLES.md +83 -106
  14. package/skills/rstool-helper/GUIDE.md +66 -114
  15. package/skills/rstool-helper/REFERENCE.md +1 -0
  16. package/skills/rstool-helper/SKILL.md +5 -8
package/skills/rstool-helper/GUIDE.md CHANGED
@@ -1,141 +1,93 @@
1
- # RS Language & rstool — Compact Guide for Agents
1
+ # RS Language & rstool
2
2
 
3
- **RS language** is a formal scheme notation for concepts, relations, operations—extends FOL, core: membership `x∈y`; typification via set-theoretic/logical expressions.
3
+ Compact entry guide for agents. Keep details in linked docs.
4
4
 
5
- **rstool** is the agent API for sessions, upserts, analysis, diagnostics, modeling/evaluation, (de)serialization.
5
+ **RSLang** is a formal notation for conceptual schemas: concepts, relations, operations, assertions. Core ideas: membership `x∈y`, set-theoretic expressions, logical expressions, typification.
6
6
 
7
- - Library: `@rsconcept/rstool` (npm)
8
- - Analyzer: `@rsconcept/domain` (dependency of rstool)
9
- - Language reference: `docs/*.md` next to this package (see table below)
7
+ **rstool** is the agent API for sessions, upserts, analysis, diagnostics, model values, evaluation, export/import.
10
8
 
11
- ## Docs / hints (canonical paths)
9
+ - Library: `@rsconcept/rstool`.
10
+ - Analyzer: `@rsconcept/domain`.
11
+ - Stdio wrapper: `npx rstool-wrapper`, JSON per line.
12
+ - Node client: `RSToolWrapperClient`.
12
13
 
13
- Paths below are relative to **this file** (`skills/rstool-helper/GUIDE.md`).
14
+ ## What to Read
14
15
 
15
- | Info | Location |
16
- | :--- | :--- |
17
- | rstool API, methods, error codes | [REFERENCE.md](REFERENCE.md) |
18
- | Worked examples, common mistakes | [EXAMPLES.md](EXAMPLES.md) |
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) |
21
- | Constituenta fields, validation, ordering | [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md) |
22
- | RSLang syntax (operators, quantifiers) | [../../docs/SYNTAX.md](../../docs/SYNTAX.md) |
23
- | Typification grades, radicals | [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md) |
24
- | Diagnostic code → fix table | [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md) |
25
- | Portal REST API (live data) | [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md) |
26
- | Lezer grammar pointers | [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md) |
27
- | Package README | [../../README.md](../../README.md) |
16
+ Paths are relative to this file.
28
17
 
29
- When working from **npm**, the same tree lives under `node_modules/@rsconcept/rstool/` (use the Read tool on those paths from the project root).
18
+ - API, methods, stdio, error codes: [REFERENCE.md](REFERENCE.md).
19
+ - Worked examples and pitfalls: [EXAMPLES.md](EXAMPLES.md).
20
+ - Domain terms: [../../docs/DOMAIN.md](../../docs/DOMAIN.md).
21
+ - Schema design rules: [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
22
+ - Constituents and validation: [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
23
+ - Syntax: [../../docs/SYNTAX.md](../../docs/SYNTAX.md).
24
+ - Typification: [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
25
+ - Definition testing with small conceptual models: [../../docs/MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
26
+ - Diagnostics: [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
27
+ - Portal REST reads: [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md).
28
+ - Grammar pointers: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md).
30
29
 
31
- ## Protocol Summary
30
+ ## Workflow
32
31
 
33
- 1. **Start session**: `createSession`
34
- 2. **Add bases/constants**: type `basic` (`X*`), `constant` (`C*`) — `definitionFormal: ''`
35
- 3. **Add derived**: terms, axioms, etc.—only after dependencies present
36
- 4. **Analyze scratch**: `analyzeExpression`
37
- 5. **Process diagnostics**: check `analysis.diagnostics`/`listDiagnostics`; fix by range
38
- 6. **Checkpoint**: `commitStep` (message optional)
39
- 7. **Model values**: `setConstituentaValue` / `setConstituentaValues` for base bindings (`{0:"a",1:"b"}`) or structured values; `getModelState`
40
- 8. **Evaluate**: `evaluateExpression` (scratch) or `evaluateConstituenta` / `recalculateModel` (stored definitions)
41
- 9. **Export/import**: persist with `exportSession`/`importSession` (includes `state.model`)
32
+ 1. `createSession`.
33
+ 2. Add `basic` (`X#`) and `constant` (`C#`) with `definitionFormal: ''`.
34
+ 3. Add dependencies before dependents.
35
+ 4. Use `analyzeExpression` before upsert when unsure.
36
+ 5. When unsure about semantics, build a tiny conceptual model and evaluate test data.
37
+ 6. Fix diagnostics by `from` / `to` range in `definitionFormal`.
38
+ 7. `commitStep` when the state is coherent.
39
+ 8. Set base/model values with `setConstituentaValue(s)`.
40
+ 9. Evaluate with `evaluateExpression`, `evaluateConstituenta`, or `recalculateModel`.
41
+ 10. Persist with `exportSession` / `importSession`.
42
42
 
43
- **Clients**:
43
+ ## Portal REST
44
44
 
45
- - Node: use `RSToolWrapperClient`
46
- - Stdio process: `npx rstool-wrapper` — JSON per line
45
+ rstool never calls Portal REST itself. Fetch live data outside rstool, then import constituents with `addOrUpdateConstituenta`.
47
46
 
48
- ## API/REST
47
+ - UI host: `https://portal.acconcept.ru`.
48
+ - API host: `https://api.portal.acconcept.ru`.
49
+ - Useful reads: `/api/rsforms/{id}`, `/api/rsforms/{id}/details`, `/api/library/{id}/versions/{v}`, `/api/oss/{id}`, `/api/models/{id}`, `/schema`.
50
+ - Do not scrape SPA HTML or reuse UI query params like `?tab=`.
49
51
 
50
- For full reference see [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md). Short form:
52
+ ## Syntax Cheatsheet
51
53
 
52
- - **Portal UI**: `https://portal.acconcept.ru`
53
- - **API**: `https://api.portal.acconcept.ru`
54
- - Endpoints: `GET /api/rsforms/{id}`, `GET /api/rsforms/{id}/details`, `GET /api/library/{id}/versions/{v}`, `GET /api/oss/{id}`, `GET /api/models/{id}`, OpenAPI at `GET /schema`.
55
- - Don't scrape SPA or use UI query params (`tab=`, etc.).
56
- - rstool itself never calls the REST API; bring data in via `addOrUpdateConstituenta` after fetching.
54
+ - Globals: `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`, `N1`, `R1`.
55
+ - Locals: `x`, `ξ`, `μ2`.
56
+ - Literals: `42`, `Z`, `∅`.
57
+ - Set expressions: `∪`, `∩`, `\`, `∆`, `×`, `ℬ(...)`, tuples, `Pr*`, `Fi*`.
58
+ - Logic: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, `=`, `≠`, `<`, `∈`, `⊆`.
59
+ - Parameterized expressions: `[arg1∈H1, arg2∈H2] body`.
57
60
 
58
- ## Constituent Types (`cstType`)
59
-
60
- | cstType | Example | Formal | Notes |
61
- | :-------- | :------ | :-------- | :-------------------------------------------------------- |
62
- | basic | X1 | **empty** | Required |
63
- | constant | C1 | **empty** | Required |
64
- | nominal | S1 | allowed | Naming |
65
- | structure | S1 | allowed | Typification grade; base concept + `convention` |
66
- | term | D1 | allowed | Formal **definition**; derived concept, computed in model |
67
- | axiom | A1 | allowed | Logical; computed in model; required to be TRUE |
68
- | statement | T1 | allowed | Logical; computed in model |
69
- | function | F1 | allowed | Parameterized; derived concept |
70
- | predicate | P1 | allowed | Parameterized; derived concept |
71
-
72
- - Non-empty formal for `basic`/`constant` ⇒ error `0x8862` (`definitionNotAllowed`)
73
- - Empty `basic`/`constant` always typified
74
- - **Interpretable** (can set value): `basic`, `constant`, `structure`
75
- - **Inferrable** (computed, do not set directly): `term`, `axiom`, `statement`
76
-
77
- ## Structure (`S#`) vs term (`D#`)
78
-
79
- The same field `definitionFormal` has **different roles** depending on `cstType`:
80
-
81
- | | `structure` (`S#`) | `term` (`D#`) |
82
- | -------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
83
- | Role of `definitionFormal` | **Typification** — declares grade `H` (element structure) | **Definition** — declares how the concept is built from suppliers |
84
- | Concept class | **Undefined** — meaning from `convention` (+ axioms on `S#`) | **Derived** — meaning from the expression; no convention required |
85
- | Model interpretation | Values are **assigned** (or constrained by axioms); domain fills `S#` per convention | Value is **computed** via `evaluateConstituenta` / `recalculateModel` |
86
-
87
- **Same syntax, different semantics:** in `ℬ(X1×X1)` the fragment `X1×X1` is a **grade** (one ordered pair of base elements). On a **term** with body `X1×X1` alone, `×` builds the **full Cartesian product** — the set of all pairs from `X1`, not a relation typification.
88
-
89
- **Agent rule:** for a relation over `X1` (e.g. parent–child), upsert `S1` with `definitionFormal: 'ℬ(X1×X1)'` and a `convention`, then derive terms with projections/filters (`Pr1(S1)`, `Fi2[{ξ}](S1)`, …). Do not use bare `X1×X1` on a `term` when you meant the structure’s typification.
90
-
91
- See [EXAMPLES.md](EXAMPLES.md) (kinship-lite) and `../../examples/build-kinship-rsform.ts`.
92
-
93
- ## Syntax
94
-
95
- - **Globals**: `X1`, `C1`, `D1`, `F1`, `P1`, `A1`, `R1`
96
- - **Locals**: `x`, `ξ`, `μ2`
97
- - **Literals**: `42`, `Z`, `∅`
98
- - Full operator + precedence table: [../../docs/SYNTAX.md](../../docs/SYNTAX.md)
99
- - Grammar pointers: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md)
100
-
101
- ## Expression Types
102
-
103
- - **Set-theoretic**: `∪`, `∩`, `\`, `∆`, `×`, `∈`, `⊆`, `ℬ(...)`, tuples
104
- - **Logical**: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, comparisons `=`, `≠`, `<`
105
- - **Parameterized**: `[arg1∈H1, arg2∈H2] body`
106
- - Detailed semantics in [../../docs/SYNTAX.md](../../docs/SYNTAX.md); typification grades and radicals in [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
107
-
108
- Always set `cstType` in upserts/analysis to true role.
61
+ Read tool output; do not infer types by inspection.
109
62
 
110
63
  ## Diagnostics Loop
111
64
 
112
- 1. Check `analysis.success`
113
- 2. If not, see `analysis.diagnostics` / `listDiagnostics`
114
- 3. Map `code` → cause → fix via [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)
115
- 4. Use `from`, `to` to patch `definitionFormal`; re-send
116
-
117
- Don't infer types—always read tool output.
65
+ 1. Check `analysis.success`.
66
+ 2. If false, read `analysis.diagnostics` or `listDiagnostics`.
67
+ 3. Map `code` to a fix in `DIAGNOSTICS.md`.
68
+ 4. Patch the reported `from` / `to` range.
69
+ 5. Re-run only after changing input.
118
70
 
119
71
  ## Declaration Order
120
72
 
121
- 1. All `basic`, `constant`
122
- 2. Core/critical first
123
- 3. Topological: dependencies before dependents (e.g. `D1` before `D2` if `D2` refers to `D1`)
124
- 4. Derived right after their sources
73
+ 1. `basic`, `constant`.
74
+ 2. Core structures and key concepts.
75
+ 3. Derived constituents in topological order.
76
+ 4. Axioms and statements after their references.
125
77
 
126
- ## Natural-language fields: keep one language
78
+ ## Natural-Language Fields
127
79
 
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**:
80
+ Keep `term`, `definitionText`, and `convention` in one language.
129
81
 
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**.
82
+ - Extending a schema: use the schema's existing language.
83
+ - New schema: use the user's request language.
132
84
 
133
85
  ## Checklist
134
86
 
135
- - [ ] `sessionId` obtained & tracked
136
- - [ ] Bases/constants are empty formal
137
- - [ ] All dependencies exist before upsert
138
- - [ ] Matching `cstType`
139
- - [ ] Diagnostics handled before commit/export
140
- - [ ] Base bindings set before evaluating expressions that reference base elements
141
- - [ ] For other details, open [REFERENCE.md](REFERENCE.md) or linked `docs/*.md`
87
+ - [ ] `sessionId` tracked.
88
+ - [ ] `basic` / `constant` formals are empty.
89
+ - [ ] Dependencies exist before upsert.
90
+ - [ ] `cstType` matches the role.
91
+ - [ ] Diagnostics handled before commit/export.
92
+ - [ ] Ambiguous semantics checked on a small model when data examples are available.
93
+ - [ ] Base values set before evaluation.
package/skills/rstool-helper/REFERENCE.md CHANGED
@@ -143,6 +143,7 @@ Standalone agents should consult the bundled distilled docs (`docs/*.md` inside
143
143
  | Quantifiers | `docs/SYNTAX.md` § *Quantifiers* |
144
144
  | Parameterized functions, templates | `docs/SYNTAX.md` § *Parameterised* |
145
145
  | Correctness / validation mindset | `docs/SYNTAX.md` § *Correctness model* |
146
+ | Definition semantic tests | `docs/MODEL-TESTING.md` |
146
147
  | Domain vocabulary | `docs/DOMAIN.md` |
147
148
  | Constituent fields and ordering | `docs/CONSTITUENTA.md` |
148
149
  | Portal REST API | `docs/PORTAL-API.md` |
package/skills/rstool-helper/SKILL.md CHANGED
@@ -20,13 +20,11 @@ Then continue with the canonical files below.
20
20
 
21
21
  ## Canonical files (read before rstool work)
22
22
 
23
- | What | Path |
24
- | :--- | :--- |
25
- | **Start here** — workflow, cstType, S# vs D# | `node_modules/@rsconcept/rstool/skills/rstool-helper/GUIDE.md` |
26
- | API, stdio, contract | `node_modules/@rsconcept/rstool/skills/rstool-helper/REFERENCE.md` |
27
- | Examples, pitfalls | `node_modules/@rsconcept/rstool/skills/rstool-helper/EXAMPLES.md` |
28
- | Language / domain docs | `node_modules/@rsconcept/rstool/docs/*.md` |
29
- | Install procedure | `node_modules/@rsconcept/rstool/skills/INSTALL.md` |
23
+ - **Start here** — workflow: `node_modules/@rsconcept/rstool/skills/rstool-helper/GUIDE.md`
24
+ - API, stdio, contract: `node_modules/@rsconcept/rstool/skills/rstool-helper/REFERENCE.md`
25
+ - Examples, pitfalls: `node_modules/@rsconcept/rstool/skills/rstool-helper/EXAMPLES.md`
26
+ - Language / domain docs: `node_modules/@rsconcept/rstool/docs/*.md`
27
+ - Install procedure: `node_modules/@rsconcept/rstool/skills/INSTALL.md`
30
28
 
31
29
  Always open **GUIDE.md** first when starting a rstool task, then **REFERENCE.md** / **EXAMPLES.md** / relevant `docs/*.md` as needed.
32
30
 
@@ -34,4 +32,3 @@ Always open **GUIDE.md** first when starting a rstool task, then **REFERENCE.md*
34
32
 
35
33
  - Package: `@rsconcept/rstool`; wrapper: `npx rstool-wrapper`
36
34
  - `@rsconcept/domain` is installed as a dependency (analyzer, errors in `src/rslang/error.ts`)
37
- - Do not copy GUIDE, REFERENCE, EXAMPLES, or `docs/` into the project skills folder — read them from `node_modules` paths above