positorium 0.1.4b2__tar.gz
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.
- positorium-0.1.4b2/.github/FUNDING.yml +12 -0
- positorium-0.1.4b2/.github/ISSUE_TEMPLATE/beta-feedback.yml +52 -0
- positorium-0.1.4b2/.github/ISSUE_TEMPLATE/bug-report.yml +52 -0
- positorium-0.1.4b2/.github/ISSUE_TEMPLATE/config.yml +5 -0
- positorium-0.1.4b2/.github/copilot-instructions.md +106 -0
- positorium-0.1.4b2/.github/workflows/ci.yml +57 -0
- positorium-0.1.4b2/.github/workflows/pages.yml +71 -0
- positorium-0.1.4b2/.github/workflows/python.yml +197 -0
- positorium-0.1.4b2/.github/workflows/release.yml +188 -0
- positorium-0.1.4b2/.gitignore +48 -0
- positorium-0.1.4b2/.vscode/launch.json +45 -0
- positorium-0.1.4b2/Cargo.lock +2078 -0
- positorium-0.1.4b2/Cargo.toml +65 -0
- positorium-0.1.4b2/LICENSE.Apache-2.0 +201 -0
- positorium-0.1.4b2/LICENSE.MIT +21 -0
- positorium-0.1.4b2/PKG-INFO +201 -0
- positorium-0.1.4b2/README.md +165 -0
- positorium-0.1.4b2/Traqula.svg +40 -0
- positorium-0.1.4b2/benches/benchmark.rs +444 -0
- positorium-0.1.4b2/docs/GETTING_STARTED.md +233 -0
- positorium-0.1.4b2/docs/README.md +46 -0
- positorium-0.1.4b2/docs/design/THEORY.md +153 -0
- positorium-0.1.4b2/docs/development/BENCHMARKS.md +78 -0
- positorium-0.1.4b2/docs/development/DECISIONS.md +1515 -0
- positorium-0.1.4b2/docs/development/EXTEND_TRAQULA.md +756 -0
- positorium-0.1.4b2/docs/development/ROADMAP.md +572 -0
- positorium-0.1.4b2/docs/development/TERRAIN_BACKEND_SPEC.md +739 -0
- positorium-0.1.4b2/docs/guides/BLACKTHORN_CASE.md +203 -0
- positorium-0.1.4b2/docs/guides/COOKBOOK.md +192 -0
- positorium-0.1.4b2/docs/guides/OPERATIONS.md +119 -0
- positorium-0.1.4b2/docs/guides/PYTHON.md +179 -0
- positorium-0.1.4b2/docs/reference/CONTRACTS.md +55 -0
- positorium-0.1.4b2/docs/reference/MODEL.md +196 -0
- positorium-0.1.4b2/docs/reference/STORAGE.md +315 -0
- positorium-0.1.4b2/docs/reference/TERRAIN.md +211 -0
- positorium-0.1.4b2/docs/reference/TRANSFER.md +99 -0
- positorium-0.1.4b2/docs/reference/TRAQULA.md +395 -0
- positorium-0.1.4b2/docs/releases/v0.1.4-beta.1.md +43 -0
- positorium-0.1.4b2/docs/releases/v0.1.4-beta.2.md +49 -0
- positorium-0.1.4b2/og.png +0 -0
- positorium-0.1.4b2/og.svg +70 -0
- positorium-0.1.4b2/positorium-terrain.css +817 -0
- positorium-0.1.4b2/positorium-terrain.js +1438 -0
- positorium-0.1.4b2/positorium.css +1440 -0
- positorium-0.1.4b2/positorium.html +1179 -0
- positorium-0.1.4b2/positorium.json +8 -0
- positorium-0.1.4b2/positorium.svg +127 -0
- positorium-0.1.4b2/positorium_1280.png +0 -0
- positorium-0.1.4b2/positorium_1280.svg +155 -0
- positorium-0.1.4b2/positorium_web_app.png +0 -0
- positorium-0.1.4b2/pyproject.toml +50 -0
- positorium-0.1.4b2/python/positorium/__init__.py +73 -0
- positorium-0.1.4b2/python/positorium/_api.py +449 -0
- positorium-0.1.4b2/python/positorium/_native.pyi +43 -0
- positorium-0.1.4b2/python/positorium/py.typed +1 -0
- positorium-0.1.4b2/relational_model.png +0 -0
- positorium-0.1.4b2/rust-toolchain.toml +4 -0
- positorium-0.1.4b2/scripts/positorium.ps1 +131 -0
- positorium-0.1.4b2/scripts/positorium.sh +159 -0
- positorium-0.1.4b2/sql/posits.sql +42 -0
- positorium-0.1.4b2/src/bin/positorium-store.rs +57 -0
- positorium-0.1.4b2/src/construct.rs +1470 -0
- positorium-0.1.4b2/src/datatype.rs +552 -0
- positorium-0.1.4b2/src/effect.rs +403 -0
- positorium-0.1.4b2/src/error.rs +56 -0
- positorium-0.1.4b2/src/interface.rs +359 -0
- positorium-0.1.4b2/src/lib.rs +97 -0
- positorium-0.1.4b2/src/literal.rs +420 -0
- positorium-0.1.4b2/src/main.rs +209 -0
- positorium-0.1.4b2/src/maintenance.rs +855 -0
- positorium-0.1.4b2/src/python.rs +262 -0
- positorium-0.1.4b2/src/server.rs +1151 -0
- positorium-0.1.4b2/src/storage.rs +2262 -0
- positorium-0.1.4b2/src/terrain.rs +1400 -0
- positorium-0.1.4b2/src/traqula/query.rs +2027 -0
- positorium-0.1.4b2/src/traqula.pest +108 -0
- positorium-0.1.4b2/src/traqula.rs +3919 -0
- positorium-0.1.4b2/src/wasm.rs +302 -0
- positorium-0.1.4b2/tests/classification.rs +96 -0
- positorium-0.1.4b2/tests/conditional_mutation.rs +464 -0
- positorium-0.1.4b2/tests/contract_versions.rs +23 -0
- positorium-0.1.4b2/tests/core_contracts.rs +189 -0
- positorium-0.1.4b2/tests/core_properties.rs +135 -0
- positorium-0.1.4b2/tests/cross_search_binding.rs +27 -0
- positorium-0.1.4b2/tests/documentation.rs +172 -0
- positorium-0.1.4b2/tests/editor_grammar.rs +71 -0
- positorium-0.1.4b2/tests/example_scripts.rs +205 -0
- positorium-0.1.4b2/tests/execution_context.rs +53 -0
- positorium-0.1.4b2/tests/execution_limits.rs +81 -0
- positorium-0.1.4b2/tests/in_effect.rs +416 -0
- positorium-0.1.4b2/tests/limit_clause.rs +34 -0
- positorium-0.1.4b2/tests/literal_values.rs +72 -0
- positorium-0.1.4b2/tests/maintenance_tools.rs +252 -0
- positorium-0.1.4b2/tests/multi_search_limits.rs +28 -0
- positorium-0.1.4b2/tests/persistence_modes.rs +193 -0
- positorium-0.1.4b2/tests/predicates.rs +126 -0
- positorium-0.1.4b2/tests/query_algebra.rs +246 -0
- positorium-0.1.4b2/tests/result_contract.rs +23 -0
- positorium-0.1.4b2/tests/single_married_snapshot.rs +25 -0
- positorium-0.1.4b2/tests/terrain_client.test.js +215 -0
- positorium-0.1.4b2/tests/terrain_contract.rs +424 -0
- positorium-0.1.4b2/tests/terrain_fixture.rs +143 -0
- positorium-0.1.4b2/tests/test_python.py +142 -0
- positorium-0.1.4b2/tests/time_filters.rs +84 -0
- positorium-0.1.4b2/tests/traqula_literals.rs +182 -0
- positorium-0.1.4b2/tests/value_var_comparisons.rs +90 -0
- positorium-0.1.4b2/theory/older_paper.tex +974 -0
- positorium-0.1.4b2/theory/oldest_paper.tex +755 -0
- positorium-0.1.4b2/theory/recent_paper.tex +782 -0
- positorium-0.1.4b2/traqula/adds.traqula +27 -0
- positorium-0.1.4b2/traqula/blackthorn.traqula +639 -0
- positorium-0.1.4b2/traqula/cross-search.traqula +13 -0
- positorium-0.1.4b2/traqula/empty.traqula +0 -0
- positorium-0.1.4b2/traqula/multi-match.traqula +12 -0
- positorium-0.1.4b2/traqula/searches.traqula +69 -0
- positorium-0.1.4b2/traqula/terrain.traqula +40 -0
- positorium-0.1.4b2/traqula/timetest.traqula +54 -0
- positorium-0.1.4b2/traqula/welcome.traqula +82 -0
- positorium-0.1.4b2/traqula-vscode/.vscode/launch.json +11 -0
- positorium-0.1.4b2/traqula-vscode/[Content_Types].xml +7 -0
- positorium-0.1.4b2/traqula-vscode/extension/language-configuration.json +22 -0
- positorium-0.1.4b2/traqula-vscode/extension/package.json +29 -0
- positorium-0.1.4b2/traqula-vscode/extension/syntaxes/traqula.tmLanguage.json +113 -0
- positorium-0.1.4b2/traqula-vscode/extension.vsixmanifest +21 -0
- positorium-0.1.4b2/traqula-vscode/language-configuration.json +22 -0
- positorium-0.1.4b2/traqula-vscode/package.json +29 -0
- positorium-0.1.4b2/traqula-vscode/syntaxes/traqula.tmLanguage.json +113 -0
- positorium-0.1.4b2/traqula-vscode/traqula-syntax-0.0.1.vsix +0 -0
- positorium-0.1.4b2/wasm_analysis.ipynb +46 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# These are supported funding model platforms
|
|
2
|
+
|
|
3
|
+
github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
|
|
4
|
+
patreon: # Replace with a single Patreon username
|
|
5
|
+
open_collective: # Replace with a single Open Collective username
|
|
6
|
+
ko_fi: positorium
|
|
7
|
+
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
|
|
8
|
+
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
|
|
9
|
+
liberapay: # Replace with a single Liberapay username
|
|
10
|
+
issuehunt: # Replace with a single IssueHunt username
|
|
11
|
+
otechie: # Replace with a single Otechie username
|
|
12
|
+
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
name: Beta feedback or use case
|
|
2
|
+
description: Tell us about conflicting or evolving information you want to preserve.
|
|
3
|
+
title: "[Feedback]: "
|
|
4
|
+
labels: ["feedback"]
|
|
5
|
+
body:
|
|
6
|
+
- type: markdown
|
|
7
|
+
attributes:
|
|
8
|
+
value: |
|
|
9
|
+
Positorium is looking for concrete evidence, compliance, investigation,
|
|
10
|
+
and master-data workflows. A small real example is more useful than a
|
|
11
|
+
polished feature request.
|
|
12
|
+
- type: textarea
|
|
13
|
+
id: situation
|
|
14
|
+
attributes:
|
|
15
|
+
label: What information disagrees or changes?
|
|
16
|
+
description: Describe the sources, revisions, uncertainty, or historical questions involved.
|
|
17
|
+
placeholder: Two screening providers disagree about an organisation, and an analyst may later retract one assessment…
|
|
18
|
+
validations:
|
|
19
|
+
required: true
|
|
20
|
+
- type: textarea
|
|
21
|
+
id: current-approach
|
|
22
|
+
attributes:
|
|
23
|
+
label: How do you handle it today?
|
|
24
|
+
description: A schema sketch or short pseudocode example is welcome. Please remove private data.
|
|
25
|
+
validations:
|
|
26
|
+
required: true
|
|
27
|
+
- type: textarea
|
|
28
|
+
id: outcome
|
|
29
|
+
attributes:
|
|
30
|
+
label: What would make Positorium useful here?
|
|
31
|
+
description: Describe the query, integration, or operational outcome you need.
|
|
32
|
+
validations:
|
|
33
|
+
required: true
|
|
34
|
+
- type: dropdown
|
|
35
|
+
id: tried
|
|
36
|
+
attributes:
|
|
37
|
+
label: Have you tried Positorium?
|
|
38
|
+
options:
|
|
39
|
+
- Browser quick example
|
|
40
|
+
- Browser detective case
|
|
41
|
+
- Native release
|
|
42
|
+
- Source checkout
|
|
43
|
+
- Python source package
|
|
44
|
+
- Not yet
|
|
45
|
+
validations:
|
|
46
|
+
required: true
|
|
47
|
+
- type: checkboxes
|
|
48
|
+
id: follow-up
|
|
49
|
+
attributes:
|
|
50
|
+
label: Follow-up
|
|
51
|
+
options:
|
|
52
|
+
- label: I am open to follow-up questions on this public issue.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: Report reproducible beta behavior without including sensitive data.
|
|
3
|
+
title: "[Bug]: "
|
|
4
|
+
labels: ["bug"]
|
|
5
|
+
body:
|
|
6
|
+
- type: input
|
|
7
|
+
id: version
|
|
8
|
+
attributes:
|
|
9
|
+
label: Version or commit
|
|
10
|
+
placeholder: v0.1.4-beta.1 or a commit hash
|
|
11
|
+
validations:
|
|
12
|
+
required: true
|
|
13
|
+
- type: dropdown
|
|
14
|
+
id: interface
|
|
15
|
+
attributes:
|
|
16
|
+
label: Interface
|
|
17
|
+
options:
|
|
18
|
+
- Browser WASM
|
|
19
|
+
- Rust API
|
|
20
|
+
- Python
|
|
21
|
+
- HTTP
|
|
22
|
+
- SSE
|
|
23
|
+
- Store maintenance CLI
|
|
24
|
+
validations:
|
|
25
|
+
required: true
|
|
26
|
+
- type: input
|
|
27
|
+
id: platform
|
|
28
|
+
attributes:
|
|
29
|
+
label: Platform
|
|
30
|
+
placeholder: macOS Apple Silicon, Linux x86-64, or Windows x86-64
|
|
31
|
+
validations:
|
|
32
|
+
required: true
|
|
33
|
+
- type: textarea
|
|
34
|
+
id: script
|
|
35
|
+
attributes:
|
|
36
|
+
label: Smallest reproducing script
|
|
37
|
+
render: traqula
|
|
38
|
+
validations:
|
|
39
|
+
required: true
|
|
40
|
+
- type: textarea
|
|
41
|
+
id: expected
|
|
42
|
+
attributes:
|
|
43
|
+
label: Expected behavior
|
|
44
|
+
validations:
|
|
45
|
+
required: true
|
|
46
|
+
- type: textarea
|
|
47
|
+
id: actual
|
|
48
|
+
attributes:
|
|
49
|
+
label: Actual behavior
|
|
50
|
+
description: Include a short error or log excerpt after removing secrets and sensitive literal values.
|
|
51
|
+
validations:
|
|
52
|
+
required: true
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Positorium AI Coding Guidelines
|
|
2
|
+
|
|
3
|
+
## Architecture Overview
|
|
4
|
+
Positorium is a database engine implementing Transitional Modeling concepts for handling conflicting, unreliable, and varying information over time. The core data model consists of:
|
|
5
|
+
|
|
6
|
+
- Thing: opaque u64 identity
|
|
7
|
+
- Role: named semantic placeholder (e.g., "wife", "name")
|
|
8
|
+
- Appearance: (Thing, Role) pairing
|
|
9
|
+
- AppearanceSet: sorted, duplicate-free set of appearances (at most one per role)
|
|
10
|
+
- Posit: proposition of (AppearanceSet, Value, Time) with its own Thing identity
|
|
11
|
+
|
|
12
|
+
All constructs follow a keeper pattern for canonical storage and deduplication using Arc-wrapped instances.
|
|
13
|
+
|
|
14
|
+
## Modules and Key Components
|
|
15
|
+
- `src/lib.rs`: Crate-level docs and module wiring.
|
|
16
|
+
- `src/construct.rs`: Core data structures and keepers (`Database`, `RoleKeeper`, `AppearanceKeeper`, `AppearanceSetKeeper`, `PositKeeper`), lookups, identity generator.
|
|
17
|
+
- `src/datatype.rs`: `DataType` trait and built-ins: `String`, `i64`, `Decimal`, `JSON`, `Time`, `Certainty`.
|
|
18
|
+
- `src/storage.rs`: Private append-only framing, commit, replay, locking, and recovery machinery.
|
|
19
|
+
- `src/maintenance.rs`: Validated inspection, physical backup, and versioned logical transfer.
|
|
20
|
+
- `src/traqula.rs` and `src/traqula/query.rs`: Pest-based parser and execution engine for the Traqula DSL.
|
|
21
|
+
- `src/traqula.pest`: Grammar definition for the query language.
|
|
22
|
+
- `src/interface.rs`: Serialized query interface with cooperative cancellation and optional streaming of results.
|
|
23
|
+
- `src/error.rs`: Domain-specific error types (`DatabaseError`) and conversions.
|
|
24
|
+
- `src/server.rs`: Trusted-local HTTP and SSE service implemented with Axum.
|
|
25
|
+
- `benches/benchmark.rs`: Criterion-based performance benchmarks.
|
|
26
|
+
- `traqula-vscode/`: Syntax highlighting extension for Traqula (keep grammar in sync with `traqula.pest`).
|
|
27
|
+
- `positorium.html`, `positorium.css`, and `positorium-terrain.*`: Static Query Studio and Terrain client; these are deployed separately from the native HTTP service.
|
|
28
|
+
|
|
29
|
+
## Development Workflow
|
|
30
|
+
- Build: use `cargo build` (Rust edition 2024).
|
|
31
|
+
- Run: prefer `cargo run` (the binary reads `positorium.json` and starts the HTTP service on the configured interface and port; it does not serve the static Query Studio).
|
|
32
|
+
- Config (`positorium.json`):
|
|
33
|
+
- `database_file_and_path`: append-only store directory (created if missing).
|
|
34
|
+
- `enable_persistence`: optional `true|false`; false selects an ephemeral in-memory engine.
|
|
35
|
+
- `recreate_database_on_startup`: `true|false` to remove the store directory at startup.
|
|
36
|
+
- `traqula_file_to_run_on_startup`: path to a Traqula script executed on boot.
|
|
37
|
+
- `listen_interface`: IP address to bind the HTTP server (default: "127.0.0.1").
|
|
38
|
+
- `listen_port`: Port number for the HTTP server (default: 8080).
|
|
39
|
+
- Diagnostics use `tracing`; startup and boundary failures are returned rather than printed and ignored.
|
|
40
|
+
|
|
41
|
+
## Coding Patterns
|
|
42
|
+
- Keeper pattern: roles, appearances, appearance sets, and posits are canonicalized internally. Keep mutation helpers crate-private and route public writes through versioned Traqula execution.
|
|
43
|
+
- Identity management: things and posits are identities; allocate them only through the crate-private database mutation path so replay, durability, and collision checks stay coupled.
|
|
44
|
+
- AppearanceSet ordering: maintain sorted order by `(role, thing)`; ensure at most one appearance per role (enforced by `AppearanceSet::new`).
|
|
45
|
+
- Data type indexing: record data types per role set in `role_name_to_data_type_lookup` to avoid runtime type probing.
|
|
46
|
+
- Bitmaps: use roaring bitmaps (`RoaringTreemap`) for set operations; prefer union/intersection methods over per-element loops.
|
|
47
|
+
- Time is built-in: every posit includes a `Time`; use constants `@NOW`, `@BOT`, `@EOT` and accepted literals (year, year-month, date, datetime).
|
|
48
|
+
- Hasher choice: use `SeaHasher` (`BuildHasherDefault`) for hash maps/sets of non-Thing keys to keep hashing consistent with existing lookups.
|
|
49
|
+
|
|
50
|
+
## Traqula DSL Notes
|
|
51
|
+
- `+var` allocates during mutation, bare `var` recalls a mutation binding, and `?var` is lexical to one search. `*` consumes one anonymous field and `...` opens an appearance-set pattern.
|
|
52
|
+
- Pattern matching is declarative and mirrors posit insertion structure; source pattern order must not change natural-join meaning.
|
|
53
|
+
- Typed predicates support exact literal identity (`===`), nominal equality (`=`), compatible overlap (`?=`), and the documented numeric, certainty, string, JSON, and temporal relations.
|
|
54
|
+
- `search ... or add posit ...` is the only compound that promotes matching identities into mutation scope. Validate both branches and the return shape before evaluation or sink callbacks.
|
|
55
|
+
- Result sets use tri-state `ResultSetMode` (Empty/Thing/Multi) backed by roaring bitmaps for efficient set algebra.
|
|
56
|
+
|
|
57
|
+
## Persistence Contract
|
|
58
|
+
- The first published backend is the versioned append-only store specified in `docs/reference/STORAGE.md`.
|
|
59
|
+
- A store directory contains `manifest.pmf`, `store.lock`, and framed `.ptl` log segments.
|
|
60
|
+
- Each mutation command is one logical batch terminated by a Commit record. The manifest exposes only the flushed committed prefix.
|
|
61
|
+
- Replay validates headers, checksums, sequence numbers, batches, canonical encodings, identity invariants, and resource bounds before rebuilding in-memory indexes.
|
|
62
|
+
- Physical codecs are private. Logical transfer preserves lossless literal tokens through the versioned JSONL contract in `docs/reference/TRANSFER.md`.
|
|
63
|
+
- There is no SQLite compatibility boundary, importer, dependency, or migration path: no Positorium release used the prototype backend (D031).
|
|
64
|
+
|
|
65
|
+
### Operational persistence behavior
|
|
66
|
+
- Startup: validated replay reconstructs keepers, lookups, and the identity generator before the engine accepts work. Corruption and unsupported formats fail closed.
|
|
67
|
+
- Writes: persistence appends each successful mutation command as one durable batch before publishing it to in-memory state.
|
|
68
|
+
- Ownership: one `Database` owns one store and one execution mutex; query interfaces sharing it serialize execution. The OS store lock rejects a second writer.
|
|
69
|
+
|
|
70
|
+
### DataType maintenance
|
|
71
|
+
When adding a literal family or representation:
|
|
72
|
+
- Preserve the exact source token and update `LiteralFamily` behavior explicitly.
|
|
73
|
+
- Keep storage codec identifiers private and stable; add a codec only with complete bounded decoding and replay validation.
|
|
74
|
+
- Update logical transfer, structured-result, comparison, property, and malformed-input tests together.
|
|
75
|
+
|
|
76
|
+
## Performance Considerations
|
|
77
|
+
- Roaring bitmaps enable fast set operations without exploding joins.
|
|
78
|
+
- Indexes maintained: role→posit, appearance_set→posit, posit→appearance_set, posit→time, plus role-name→datatype partitions.
|
|
79
|
+
- Candidate tracking per bound variable (value variables, time variables) is used during search.
|
|
80
|
+
- Avoid premature allocation by relying on `ResultSetMode` and in-place roaring operations.
|
|
81
|
+
|
|
82
|
+
## Concurrency and Interface
|
|
83
|
+
`src/interface.rs` provides a query interface with bounded execution-lock waiting, cooperative cancellation, and optional streaming. `src/server.rs` implements an Axum HTTP/SSE boundary. All frontends sharing a `Database` use its execution owner, so separately created interfaces cannot bypass serialization.
|
|
84
|
+
- File-backed and in-memory modes have the same logical execution semantics.
|
|
85
|
+
- Cancellation is cooperative and must be checked at bounded points in parsing, command execution, result production, and execution-lock waiting.
|
|
86
|
+
- Shutdown stops intake, finishes or cancels active work according to the boundary contract, and flushes the owned store.
|
|
87
|
+
|
|
88
|
+
## Error Handling
|
|
89
|
+
Domain-specific errors (`DatabaseError`) are defined in `error.rs` with variants for config, persistence, data corruption, parse, execution, invariant, and lock errors. Propagate or extend this type for new boundary failures.
|
|
90
|
+
|
|
91
|
+
## Testing and Benchmarks
|
|
92
|
+
- Match CI with `cargo test --all-targets --all-features --no-fail-fast` and `cargo test --all-targets --no-default-features --no-fail-fast`.
|
|
93
|
+
- Run both Clippy feature matrices with `-D warnings`, formatting checks, the Terrain JavaScript test, and the browser WASM suite for boundary changes.
|
|
94
|
+
- Use Criterion benchmarks in `benches/benchmark.rs` (`cargo bench`) for architectural performance measurements.
|
|
95
|
+
|
|
96
|
+
## Contributor PR Checklist
|
|
97
|
+
- Builds cleanly: `cargo build` (and optionally `cargo clippy`, `cargo fmt`).
|
|
98
|
+
- Doctests pass: `cargo test`.
|
|
99
|
+
- If grammar changed: update `traqula.pest` and keep `traqula-vscode/` syntax in sync.
|
|
100
|
+
- If changing literal behavior: update lossless transfer, comparison, result, and malformed-input tests.
|
|
101
|
+
- If touching persistence: follow `docs/reference/STORAGE.md`; preserve atomic batches, fail-closed replay, and bounded decoding. Do not add SQLite compatibility work.
|
|
102
|
+
- Keepers & lookups: keep construction internal and update canonical keepers plus every dependent lookup atomically.
|
|
103
|
+
- Add minimal examples in `docs/` or an appropriate `traqula/*.traqula` fixture when introducing new syntax or behavior.
|
|
104
|
+
|
|
105
|
+
## License
|
|
106
|
+
Dual licensed under Apache-2.0 and MIT (see `LICENSE.*`).
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
contents: read
|
|
9
|
+
|
|
10
|
+
env:
|
|
11
|
+
CARGO_TERM_COLOR: always
|
|
12
|
+
RUST_BACKTRACE: "1"
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
native:
|
|
16
|
+
name: Native (${{ matrix.os }})
|
|
17
|
+
strategy:
|
|
18
|
+
fail-fast: false
|
|
19
|
+
matrix:
|
|
20
|
+
os: [ubuntu-latest, macos-latest, windows-latest]
|
|
21
|
+
runs-on: ${{ matrix.os }}
|
|
22
|
+
steps:
|
|
23
|
+
- uses: actions/checkout@v4
|
|
24
|
+
- name: Install stable Rust
|
|
25
|
+
run: rustup show active-toolchain
|
|
26
|
+
- name: Test default feature set
|
|
27
|
+
run: cargo test --all-targets --all-features --no-fail-fast
|
|
28
|
+
- name: Test in-memory feature set
|
|
29
|
+
run: cargo test --all-targets --no-default-features --no-fail-fast
|
|
30
|
+
|
|
31
|
+
quality:
|
|
32
|
+
name: Formatting and lints
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
steps:
|
|
35
|
+
- uses: actions/checkout@v4
|
|
36
|
+
- name: Install stable Rust components
|
|
37
|
+
run: rustup component add rustfmt clippy
|
|
38
|
+
- name: Check formatting
|
|
39
|
+
run: cargo fmt --all -- --check
|
|
40
|
+
- name: Lint all features
|
|
41
|
+
run: cargo clippy --all-targets --all-features -- -D warnings
|
|
42
|
+
- name: Lint in-memory feature set
|
|
43
|
+
run: cargo clippy --all-targets --no-default-features -- -D warnings
|
|
44
|
+
|
|
45
|
+
wasm:
|
|
46
|
+
name: WASM
|
|
47
|
+
runs-on: ubuntu-latest
|
|
48
|
+
steps:
|
|
49
|
+
- uses: actions/checkout@v4
|
|
50
|
+
- name: Install stable WASM target
|
|
51
|
+
run: rustup target add wasm32-unknown-unknown
|
|
52
|
+
- name: Check in-memory WASM build
|
|
53
|
+
run: cargo check --target wasm32-unknown-unknown --no-default-features --features wasm
|
|
54
|
+
- name: Install wasm-pack
|
|
55
|
+
run: cargo install wasm-pack --locked --version 0.14.0
|
|
56
|
+
- name: Run browser smoke tests
|
|
57
|
+
run: wasm-pack test --headless --chrome . --no-default-features --features wasm
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
name: WASM testbed
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_dispatch:
|
|
5
|
+
push:
|
|
6
|
+
branches: [master]
|
|
7
|
+
paths:
|
|
8
|
+
- "src/**"
|
|
9
|
+
- "Cargo.toml"
|
|
10
|
+
- "Cargo.lock"
|
|
11
|
+
- "positorium.html"
|
|
12
|
+
- "positorium.css"
|
|
13
|
+
- "positorium-terrain.js"
|
|
14
|
+
- "positorium-terrain.css"
|
|
15
|
+
- "traqula/terrain.traqula"
|
|
16
|
+
- "traqula/welcome.traqula"
|
|
17
|
+
- "traqula/blackthorn.traqula"
|
|
18
|
+
- "tests/terrain_client.test.js"
|
|
19
|
+
- "tests/terrain_fixture.rs"
|
|
20
|
+
- "og.png"
|
|
21
|
+
- ".github/workflows/pages.yml"
|
|
22
|
+
|
|
23
|
+
permissions:
|
|
24
|
+
contents: read
|
|
25
|
+
pages: write
|
|
26
|
+
id-token: write
|
|
27
|
+
|
|
28
|
+
concurrency:
|
|
29
|
+
group: pages
|
|
30
|
+
cancel-in-progress: true
|
|
31
|
+
|
|
32
|
+
jobs:
|
|
33
|
+
build-and-test:
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@v6
|
|
37
|
+
- name: Terrain client aggregation test
|
|
38
|
+
run: node tests/terrain_client.test.js
|
|
39
|
+
- name: Terrain Traqula fixture test
|
|
40
|
+
run: cargo test --test terrain_fixture
|
|
41
|
+
- run: rustup target add wasm32-unknown-unknown
|
|
42
|
+
- name: Install wasm-pack
|
|
43
|
+
run: cargo install wasm-pack --locked --version 0.14.0
|
|
44
|
+
- name: Browser smoke tests
|
|
45
|
+
run: wasm-pack test --headless --chrome . --no-default-features --features wasm
|
|
46
|
+
- name: Build web package
|
|
47
|
+
run: wasm-pack build --release --target web --out-dir pkg . --no-default-features --features wasm
|
|
48
|
+
- name: Assemble zero-install testbed
|
|
49
|
+
shell: bash
|
|
50
|
+
run: |
|
|
51
|
+
mkdir site
|
|
52
|
+
mkdir -p site/traqula
|
|
53
|
+
cp positorium.html site/index.html
|
|
54
|
+
cp positorium.css positorium-terrain.css positorium-terrain.js og.png site/
|
|
55
|
+
cp traqula/terrain.traqula traqula/welcome.traqula traqula/blackthorn.traqula site/traqula/
|
|
56
|
+
cp -R pkg site/pkg
|
|
57
|
+
- uses: actions/configure-pages@v6
|
|
58
|
+
- uses: actions/upload-pages-artifact@v5
|
|
59
|
+
with:
|
|
60
|
+
path: site
|
|
61
|
+
|
|
62
|
+
deploy:
|
|
63
|
+
needs: build-and-test
|
|
64
|
+
runs-on: ubuntu-latest
|
|
65
|
+
environment:
|
|
66
|
+
name: github-pages
|
|
67
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
68
|
+
steps:
|
|
69
|
+
- name: Deploy GitHub Pages
|
|
70
|
+
id: deployment
|
|
71
|
+
uses: actions/deploy-pages@v5
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
name: Python
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [master]
|
|
6
|
+
tags: ["v[0-9]*.[0-9]*.[0-9]*"]
|
|
7
|
+
pull_request:
|
|
8
|
+
workflow_dispatch:
|
|
9
|
+
|
|
10
|
+
permissions:
|
|
11
|
+
contents: read
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
test:
|
|
15
|
+
name: Python ${{ matrix.python-version }} behavior
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
strategy:
|
|
18
|
+
fail-fast: false
|
|
19
|
+
matrix:
|
|
20
|
+
python-version: ["3.9", "3.14"]
|
|
21
|
+
steps:
|
|
22
|
+
- uses: actions/checkout@v4
|
|
23
|
+
- uses: actions/setup-python@v5
|
|
24
|
+
with:
|
|
25
|
+
python-version: ${{ matrix.python-version }}
|
|
26
|
+
- uses: dtolnay/rust-toolchain@stable
|
|
27
|
+
- name: Build native wheel
|
|
28
|
+
uses: PyO3/maturin-action@v1
|
|
29
|
+
with:
|
|
30
|
+
command: build
|
|
31
|
+
args: --release --locked --out dist
|
|
32
|
+
manylinux: auto
|
|
33
|
+
- name: Install wheel
|
|
34
|
+
run: python -m pip install --force-reinstall dist/*.whl
|
|
35
|
+
- name: Run Python behavior tests
|
|
36
|
+
run: python -m unittest tests/test_python.py
|
|
37
|
+
- name: Verify installed contract
|
|
38
|
+
run: >-
|
|
39
|
+
python -c "import positorium; assert positorium.PYTHON_INTERFACE_VERSION == 1;
|
|
40
|
+
assert positorium.TRAQULA_VERSION == 1;
|
|
41
|
+
assert positorium.__version__.replace('b', '-beta.') == positorium.RUST_PACKAGE_VERSION"
|
|
42
|
+
|
|
43
|
+
linux:
|
|
44
|
+
name: Linux ${{ matrix.target }} wheel
|
|
45
|
+
runs-on: ubuntu-22.04
|
|
46
|
+
strategy:
|
|
47
|
+
fail-fast: false
|
|
48
|
+
matrix:
|
|
49
|
+
target: [x86_64, aarch64]
|
|
50
|
+
steps:
|
|
51
|
+
- uses: actions/checkout@v4
|
|
52
|
+
- uses: actions/setup-python@v5
|
|
53
|
+
with:
|
|
54
|
+
python-version: "3.9"
|
|
55
|
+
- name: Build manylinux wheel
|
|
56
|
+
uses: PyO3/maturin-action@v1
|
|
57
|
+
with:
|
|
58
|
+
target: ${{ matrix.target }}
|
|
59
|
+
args: --release --locked --out dist
|
|
60
|
+
manylinux: auto
|
|
61
|
+
sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
|
|
62
|
+
- uses: actions/upload-artifact@v4
|
|
63
|
+
with:
|
|
64
|
+
name: python-dist-manylinux-${{ matrix.target }}
|
|
65
|
+
path: dist/*.whl
|
|
66
|
+
if-no-files-found: error
|
|
67
|
+
|
|
68
|
+
musllinux:
|
|
69
|
+
name: musllinux ${{ matrix.target }} wheel
|
|
70
|
+
runs-on: ubuntu-22.04
|
|
71
|
+
strategy:
|
|
72
|
+
fail-fast: false
|
|
73
|
+
matrix:
|
|
74
|
+
target: [x86_64, aarch64]
|
|
75
|
+
steps:
|
|
76
|
+
- uses: actions/checkout@v4
|
|
77
|
+
- uses: actions/setup-python@v5
|
|
78
|
+
with:
|
|
79
|
+
python-version: "3.9"
|
|
80
|
+
- name: Build musllinux wheel
|
|
81
|
+
uses: PyO3/maturin-action@v1
|
|
82
|
+
with:
|
|
83
|
+
target: ${{ matrix.target }}
|
|
84
|
+
args: --release --locked --out dist
|
|
85
|
+
manylinux: musllinux_1_2
|
|
86
|
+
sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
|
|
87
|
+
- uses: actions/upload-artifact@v4
|
|
88
|
+
with:
|
|
89
|
+
name: python-dist-musllinux-${{ matrix.target }}
|
|
90
|
+
path: dist/*.whl
|
|
91
|
+
if-no-files-found: error
|
|
92
|
+
|
|
93
|
+
windows:
|
|
94
|
+
name: Windows x64 wheel
|
|
95
|
+
runs-on: windows-latest
|
|
96
|
+
steps:
|
|
97
|
+
- uses: actions/checkout@v4
|
|
98
|
+
- uses: actions/setup-python@v5
|
|
99
|
+
with:
|
|
100
|
+
python-version: "3.9"
|
|
101
|
+
architecture: x64
|
|
102
|
+
- name: Build Windows wheel
|
|
103
|
+
uses: PyO3/maturin-action@v1
|
|
104
|
+
with:
|
|
105
|
+
target: x64
|
|
106
|
+
args: --release --locked --out dist
|
|
107
|
+
sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
|
|
108
|
+
- uses: actions/upload-artifact@v4
|
|
109
|
+
with:
|
|
110
|
+
name: python-dist-windows-x64
|
|
111
|
+
path: dist/*.whl
|
|
112
|
+
if-no-files-found: error
|
|
113
|
+
|
|
114
|
+
macos:
|
|
115
|
+
name: macOS ${{ matrix.target }} wheel
|
|
116
|
+
runs-on: ${{ matrix.runner }}
|
|
117
|
+
strategy:
|
|
118
|
+
fail-fast: false
|
|
119
|
+
matrix:
|
|
120
|
+
include:
|
|
121
|
+
- runner: macos-15-intel
|
|
122
|
+
target: x86_64
|
|
123
|
+
- runner: macos-14
|
|
124
|
+
target: aarch64
|
|
125
|
+
steps:
|
|
126
|
+
- uses: actions/checkout@v4
|
|
127
|
+
- uses: actions/setup-python@v5
|
|
128
|
+
with:
|
|
129
|
+
python-version: "3.9"
|
|
130
|
+
- name: Build macOS wheel
|
|
131
|
+
uses: PyO3/maturin-action@v1
|
|
132
|
+
with:
|
|
133
|
+
target: ${{ matrix.target }}
|
|
134
|
+
args: --release --locked --out dist
|
|
135
|
+
sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
|
|
136
|
+
- uses: actions/upload-artifact@v4
|
|
137
|
+
with:
|
|
138
|
+
name: python-dist-macos-${{ matrix.target }}
|
|
139
|
+
path: dist/*.whl
|
|
140
|
+
if-no-files-found: error
|
|
141
|
+
|
|
142
|
+
sdist:
|
|
143
|
+
name: Source distribution
|
|
144
|
+
runs-on: ubuntu-latest
|
|
145
|
+
steps:
|
|
146
|
+
- uses: actions/checkout@v4
|
|
147
|
+
- uses: actions/setup-python@v5
|
|
148
|
+
with:
|
|
149
|
+
python-version: "3.9"
|
|
150
|
+
- uses: dtolnay/rust-toolchain@stable
|
|
151
|
+
- name: Build source distribution
|
|
152
|
+
uses: PyO3/maturin-action@v1
|
|
153
|
+
with:
|
|
154
|
+
command: sdist
|
|
155
|
+
args: --out dist
|
|
156
|
+
- name: Install source distribution and smoke test
|
|
157
|
+
run: |
|
|
158
|
+
python -m pip install dist/*.tar.gz
|
|
159
|
+
python -c "import positorium; assert positorium.Database.memory().closed is False"
|
|
160
|
+
- uses: actions/upload-artifact@v4
|
|
161
|
+
with:
|
|
162
|
+
name: python-dist-sdist
|
|
163
|
+
path: dist/*.tar.gz
|
|
164
|
+
if-no-files-found: error
|
|
165
|
+
|
|
166
|
+
publish:
|
|
167
|
+
name: Publish to PyPI
|
|
168
|
+
if: ${{ startsWith(github.ref, 'refs/tags/') }}
|
|
169
|
+
needs: [test, linux, musllinux, windows, macos, sdist]
|
|
170
|
+
runs-on: ubuntu-latest
|
|
171
|
+
environment:
|
|
172
|
+
name: pypi
|
|
173
|
+
url: https://pypi.org/p/positorium
|
|
174
|
+
permissions:
|
|
175
|
+
contents: read
|
|
176
|
+
id-token: write
|
|
177
|
+
steps:
|
|
178
|
+
- uses: actions/checkout@v4
|
|
179
|
+
- name: Verify release tag
|
|
180
|
+
shell: bash
|
|
181
|
+
run: |
|
|
182
|
+
package_version="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"
|
|
183
|
+
test "$GITHUB_REF_NAME" = "v${package_version}"
|
|
184
|
+
test -f "docs/releases/${GITHUB_REF_NAME}.md"
|
|
185
|
+
- uses: actions/download-artifact@v4
|
|
186
|
+
with:
|
|
187
|
+
pattern: python-dist-*
|
|
188
|
+
path: dist
|
|
189
|
+
merge-multiple: true
|
|
190
|
+
- name: Verify distribution set
|
|
191
|
+
shell: bash
|
|
192
|
+
run: |
|
|
193
|
+
find dist -maxdepth 1 -type f -print
|
|
194
|
+
test -n "$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
|
|
195
|
+
test -n "$(find dist -maxdepth 1 -name '*.tar.gz' -print -quit)"
|
|
196
|
+
- name: Publish distributions
|
|
197
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|