Aksara [v0.6.1] — Installed-Package Truth

[nagarjuna-tella]

Aksara v0.6.1 is a post-v0.6 adoption and trust release.

v0.6.0 established Aksara's Production Mode foundation and stable AI/MCP execution boundary. v0.6.1 focuses on making sure the product developers install is the same product our documentation, scaffolding, package metadata, and examples describe.

This release does not introduce a new architectural subsystem.

Instead, it removes ambiguity, fixes several developer-experience inconsistencies, strengthens clean-install validation, and makes the stable/experimental boundary much clearer.

Highlights

One configuration story

Generated Aksara projects now use the framework's global settings authority rather than creating a separate settings instance that could disagree with runtime configuration.

CLI database commands now follow the documented precedence:

AKSARA_DATABASE_URL
        ↓
DATABASE_URL

DATABASE_URL remains supported as a compatibility alias.

Configuration guidance has also been simplified so new projects have one obvious recommended path while compatibility settings remain available.

Stable-core-first scaffolding

Newly generated projects now start from the stable Aksara core.

Experimental surfaces such as provider-backed AI, MCP exposure, and Studio are explicitly enabled when needed rather than being silently assumed by the scaffold.

This makes a fresh project easier to understand and keeps experimental capabilities from looking like required infrastructure.

Clear MCP endpoints

The documentation now consistently distinguishes the two MCP-related surfaces:

/mcp/

The actual MCP Streamable HTTP protocol endpoint used by MCP clients.

/ai/tools/mcp

The inspection/catalog surface for generated tool metadata.

Public examples, settings documentation, security guidance, and getting-started material now use the correct endpoint for each purpose.

Canonical authenticated MCP journey

The primary developer path now demonstrates the actual stable execution model:

Model
  ↓
Migration
  ↓
Generated REST API
  ↓
Server-resolved Principal
  ↓
Generated MCP tool
  ↓
Official MCP client at /mcp/
  ↓
Authorized invocation
  ↓
Persisted PostgreSQL result

The example includes the server-side identity step required for authenticated MCP execution rather than implying that an MCP client chooses its own authority or tenant.

Better authentication failure behavior

Requests running without Starlette authentication middleware are now treated as anonymous instead of failing before Aksara's normal authorization path can run.

This preserves the framework's permission model and produces the expected authorization behavior rather than an unrelated request-context exception.

AI documentation now matches the package

Several public AI pages previously presented conceptual or historical APIs such as AgentRuntime and Planner as if they were current importable interfaces.

v0.6.1 removes that ambiguity.

Executable examples now use APIs that actually exist in the installed package.

Planner behavior, provider abstractions, investigation/session state, autonomous execution, memory, and Studio AI remain clearly marked as experimental or evolving rather than part of the stable v0.6 contract.

Accurate background-task contract

Background-task documentation previously implied complete Principal restoration across queued execution.

The current durable task record persists tenant context, not the full Principal authorization provenance required for delayed reauthorization.

The documentation and regression coverage now reflect that actual contract.

Full durable Principal provenance and reauthorization remain part of the planned v0.7 architecture rather than being partially introduced in this patch.

Package and release truth

Project metadata, version references, and public descriptions have been refreshed to match the current framework.

The repository now also includes final v0.6.0 release evidence in addition to the historical RC evidence, improving future release archaeology.

Documentation that executes

v0.6.1 adds stronger semantic documentation checks.

High-value public examples are now validated against the APIs we actually ship instead of relying primarily on literal documentation locks.

The public example audit covered 1,704 code/documentation blocks with no broken or stale executable classifications.

Installed-wheel release gate

A new installed-package gate validates the main developer journey from a built wheel rather than an editable source checkout.

The validated flow includes:

wheel install
→ CLI
→ project scaffold
→ model
→ migrations
→ PostgreSQL
→ Doctor
→ OpenAPI / REST
→ MCP catalog
→ official MCP client at /mcp/
→ authorized task_create invocation
→ persisted row visible through REST
→ clean shutdown
→ database pool released

This helps ensure repository-only imports or local development assumptions cannot make a broken public package appear healthy.

Validation

The v0.6.1 candidate passed the complete supported runtime matrix:

• Python 3.11
• Python 3.14
• minimum supported FastAPI/Starlette boundary
• latest supported FastAPI/Starlette boundary

Each full matrix run completed with:

8,010 passed, 2 expected provider-dependent skips

Additional release validation included:

• 461 migration tests
• 429 security tests
• 162 fuzz tests with 3 expected skips
• 314 diagnostics tests
• 81 MCP/security-boundary tests
• strict MkDocs build
• installed-wheel PostgreSQL integration
• official MCP client integration
• Doctor release policy with zero warnings, failures, or blocks
• Ruff/mypy non-increasing debt ratchet
• Bandit
• dependency vulnerability audit
• Gitleaks
• CodeQL
• CycloneDX SBOM
• wheel/sdist build
• Twine validation
• isolated package import
• all hosted GitHub release checks

Stable v0.6 contract remains unchanged

v0.6.1 preserves the stable Production Mode foundation introduced in v0.6.0:

• async PostgreSQL ORM
• migrations
• generated REST APIs
• authentication and Principal model
• permissions and PolicyEngine
• documented tenant isolation contract
• MCP Streamable HTTP
• generated executable MCP tools
• execution-time authorization
• tenant and field enforcement
• bounded approval grants
• deterministic execution audit events
• structured errors
• transaction rollback
• cancellation
• runtime limits
• CLI and Doctor release diagnostics

No stable v0.6 API was intentionally removed.

Still experimental

The following remain intentionally outside the stable production contract:

• planner behavior
• investigation/session state
• persistent AI conversations
• agent memory
• multi-agent workflows
• durable autonomous workflows
• provider-specific model quality
• provider-selection abstractions
• automatic code/patch execution
• Studio AI internals

These capabilities may continue evolving without expanding the v0.6 compatibility promise.

What's next

v0.6.1 intentionally does not begin the next architectural milestone.

The direction toward v0.7 is:

Durable authorized operations

If v0.6 made Aksara agent execution safe, v0.7 aims to make authorized work identifiable, queryable, recoverable, reauthorized, idempotent within the framework-owned database boundary, cancellable, and auditable across workers and application restarts.

Before implementation, that architecture will be defined through an explicit operation/state-machine design rather than grown incrementally from the existing experimental Agent APIs.

Upgrade

Install or upgrade with:

pip install -U aksara-framework==0.6.1

For production deployments, continue to:

• run migrations separately before application startup
• use a restricted PostgreSQL application role
• enable/force RLS where required by the tenancy contract
• run:

aksara doctor production-check --release

before release/deployment.

---

Aksara v0.6.1 is fundamentally a trust release:

the package, the scaffold, the docs, and the runtime now tell the same story.

---

This discussion was created from the release Aksara [v0.6.1] — Installed-Package Truth.