Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,27 +20,36 @@ jobs:
check:
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python: ['3.11', '3.12', '3.13']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v6
- uses: oven-sh/setup-bun@v2
- run: uv sync --frozen --all-packages --python 3.13
- run: uv sync --frozen --all-packages --python ${{ matrix.python }}
- run: bun install --frozen-lockfile
- name: Boundaries, lint, types and unit tests
run: uv run python scripts/check.py
- name: Tree size guard
run: python3 scripts/check_tree_size.py
- name: Version consistency and tree size guard
run: |
uv run python scripts/check_versions.py
uv run python scripts/check_tree_size.py

# Native PostgreSQL (pgserver) and browser tests; runs on every PR so the stack is exercised before merge.
# Native PostgreSQL (pgserver), browser scenarios and the README quickstart.
native:
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: '3.13'
- uses: astral-sh/setup-uv@v6
- uses: oven-sh/setup-bun@v2
- run: uv sync --frozen --all-packages --python 3.13
Expand All @@ -55,6 +64,10 @@ jobs:
- run: node node_modules/playwright/cli.js install --with-deps chromium
- name: Browser scenarios
run: bun run test:native
- name: Build wheels and run the README quickstart against them
run: |
uv run python scripts/build_dist.py
python scripts/smoke_install.py dist
- uses: actions/upload-artifact@v4
if: always()
with:
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ on:
paths:
- 'docs/helix/**'
- '.github/workflows/pages.yml'
- 'packages/batten/pyproject.toml'
workflow_dispatch:

permissions:
Expand Down
121 changes: 121 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
name: Release

# Runs only on a version tag (v0.1.0a3, ...). A manual dispatch builds and
# smoke-tests but never publishes.
on:
push:
tags: ['v*']
workflow_dispatch:
inputs:
dry_run:
description: Build and smoke-test only. Publishing happens only from a tag push.
type: boolean
default: true

permissions:
contents: read

jobs:
test:
uses: ./.github/workflows/ci.yml

build:
needs: test
runs-on: ubuntu-24.04
timeout-minutes: 15
permissions:
contents: read
id-token: write
attestations: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Publishing needs a tag
if: github.ref_type != 'tag' && inputs.dry_run == false
run: |
echo "Publishing only happens from a version tag push; re-run with dry_run." >&2
exit 1
- uses: astral-sh/setup-uv@v6
- uses: oven-sh/setup-bun@v2
- run: uv sync --frozen --all-packages --python 3.13
- run: bun install --frozen-lockfile
- name: Tag matches the one workspace version
run: |
if [ "${GITHUB_REF_TYPE}" = tag ]; then
uv run python scripts/check_versions.py "${GITHUB_REF_NAME}"
else
uv run python scripts/check_versions.py
fi
- run: uv run python scripts/build_dist.py
- uses: actions/attest-build-provenance@v2
if: github.ref_type == 'tag'
with:
subject-path: dist/*
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist
if-no-files-found: error

smoke:
needs: build
runs-on: ubuntu-24.04
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
python: ['3.11', '3.13']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python }}
- uses: actions/download-artifact@v4
with:
name: dist
path: dist
- name: Fresh-venv install of the built wheels and the README quickstart
run: python scripts/smoke_install.py dist

publish:
if: github.event_name == 'push' && github.ref_type == 'tag'
needs: smoke
runs-on: ubuntu-24.04
environment:
name: pypi
url: https://pypi.org/project/novirhyza-batten/
permissions:
id-token: write
steps:
- uses: actions/download-artifact@v4
with:
name: dist
path: dist
- run: rm dist/SHA256SUMS
- uses: pypa/gh-action-pypi-publish@release/v1
with:
packages-dir: dist/

github-release:
needs: publish
runs-on: ubuntu-24.04
permissions:
contents: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/download-artifact@v4
with:
name: dist
path: dist
- name: Create the GitHub Release
env:
GH_TOKEN: ${{ github.token }}
run: |
python3 scripts/release_notes.py "${GITHUB_REF_NAME#v}" > notes.md
gh release create "${GITHUB_REF_NAME}" dist/* --title "Batten ${GITHUB_REF_NAME}" \
--notes-file notes.md --prerelease --verify-tag
8 changes: 6 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Working in Batten

Batten is an application SDK: a UMF/Weft/PostgreSQL-backed local host, an ASGI
registry and an object store. Packages live in `packages/`, the example app in
`examples/approval-desk`.
registry and an object store. Packages: `packages/batten` (contracts, runtime,
tables, asgi), `packages/batten-storage`, `packages/batten-local` (local host and
`umf_postgres`); example app in `examples/approval-desk`. One version for all,
checked by `scripts/check_versions.py`; releases are `v*` tags (`release.yml`).

- Setup and checks: `uv sync --frozen --all-packages`, `bun install --frozen-lockfile`,
`uv run python scripts/check.py` (boundaries, ruff, pyright, oxlint, tsc, pytest).
Expand All @@ -14,6 +16,8 @@ registry and an object store. Packages live in `packages/`, the example app in
packages must not import native or platform modules. Keep new public names in
`public-api.json`.
- Use fabricated data only; no credentials. MIT OR Apache-2.0.
- `README.md` has the quickstart that `scripts/smoke_install.py` executes in CI; keep
its commands and that script in step.
- CI is the gate. Do not commit evidence, receipts, verification JSON or
qualification packets. `ROADMAP.md` lists what is not built; do not describe it as
supported.
45 changes: 45 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Changelog

All distributions share one version and one `v*` tag. Versions before 0.1.0a3 were
separate GitHub prereleases (`runtime-v*`, `storage-v*`).

## 0.1.0a3

Unreleased. First release from PyPI.

- One version for every distribution; one `v*` tag; tag-driven release workflow with
trusted publishing to PyPI, a fresh-venv install smoke test and a GitHub Release.
- Seven wheels became three plus the example: `novirhyza-batten` (contracts, runtime,
tables, ASGI; the `batten.*` import paths are unchanged), `novirhyza-batten-storage`,
`novirhyza-batten-local` (local host and UMF/Weft provider) and
`novirhyza-batten-approval-desk`. The old `novirhyza-batten-{contracts,runtime,tables,asgi,umf-postgres}`
names were never published to PyPI.
- Python 3.11 to 3.13 supported (tested in CI); the workspace was 3.13 only.
- Dependency ranges instead of exact pins: `umf-codegen>=0.10.8,<0.11`,
`umf-weft>=0.4.57,<0.5`, `umf-access>=0.1.0.dev8,<0.2`, `psycopg>=3.3.7,<4`,
`pgserver-pg18>=18.6.1,<19` (still installed from its GitHub release until it is
on PyPI).
- Removed the unimplemented reference-app specifications, evidence and verification
files, and the ratchet gates; added unit tests for contracts, runtime, ASGI, the
UMF provider and the local host; CI runs on Linux for every pull request.
- The approval UMF model now lives in `examples/approval-desk/model/`.

## 0.1.0a2 (runtime-v0.1.0a2, 2026-11-03)

- UMF codegen and core 0.10.8; Weft SQL compiler moved from `weft-sql` 0.4.54 to
`umf-weft` 0.4.57; psycopg 3.3.7.
- TypeScript 7 and Oxlint for the browser tooling; the same two Playwright scenarios.

## 0.1.0a1 (runtime-v0.1.0a1, 2026-11-02)

- First runnable local application: approval desk and a visual app registry, with
contracts, runtime, table port, UMF/PostgreSQL adapter, ASGI transport and local
host as separate wheels.
- Submit, edit, approve and reject requests through UMF tables and Weft on PostgreSQL 18;
a lost mutation response is recovered from its original native receipt.

## storage 0.1.0a1 (storage-v0.1.0a1)

- `novirhyza-batten-storage`: portable async object storage protocols and a managed
local POSIX provider (scoped writes, pinned reads and ranges, conditional
replacement, bounded listing, multipart uploads).
83 changes: 52 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,69 @@
# Batten

Batten is an application software development kit (SDK) in the Novirhyza family.
Authors define native data structures, operations, workflows, jobs, and interfaces.
A public host contract handles admission, execution, integration, and delivery
through explicitly bounded platform modules.
Batten is a small Python application SDK from Novirhyza. You declare tables and
operations once; Batten hosts them behind a public operation API with identity,
audit capture, bounded concurrency and an ASGI transport, on top of UMF and Weft
tables stored in PostgreSQL 18.

The proposed portable core has no ontology-specific capability. An ontology
provider is one Batten module, backed by Arras. UMF, Weft, Tether, and other
platform libraries are dependencies supplied by the platform.
**Status: alpha (0.1.0a3).** What CI tests today, on Linux with Python 3.11, 3.12
and 3.13: the host runtime, the ASGI registry and operation endpoints, the local
object store, the UMF table provider (compiling the approval model with released
`umf-codegen`), and the example approval desk end to end on a real pgserver
PostgreSQL 18 cluster with Playwright browser scenarios (Python 3.13).

Visit the [Batten microsite](https://documentdrivendx.github.io/batten/).
Batten ships **standalone** for now. It depends on UMF, Weft and pgserver only;
there is no Arras, Lintel or Truss integration yet (see the [roadmap](ROADMAP.md)).
Local identities are loopback development stubs, not production authentication.

Explore the [microsite source and local preview instructions](docs/helix/site/README.md)
or read the [application overview](docs/helix/guide/developer/index.md).
The microsite explains the design. The first source implementation is the optional
[local object-storage package](packages/batten-storage/README.md); the complete
application runtime remains in design.
## Install and run the example

Dual licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE).
Copyright Synaptiq.
Needs Python 3.11 to 3.13 on Linux or macOS arm64. `pgserver-pg18` is not on PyPI
yet, so the install points pip at its GitHub release.

<!-- quickstart -->
```sh
python -m venv .venv
. .venv/bin/activate
pip install --pre --find-links https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2 novirhyza-batten-approval-desk
batten-approval init
batten-approval call --actor alex --operation list
batten-approval serve
```
<!-- /quickstart -->

`init` creates a fabricated local PostgreSQL 18 cluster in `.local/approval`;
`call` runs one operation as Alex; `serve` starts the app. Open
<http://127.0.0.1:8820/> and choose **Approval desk**. CI runs these exact commands
against the built wheels before every release.

## Packages

Development uses Python 3.13, Node 26.13.0, Bun 1.4.4 and the locked uv 0.13.7
workspace. Oxlint and TypeScript 7 supply the browser quality checks:
All distributions share one version and one `v*` release tag.

| PyPI name | Import | What it is |
|---|---|---|
| `novirhyza-batten` | `batten.contracts`, `batten.runtime`, `batten.tables`, `batten.asgi` | Operation contracts, host runtime, table port, ASGI transport and app registry |
| `novirhyza-batten-storage` | `batten.storage` | Portable object storage and a managed local filesystem store; no dependencies |
| `novirhyza-batten-local` | `batten.hosting.local`, `batten.umf_postgres` | Local host and UMF/Weft table provider on pgserver PostgreSQL 18 |
| `novirhyza-batten-approval-desk` | `approval_desk` | The example app (`batten-approval` command) |

## Development

```sh
uv sync --frozen --all-packages
bun install --frozen-lockfile
uv run python scripts/check.py
uv run python scripts/check.py # boundaries, ruff, pyright, oxlint, tsc, pytest
uv run python scripts/prepare_approval.py && uv run pytest -m integration && bun run test:native
```

`just test` runs both the Python suite and the two JavaScript Playwright scenarios.
The same quality command runs in CI; `just check` is an equivalent entry point. `just lint`
provides the configured local pre-commit check. Product storage has no third-party
runtime dependencies. Quality tools remain outside its wheel.

The last line needs native PostgreSQL (pgserver) and a Playwright browser; it runs
in CI on every pull request. See [AGENTS.md](AGENTS.md) for the layout and rules.

What is not built is listed in the [roadmap](ROADMAP.md).
## More

## Run the first reference application
[Microsite](https://documentdrivendx.github.io/batten/) ·
[Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) ·
[Design records](docs/helix/README.md) · [Object storage](packages/batten-storage/README.md)

The [approval desk](examples/approval-desk/README.md) uses original UMF tables and
Weft on a dedicated PostgreSQL 18 pgserver, a modular local Batten host and an
authored TypeScript UI. Start with `just approval-prepare`, explicitly initialize
with `just approval-init`, then run `just approval`. The installed app opens at
<http://127.0.0.1:8820/>. Browser tests run with `just approval-test`;
`just check` stays independent of database processes.
Dual licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE).
Copyright Synaptiq.
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ ddx:

# ADR-003: Distribute platform modules separately

> As of 0.1.0a3 the contracts, runtime, tables and ASGI modules ship in one wheel
> (`novirhyza-batten`) and the local host with the UMF/PostgreSQL provider in another
> (`novirhyza-batten-local`). Import paths are unchanged and the import-boundary check
> still enforces the separation. The table below is the original plan.

## Problem

Optional dependencies in one wheel can keep installation light, but the wheel
Expand Down
4 changes: 2 additions & 2 deletions docs/helix/guide/developer/example-approval-desk.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@

Runnable local preview. Follow this journey as a requester and independent approver. Use fabricated data throughout.

[Prepare and start the local app](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md) before following these steps. The preview uses loopback development identities and PostgreSQL 18; production authentication and broader fleet qualification remain separate.
[Install and start the local app](https://github.com/DocumentDrivenDX/batten/blob/main/README.md#install-and-run-the-example) before following these steps. The preview uses loopback development identities and PostgreSQL 18; production authentication and broader fleet qualification remain separate.

## Capabilities in this journey

tables, actions. These tags describe requested integration boundaries.

## 1. Open the local registry

Follow the run instructions to prepare the exact Python 3.13 cohort and explicitly initialize a new fabricated database. Start the host, open its root registry and choose Approval desk.
Follow the install instructions, then explicitly initialize a new fabricated database with `batten-approval init`. Start the host with `batten-approval serve`, open its root registry and choose Approval desk.

## 2. Submit as Alex

Expand Down
4 changes: 2 additions & 2 deletions docs/helix/guide/developer/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,9 @@ A provider must satisfy the required interface and exact compatibility checks. A

## Explore the design

The local runtime preview delivers an approval desk and a visual application registry, with native UMF/Weft persistence on PostgreSQL 18. Separate wheels package the contracts, runtime, table port, native adapter, ASGI transport, local host and app. Qualification is bounded to the recorded cohort and local development identities; the complete fleet remains a design goal. Optional local object storage has its own release. The interactive explorer illustrates the broader contracts and makes no service calls.
The local runtime preview delivers an approval desk and a visual application registry, with native UMF/Weft persistence on PostgreSQL 18. Four wheels package the runtime and ASGI transport, the optional object store, the local UMF/Weft host and the example app; they share one version. Local identities are development stubs, and the complete fleet remains a design goal. The interactive explorer illustrates the broader contracts and makes no service calls.

[Get the runtime preview](https://github.com/DocumentDrivenDX/batten/releases/tag/runtime-v0.1.0a2) or [read the run instructions](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md).
[Install the example](https://github.com/DocumentDrivenDX/batten/blob/main/README.md#install-and-run-the-example) or [read the example README](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md).

[Compose an application](composition.md), [choose a host](hosting.md), or read the [architecture](architecture.md).

Expand Down
Loading
Loading