Skip to content

Changelog

Unreleased

  • Release: release.yml is 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.yml publishes 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 visual project 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.md is short; ROADMAP.md lists open work.
  • Renamed the npm package checks test:packed-consumer and test:packed-browser to test:smoke-npm-consumer and test:smoke-npm-browser.

0.8.1 — the static host ships in the package, and markdown list continuation

  • Packaging: @documentdrivendx/arras-ui now has a ./static export (createStaticClient, loadStore, staticSchemaApi, readConfig, digestOf, READ_ONLY, GraphLoadError, InvalidDocument, and the StaticConfig type), so a host can mount ArrasApp or GraphBrowser over its own bundle. 0.8.0 shipped the declarations but no JavaScript for it.
  • Packaging: the built static host (static.html and its assets, relative URLs, the same content security policy) ships in the npm package as static-site/, with the stage script as scripts/stage-static.mjs (also the arras-ui-stage-static command). A downstream site stages a graph without a checkout or a build. The wheel carries this package as its npm tarball.
  • Fix: in the markdown format, 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.view vocabulary 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 to http, https and mailto. 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.graph file, with no server. npm run build:static, npm run stage:static, npm run check:static. The UI takes the client through a new client prop; nothing else in it changes.
  • Adds the read corpus read_cases.json (generated from the Python reference by tools/gen_static_reads.py), tests/vectors/domain.json, and examples/pizza/pizza.graph.json; the existing view_cases.json and template vectors now also run against the TypeScript reader.
  • Adds graphql 16.11.0 as a runtime dependency of the UI, and moves the graph file reader from browser/ to api/ (the browser path re-exports it).
  • Known gap: the prose view format forbids markup; a sanitized markdown format 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-manifest overriding configuration.
  • Fixes #51: the theme-manifest builder and CLI accept an optional light or dark appearance 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 when python -m support 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.py skip without the umf extra, and fail under ARRAS_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 (font and color inherited) 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_manifest and python -m arras.ui theme-manifest build a runtime theme bundle (stylesheet, favicon, fonts and a validated theme-manifest.json) for create_app(theme_manifest=...).

  • arras.backend is a catalogued host module (Backend, Provider, Migrates and the names their signatures use), and arras.conformance.HarnessBase is a supported base for a corpus harness, so a backend written outside the package imports no internal module. InMemory.person takes admin and InMemory.set_available takes a reason.

  • A runtime theme manifest may declare entry.appearance ("light" or "dark"): the served page's <html> then carries data-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 draws Brand(logo="theme") with the built-in mark; a theme-supplied mark is a host-built UI feature.

  • The acceptance testkit's createAcceptanceConfig takes hostAppearanceProvider (default false) for a host that installs its own appearance provider: the host-isolation specs 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 serve arras itself: same module objects, canonical __spec__, working importlib.resources and python -m, with an optional closed list of modules.

  • The acceptance testkit no longer refuses to build its config on macOS without baselineDir: only the visual project 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-build names 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 in support/QUALIFICATION.md. WidgetControls in @documentdrivendx/arras-ui/testkit/host renders 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.