Changelog
Unreleased
- Release:
release.ymlis rewritten. A version tag runs the same tests as pull requests, builds the wheel, sdist and npm package, installs them in fresh environments (arras doctor, the dev host and an isolated npm consumer), then publishes to PyPI by trusted publishing and to npm with provenance, and creates the GitHub Release. A manual dispatch is a dry run that never publishes. There is no committed wheel hash pin. - CI: one Linux workflow (
ci.yml) with a nightly job for the real-Truss, slow and browser tests, and a tree size guard;pages.ymlpublishes a documentation microsite stamped with the release version. - Removed the Lakebase acceptance tooling and its tests, the downstream qualification runner, the committed
darwin screenshot baselines and the committed evidence and release-receipt documents. They remain in git
history. Screenshot baselines are no longer committed; the
visualproject runs on macOS only. - Docs: the README is rewritten around install and a quickstart that CI runs; the Ashlar adapter is labelled
experimental and not CI-tested;
AGENTS.mdis short;ROADMAP.mdlists open work. - Renamed the npm package checks
test:packed-consumerandtest:packed-browsertotest:smoke-npm-consumerandtest:smoke-npm-browser.
0.8.1 — the static host ships in the package, and markdown list continuation
- Packaging:
@documentdrivendx/arras-uinow has a./staticexport (createStaticClient,loadStore,staticSchemaApi,readConfig,digestOf,READ_ONLY,GraphLoadError,InvalidDocument, and theStaticConfigtype), so a host can mountArrasApporGraphBrowserover its own bundle. 0.8.0 shipped the declarations but no JavaScript for it. - Packaging: the built static host (
static.htmland its assets, relative URLs, the same content security policy) ships in the npm package asstatic-site/, with the stage script asscripts/stage-static.mjs(also thearras-ui-stage-staticcommand). A downstream site stages a graph without a checkout or a build. The wheel carries this package as its npm tarball. - Fix: in the
markdownformat, a list item whose text continues on an indented line is one paragraph, as in CommonMark, not separate paragraphs with a gap mid-sentence. - Release: the registry workflow's final fresh-install check waits and retries while the npm registry propagates a new version.
0.8.0 — static read-only Graph Browser and the markdown format
Markdown format
- Adds
arras.viewvocabulary 0.2.0 with one new format,markdown(ADR-032, CONTRACT-010 A): a closed subset of Markdown drawn as React elements in the Graph Browser, with no HTML string built, images shown as alt text and links limited tohttp,httpsandmailto. 0.1.0 documents read as before; both versions are read by the Python library and the static profile.
Static read-only Graph Browser
- Adds the static read-only profile (ADR-031, CONTRACT-012): the Graph Browser runs from
static files, in the browser, over a UMF module document and an
arras.graphfile, with no server.npm run build:static,npm run stage:static,npm run check:static. The UI takes the client through a newclientprop; nothing else in it changes. - Adds the read corpus
read_cases.json(generated from the Python reference bytools/gen_static_reads.py),tests/vectors/domain.json, andexamples/pizza/pizza.graph.json; the existingview_cases.jsonand template vectors now also run against the TypeScript reader. - Adds
graphql16.11.0 as a runtime dependency of the UI, and moves the graph file reader frombrowser/toapi/(the browser path re-exports it). - Known gap: the
proseview format forbids markup; a sanitizedmarkdownformat is a separate proposal.
0.7.3 — embedded host, themes, and aliases
- Fixes #49: development-host help now shows the effective configured operator groups; explicit command-line groups still take precedence.
- Fixes #50: the development host applies an explicit distribution theme manifest
to the stock UI, with
--theme-manifestoverriding configuration. - Fixes #51: the theme-manifest builder and CLI accept an optional
lightordarkappearance declaration; omitted appearance remains undeclared. - Fixes #52: local package attributes and shim modules keep precedence when Arras
aliases are installed; a closed alias list must explicitly include a package
__main__entrypoint whenpython -msupport is intended. - Fixes #53: the portable UI acceptance testkit preserves host-owned appearance and storage changes while detecting forbidden Arras writes across interactions and operating-system appearance events.
- Fixes #36: legacy view-vocabulary and graph-format aliases are explicit, bounded read policies on a distribution; reads canonicalize aliases while writes remain canonical, and browser graph parsing receives aliases per call.
- Aligns the neutral extension-host dependency and doctor expectations with the exact release version used by fresh installed-consumer qualification.
0.7.2 — unpublished tag
The immutable tag passed all 203 native tests but stopped before artifact
publication on a workflow-contract assertion that still required the broad
Python selector 3.11. The qualified producer uses the stricter 3.11.18.
The successor corrects that exact-pin assertion and runs the workflow-contract
checks before tagging. No GitHub Release, PyPI, or npm artifact was published.
0.7.1 — unpublished tag
The immutable tag was not published to GitHub Releases, PyPI, or npm. Its release build stopped at exact-artifact verification. The successor corrects the extension-host example dependency pin and qualifies the Linux-produced archive bytes before selecting the release digest.
0.7.0 — bounded UMF memory actions
Adds opt-in arras-umf-set/1 execution through the official generated synchronous
client and Ontology.execute. The one-module STRING SET profile uses public
umf-core==0.10.5; document/core semantics remain 0.10.0. The optional engine
now requires its qualified Linux x86_64 or macOS ARM64 native wheel. Python 3.11
remains the release interpreter. Memory replay lasts only for the current process;
Truss/Ashlar action execution remains unqualified.
0.6.5 — downstream integration
Python 3.11 is the supported release profile. Later interpreters remain permitted by the installer minimum but are outside the supported qualification scope.
The development host takes the groups its operator surface is offered to:
--operator-group NAME (repeatable) on the command line, or operator_groups= on
arras.devhost.main and arras.devhost.DevHost. The sandbox's operators join each
named group; the default stays admins and builders.
A key set under both a distribution's env_prefix and ARRAS_ to different
values (EXAMPLE_DEV_USER=alice, ARRAS_DEV_USER=bob) still uses the
distribution's value, and now says so: Config.warnings and one stderr line per
conflict (at most eight) name both variables, never a value. Token and
token-file conflicts continue to refuse.
- The official-engine cases in
tests/test_umf_projection.pyskip without theumfextra, and fail underARRAS_REQUIRE_UMF=1, as the other UMF tests do.
The development host's Truss URL variable, credentials variable and per-user
directory follow the distribution's env_prefix: <PREFIX>_TRUSS_DEV_URL,
<PREFIX>_TRUSS_DEV_CREDENTIALS and ~/.<prefix>/ (truss-dev.env,
truss-dev-credentials/), with the ARRAS_ names and ~/.arras/ as fallbacks.
--help prints the selected names. The default distribution is unchanged.
- The Graph Browser's reset of its controls (
fontandcolorinherited) carries no specificity, so a host's one-class button rule, or the class a design-system widget draws, is no longer overridden by it. Restores the reviewed default typography of the Explore/Operate switch after an earlier reset changed it.
The development host's default --ui falls back to the build the wheel carries
(arras.ui.STATIC) when there is no source-tree ui/dist. An installed wheel's
python -m arras.devhost served only the API and a "UI is not built" page; it now serves the page
and its assets. A source build still takes precedence, and a directory named with --ui is served
as given.
Adds an arras console script. arras doctor, arras devhost and arras mcp run
python -m arras.doctor, python -m arras.devhost and python -m arras.mcp with the rest of the
command line, and arras --version prints the installed version. The module entry points and the
launcher functions a distribution calls (arras.devhost.main, arras.mcp.launch) are unchanged.
Fixes ui.create_app, console.create_app and the operate apps under a framework
mount: with Starlette or FastAPI Mount("/ontology", ui.create_app(..., base_path="/ontology"))
returned 404 for every path, because the prefix was removed twice. base_path equal to
the mount prefix and base_path="" now serve the same URLs. Adds Starlette, FastAPI and
httpx to the development group for the mount tests.
-
arras.ui.assets.build_theme_manifestandpython -m arras.ui theme-manifestbuild a runtime theme bundle (stylesheet, favicon, fonts and a validatedtheme-manifest.json) forcreate_app(theme_manifest=...). -
arras.backendis a catalogued host module (Backend,Provider,Migratesand the names their signatures use), andarras.conformance.HarnessBaseis a supported base for a corpus harness, so a backend written outside the package imports no internal module.InMemory.persontakesadminandInMemory.set_availabletakes areason. -
A runtime theme manifest may declare
entry.appearance("light"or"dark"): the served page's<html>then carriesdata-appearance, so a theme that supplies one appearance's role tokens no longer breaks contrast on a viewer whose system prefers the other. A theme without it must supply both. Documented: the prebuilt page drawsBrand(logo="theme")with the built-in mark; a theme-supplied mark is a host-built UI feature. -
The acceptance testkit's
createAcceptanceConfigtakeshostAppearanceProvider(defaultfalse) for a host that installs its own appearance provider: thehost-isolationspecs that assume a bare host are skipped, and the one that asserts the library installs no appearance checks the Arras subtree alone. -
arras.alias.alias_package(name, *, target="arras", modules=None)lets a thin package under another import name servearrasitself: same module objects, canonical__spec__, workingimportlib.resourcesandpython -m, with an optional closed list of modules. -
The acceptance testkit no longer refuses to build its config on macOS without
baselineDir: only thevisualproject compares screenshots, and it fails at its start, naming the missing directory, when none was given. A run of the nonvisual projects needs none. -
arras-ui-qualify --host-buildnames the host-fixture requirement a page misses (a marked widget, the controls region, the keyboard opener, the app's Mark, a gradient or opacity behind a focus ring) on its error output and in the failure receipt, and points to the fixture contract now written insupport/QUALIFICATION.md.WidgetControlsin@documentdrivendx/arras-ui/testkit/hostrenders the controls region from the design system in context.
0.6.4 — embedding isolation
Adds explicit identity/API session boundaries and optional pageEffects=false
for compiled React consumers. Resets cached data, refusals, forms, drafts and
viewer modes across sessions; guards shared-cache ownership and conflicting
nested configuration. Controlled Explore preserves host history and scroll.
Individual areas get a CSS scope, and instance-local labels, SVG resources,
focus requests and edit portals avoid cross-widget collisions. Documents API-only
ASGI hosting and compiled public npm entrypoints. Native/UMF pins and HTTP
contract versions are unchanged. Published as v0.6.4
on PyPI and npm. All ten release gates, public-byte checks, fresh installs and
public PyPI extras checks on Linux x86_64/macOS arm64 passed; the
publication record
retains exact hashes and npm visibility-retry history.
0.6.1 — release candidate
Adopts exact public Truss 0.0.50 while keeping Weft 0.4.51 and official UMF
core 0.10.0 fixed. Hosts may explicitly supply an immutable tolerated_grantees
tuple for fresh Truss installation; reconnect preserves stored policy. Typed
third-party grant refusals retain bounded diagnostics and the original rollback,
uncertainty and quarantine behavior.
The Truss native runtime manifest remains truss-catalog-runtime/0.74-candidate
with SHA-256 288801f7177338328441b5d3ce9328af31740ebf513f04ea45e30ae316a9f3a4.
The active migration manifest is versioned separately and retains the prior
0.0.49 manifest. The 0.0.50 public source binding does not transfer earlier installed-native or
Lakebase receipts. The exact canonical Arras wheel has since passed both complete
0.6.1 campaigns; source-bound receipts are retained in the governed evidence tree.
Adds separately authorized Lakebase qualification with original identity, transaction, feed, recovery and provider observations. The exact-wheel macOS campaign passed, and the original twelve-case managed campaign passed 12/12 with cleanup, audit, census and custody checks. Final review, exact-commit CI, release artifacts, merge/tag and publication remain open; execution results alone do not declare final release acceptance.
As of 2026-10-25, source 20db67822b20c822ee91c6823a3fe73ebc3ae932 passed all
five CI jobs in run 40221099126 and remains bound to the canonical wheel SHA-256
259e16c7d4c8f6c56d9930ee5f16e74c4ab6b2c8a3ecffdb7d8b306c77b60f18. Fresh Mac
arm64 / CPython 3.11.9 qualification in run 40221099126 passed 64 cases with
eight declared limits and seven replica-only cases inapplicable; native-wheel
hashes, 172-file installed payload parity and cleanup passed. The repaired fresh
Lakebase baseline passed 6/6. The separate original twelve-case Lakebase campaign
passed 12/12 with original cleanup, independent audit, process census and custody
handback passed. Source-bound safe receipts are retained in the governed evidence
tree. The scoped supplemental census did not capture the direct supervisor PGID;
no forced-cleanup claim is made. The initial journal-binding failure and earlier
D11/D12 failures remain historical. Final review, exact-commit CI, release build,
merge/tag and publication gates remain open; this remains a release candidate,
not a published or finally accepted release.
0.6.0 — 2026-10-23
Adds optional official UMF source admission through arras.umf_admission and an
opt-in umf-core-metadata/1 profile for bounded memory-backend metadata
registration and readback. Legacy parsing remains the default; writes refuse for
the metadata-only profile, and the Truss adapter refuses it before acceptance.
This does not add value/constraint execution, canonical actions, native metadata
or Ashlar support. The official UMF core 0.10.0, Truss 0.0.48 and Weft 0.4.51
pins remain unchanged.
Source commit 8f8097ab0bebb3f8eda6d76568c62ee5e84d33ef carries the same A2 scope
as merged source df923164; PR 7 main CI run 39960762557 passed all four checks.
Immutable tag object 686886c7ed2425e4e9e496b70fcc39272b8a52d9 was published as
v0.6.0 on
2026-10-23. Release run
39963352238
completed successfully, including the required Linux jobs, exact-wheel UMF proof,
installed consumer and anonymous public-download verification. The public bundle
contains 17 assets: 16 checksum-listed payloads plus SHA256SUMS, with the
schema-v2 safe UMF receipt as asset 17. Public asset identities and Linux results
are recorded in the release notes and deployment checklist. The final independent
public review is complete and linked from the release notes.
PyPI/npm registry publication remains deferred.
0.5.1 — 2026-10-22
This patch preserves the generic downstream interfaces described below. It corrects a CLI-refusal test to check the bounded parser diagnostic, exit status, credential redaction and absence of startup effects. Regular Python CI now uses the same Truss-extra dependency environment as the release build.
The immutable v0.5.0 tag failed its build gate before any release assets were
published. Version 0.5.1 is a fresh artifact cohort. Its SDK/doctor, fresh consumer and
ordinary themed checks pass independently on the new wheel; all 75 reviewed
baseline hashes are unchanged. The release requires its own installed-native,
exact-tag and anonymous public-download gates before completion. The release
notes and receipts distinguish component runtimes and delivery results.
0.5.0 — failed unpublished tag, 2026-10-22
The following records the qualified candidate feature scope. The tag workflow stopped before artifact creation or publication; it did not deliver a release.
The first public distribution supplies generic Python/UI seams and installed consumer qualification. The release notes record qualified cohorts and limits; the release checklist governs delivery.
Distribution and public API
The wheel carries the built page, exact scoped npm tarball and a deliberate, machine-checked public API catalog. Artifact checks compare source and sdist-rebuilt wheels, dependency metadata, packaged resources and installed consumers. GitHub assets provide wheel, sdist, npm tarball, checksums and receipts. Registry uploads are independent, explicitly configured delivery steps.
Package, contract, vocabulary and catalog versions are separate. A breaking 0.x package change increments its minor version; patches preserve the public surface. Existing contract-specific deprecation periods remain in force.
Naming and configuration
Brand and DistributionConfig supply host presentation without rewriting
upstream imports or wire identities. Public MCP/development launchers support
thin wrapper commands. Opt-in environment aliases take precedence over canonical
fallback, while conflicting credential sources fail before identity selection.
MCP tool aliases reject collisions and stale mappings. Canonical CSS tokens,
protocol names and default instrumentation identifiers remain stable. TelemetryNames and
TelemetryContext provide typed per-host event/attribute/log projection and
validated host-owned service Resources. Awaited ASGI/MCP/worker operations preserve
the selected context; failures do not mutate global providers or business results.
Focused source tests and Sol review pass. The frozen candidate passes 20
installed doctor cases, eight SDK phases and three false-pass controls; exact-tag
and public-download checks remain separate.
UI assets and theming
A compiled host replaces the six design-system slots, including Mark, through public
exports, using one React. A prebuilt page accepts a bounded verified runtime
CSS/font/favicon theme manifest. Same-origin digest routes validate exact paths,
MIME, sizes, hashes and UI cohorts. Arbitrary widget replacement uses the compiled
route. The packed arras-ui-qualify tool checks an explicit host URL with optional
public test-tool peers, retained reports and separate macOS visual baselines.
It never installs peers or downloads browsers implicitly. Node-only ./testkit
and browser-only ./testkit/host share the canonical 17-spec suite and 83 verified
resources. The actual packed themed capture and ordinary comparison each pass
272 cases, with all 67 reviewed baselines unchanged and negative controls intact.
Operators, policy and audit
Composed UI hosting forwards schema authorization alongside existing operator
and action callbacks. PolicyBackend checks current host policy over immutable
resolved requests while preserving the person's token and backend authority.
PolicyRefused exposes a bounded policy code through existing refusal envelopes.
An optional provider protocol binds annotations to the write/audit group; a
provider without that capability refuses before writing. The generic transaction
proof is synthetic. Native Truss policy annotations and deployment-specific
source-entitlement guarantees are not supplied by this release.
Modules and content
A neutral external package selects its own module, seeds and graph resources through public registration/import calls, without loading demo content by default. Registration/discovery stays explicit; documents do not import code. The selected legacy Arras document/action profile is qualified separately from source admission and native execution. The closed view vocabulary has no arbitrary document-component escape hatch. General official-UMF adoption is not claimed.
Backends and development deployment
Hosts compose backend factories and own connections, roles, credential sources and deployment timing. Persistent development hosts retain stable per-person credentials and preserve unrelated memberships and expiry. Missing retained credentials require explicit administrator recovery; ordinary startup does not rotate another host's password. A public lazy native conformance helper owns only its throwaway local database and closes it after each corpus case.
Downstream testing and repository hygiene
Installed consumers can run the packaged corpus and UI checker without copying the upstream test tree. A reusable workflow verifies an exact HTTPS wheel digest, installs a consumer and reports explicitly selected test outcomes. Generic gates check dependency origins, public import boundaries and fixture provenance. The upstream source/docs no longer depend on a named downstream as their authority. Consumers link or extend HELIX decisions and keep their own content downstream.
Upgrade diagnostics
The offline doctor checks explicit installed pins, public exports, configuration, naming, role tokens, asset manifests and declared module profiles. Stable reports separate incompatibility, malformed requests and unavailable capabilities. It reads no ambient credentials, token file, native host or authorization decision. Static compatibility does not establish rendered accessibility or native writes.
Required actions and limits
Pin exact released artifacts and verify their checksums. Use only catalogued Python/UI exports. Keep theme/content packages in the consumer, and run its installed, native and rendered qualification profiles against each new pin. Configure a shared stable credential source before attaching another persistent development host; recover previously unretained role credentials explicitly.
The release notes and machine-readable evidence separate Python/SDK, UI, native and installed-consumer cohorts. The selected native tuple is public Truss 0.0.48, Weft 0.4.51 and pgserver-pg18 18.6.1. Both Linux and Mac source suites pass 199 tests; the fresh Darwin installed corpus records 64 passes, eight declared limits and seven replica-only cases inapplicable. Source classifiers do not qualify unrun platforms. PyPI/npm uploads are deferred while existing publishing access is unavailable; GitHub artifact delivery remains required.