diff --git a/README.md b/README.md index 0c4854b..e8f058d 100644 --- a/README.md +++ b/README.md @@ -6,33 +6,12 @@ -⚠️ **Disclaimer:** Under active development. Code has not been audited. APIs and interfaces are subject to change! +⚠️ **Disclaimer:** Under active development. Code has not been audited, APIs and interfaces are subject to change! Framespace Genesis [![Tests](https://github.com/Stream44/FramespaceGenesis/actions/workflows/test.yaml/badge.svg)](https://github.com/Stream44/FramespaceGenesis/actions/workflows/test.yaml?query=branch%3Amain) === -*Experimental* implementations of [encapsulate](https://github.com/Stream44/encapsulate) based visual modeling engines. Models are constructed by defining components and events are generated by following an actual execution path through annotated code components. - -Usage --- - -[bun.sh](https://bun.sh) is required. - -After cloning run: - -``` -bun install - -# Generate data for viewing -bun test - -# Start the workbench -bun dev - -# Open browser -open http://localhost:3000 -``` - +An *experimental* implementation of an [encapsulate](https://github.com/Stream44/encapsulate) based visual modeling engine. Models are constructed and events are generated by following an actual execution path through annotated code components. Overview === @@ -67,61 +46,57 @@ The model **executes by following the actual codepath** — object method calls These events are collected into a **boundary event log**. The schema and event log together drive a **schema-based, event-hydrated interactive visualization**. -**The primary rule:** construct a **promise graph** through all action invocations that touches every attribute and ends up in a resolved state when the model has finished executing. - ![Implementation Approach](./engines/Concept.svg) -Model Engines -=== - -Engines implement queryable graph models to drive visualizations. Each engine supportes a specific set of model features. - -LadybugDB engine for Encapsulate ---- - -Query [encapsulate](https://github.com/Stream44/encapsulate) *Capsule Source Tree* and *Membrane Event* related data from the [ladybugdb.com](https://ladybugdb.com/) embedded database engine. - -See: [engines/Capsule-Ladybug-v0/](engines/Capsule-Ladybug-v0/) - -Framespace Workbench +Visualizations === -The workbench single-page-application presents all supported visual models for a selected **Capsule Spine Tree Instance** on the same page. The visualizations update in realtime as source code is modified. - -See: [workbench/](workbench/) +### Quadrant Visual Model -![Framespace Workbench](./workbench/Screenshot.jpg) +The visualization is organized into **quadrants** with column and row trees that define the spatial layout. **Nested spaces** act as logical domains — the same identified space is the same space across quadrants, not just a visual container. +Inside spaces, **components** are the core unit. A component has **properties** (state) and **actions** (executable methods). Components can have multiple actions and attributes that define their visual and functional identity. -Visualizations -=== +**Action invocations** connect components. An action payload moves from action to action — internal or external, one-to-one or fan-out to multiple invocations. Payloads crossing component and space boundaries emit **boundary crossing events** which makes execution observation possible. -### Framespace API +The primary rule: construct a **promise graph** through all action invocations that touches every attribute and ends up in a resolved state when the model has finished executing. -Inspect all APIs available to create visualizations to see what they return. This aids in model definition and visualization development. +![Quadrant Visual Model](./visualizations/Quadrant/Concept.svg) -See: [visualizations/FramespaceAPI/](visualizations/FramespaceAPI/) +Contributing +=== -### Capsular Spine Visual Model +All contributions must comply with the repository’s Developer Certificate of Origin (DCO) and verified commit signature requirements. -Various visualizations to represent chains of [encapsulated](https://github.com/Stream44/encapsulate) components with animated execution activity. +Before opening a Pull Request: -See: [visualizations/CapsularSpine/](visualizations/CapsularSpine/) +1. Sign the DCO agreement once: + ```bash + bun run sign-dco + ``` +2. Ensure every commit: -### Quadrant Visual Model + * Contains a `Signed-off-by:` trailer + * Is cryptographically signed (SSH or GPG) + * Has a clean working tree before using repository scripts -The visualization is organized into **quadrants** with column and row trees that define the spatial layout. **Nested spaces** act as logical domains — the same identified space is the same space across quadrants, not just a visual container. +3. Push your branch using the provided helper: -Inside spaces, **components** are the core unit. A component has **properties** (state) and **actions** (executable methods). Components can have multiple actions and attributes that define their visual and functional identity. + ```bash + bun run push + ``` -**Action invocations** connect components. An action payload moves from action to action — internal or external, one-to-one or fan-out to multiple invocations. Payloads cross component and space boundaries making visual effects possible. + This will squash unsigned commits into a signed commit where possible. -See: [visualizations/Quadrant/](visualizations/Quadrant/) +⚠️ Important: -![Quadrant Visual Model](./visualizations/Quadrant/Concept.svg) +* The DCO check validates **all commits in the PR range**, not only the latest commit +* Verified signatures are enforced by repository rules +* Force-push may be restricted by branch protection; if you need to rewrite commits, create a new branch and open a new PR +* See the full contribution guide: [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) Provenance @@ -143,6 +118,4 @@ Repository DID: `did:repo:e7b46f0978c2cc02461b480b99a6589a2b6fa888` (c) 2026 [Christoph.diy](https://christoph.diy) • Code: [LGPL](./LICENSE.txt) & [MIT](./LICENSE.txt) • Text: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) • Created with [Stream44.Studio](https://Stream44.Studio) -### Contributing -All contributions must contain a [Developer Certificate of Origin](https://github.com/Stream44/dco). To contribute, sign `DCO.md` once using `bun run sign-dco` and push branches to github using `bun run push` which will squash unsigned commits into a signed commit. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..ea5c277 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,262 @@ +# Contributing to Framespace Genesis + +Thank you for contributing to Framespace Genesis. + +This repository enforces strong provenance and integrity guarantees. As a result, contributions must satisfy **three independent requirements**: + +1. Developer Certificate of Origin (DCO) +2. Signed-off commit messages +3. Verified cryptographic commit signatures (SSH or GPG) + +All three are required for CI to pass. + +--- + +## Overview of Repository Rules + +Before submitting a Pull Request, ensure that: + +- You have signed the DCO agreement +- Every commit contains a `Signed-off-by:` trailer +- Every commit is cryptographically signed +- The working directory is clean when using repository scripts +- Branch protection rules may prevent force-pushes + +Failing any of these will cause CI checks to fail. + +--- + +## One-Time Setup (Required) + +### 1. Install Bun + +```bash +curl -fsSL https://bun.sh/install | bash +```` + +Verify: + +```bash +bun --version +``` + +### 2. Configure Git Identity + +Use the same email as your GitHub account: + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +--- + +## Configure Verified Commit Signing (SSH Recommended) + +This repository enforces verified signatures. + +### Step 1 — Enable SSH Signing in Git + +```bash +git config --global gpg.format ssh +git config --global user.signingkey ~/.ssh/id_ed25519.pub +git config --global commit.gpgsign true +``` + +If your key has a different name, list keys: + +```bash +ls ~/.ssh/*.pub +``` + +### Step 2 — Configure Local Verification (Required by Git) + +```bash +mkdir -p ~/.config/git +echo "$(whoami) $(cat ~/.ssh/id_ed25519.pub)" > ~/.config/git/allowed_signers +git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers +``` + +### Step 3 — Register Your Signing Key in GitHub + +Go to: +GitHub → Settings → SSH and GPG Keys → New SSH Key + +Important: + +* Set **Key Type** to: `Signing Key` +* Do NOT add it only as an authentication key + +--- + +## Sign the Developer Certificate of Origin (DCO) + +Sign once per repository: + +```bash +bun run sign-dco +``` + +This records your DCO agreement in the repository. + +--- + +## Recommended Contribution Workflow (Golden Path) + +This workflow avoids history rewriting and CI failures. + +```bash +git checkout -b my-feature-branch +bun install + +# Make your changes +git add . +git commit -S --signoff -m "Describe your change clearly" + +git push -u origin my-feature-branch +``` + +Then open a Pull Request. + +--- + +## Using the Repository Push Helper + +The repository provides a helper: + +```bash +bun run push +``` + +Behaviour: + +* Requires a clean working directory +* May squash unsigned commits into a signed commit +* Does NOT automatically fix missing `Signed-off-by` trailers on older commits +* Will fail if untracked or unstaged files exist + +--- + +## Common CI Failures and Fixes + +### 1. Missing Signed-off-by Trailer + +Error: + +``` +Missing: Signed-off-by trailer +``` + +Fix: + +```bash +git commit --amend -S --signoff --no-edit +``` + +--- + +### 2. Missing Verified Signature + +Cause: + +* Git signing not configured +* Signing key not registered in GitHub as a Signing Key + +Fix: + +* Configure SSH signing (see above) +* Amend the commit: + +```bash +git commit --amend -S --no-edit +``` + +--- + +### 3. DCO Fails for Older Commits in PR + +The DCO check validates **all commits between `main` and your PR head**. + +Inspect commit range: + +```bash +git log --oneline origin/main..HEAD +``` + +If any commit is missing sign-off or signature, rewrite them: + +```bash +git rebase -i HEAD~N +git commit --amend -S --signoff --no-edit +git rebase --continue +``` + +--- + +### 4. Force Push Blocked by Repository Rules + +This repository may block force-push on branches. + +If you rewrote commit history: + +```bash +git checkout -b my-branch-fixed +git push -u origin my-branch-fixed +``` + +Then open a new Pull Request and close the old one. + +--- + +### 5. Working Directory Not Clean (`bun run push` fails) + +Example: + +``` +Working directory has uncommitted changes +``` + +Fix options: + +* Commit the files +* Stash them: + + ```bash + git stash -u + bun run push + git stash pop + ``` +* Or ignore local artefacts (e.g. `bun.lock`) using: + + ```bash + echo "bun.lock" >> .git/info/exclude + ``` + +--- + +## Pull Request Requirements + +A Pull Request will only be mergeable when: + +* All CI checks pass +* DCO validation passes +* Signature verification passes +* At least one reviewer with write access approves the PR + +Contributors cannot merge their own PR without external approval due to repository governance rules. + +--- + +## Final Verification Before Opening a PR + +```bash +git log -3 --show-signature +git log -3 --pretty=%B +``` + +Ensure: + +* Each commit shows a valid signature +* Each commit contains a `Signed-off-by:` line + +````