AI Fabric Framework 0.4.0

AI Fabric 0.4.0 Release Notes

• Status: Released
• Release date: 2026-07-25
• Version: 0.4.0
• Tag: ai-fabric-framework-v0.4.0
• Release branch: main
• Release scope: typed entity annotations, canonical projection, transaction-aware indexing,
  migration/data-sync convergence, real apps, and public documentation.

AI Fabric 0.4.0 is a breaking lifecycle release. It replaces the permissive 0.3 annotation and queue
model with one typed, validated, durable entity-indexing contract.

Highlights

• Required stable @AICapable.entityType.
• Typed @AIProcess.operation; Java method names no longer imply lifecycle behavior.
• Explicit @AIIdentity plus supported JPA and custom identity resolution.
• Typed searchable/context destinations, data types, preprocessing, required fields, and projection
  priority.
• One immutable descriptor and one canonical, destination-specific AIIndexDocument.
• Fail-closed required-field and requested PII projection.
• Source-transaction-aware queue insertion and provider execution only after commit.
• Durable sync, async, and batch strategies with retry and dead-letter evidence.
• Commit-owned synchronous dispatch that cannot race with retry workers, plus bounded recovery of
  abandoned post-commit dispatch.
• Per-entity ordering state that rejects stale update/delete work.
• Immediate and scheduled synchronous dispatch both honor non-terminal predecessor ordering.
• Entity-level indexing.enabled: false disables annotation lifecycle dispatch without failing the
  domain write.
• Separate dependent analysis work instead of hidden duplicate indexing.
• Migration, trusted push data sync, and Spring AI document ingestion converged on the same projected
  indexing gateway.
• Sanitized aifabricEntities actuator diagnostics and bounded-cardinality Micrometer metrics.
• Complete startup validation for entity contracts, process methods, and queue schema.

Breaking Changes

There are no compatibility aliases for the 0.3 lifecycle. Applications must:

• replace old annotation booleans and string values with typed contracts;
• replace AISearchable.weight with projection priority only where ordering/retention is intended;
• replace processEntityForAI(...) and paired raw lifecycle calls with
  AIEntityIndexingGateway;
• replace old entity YAML with typed indexing/analysis policy;
• replace old queue tables and rebuild generated vectors from authoritative source records.

Read the full
0.4 lifecycle migration guide
before upgrading.

Transaction Semantics

The source change and approved projected queue row commit together when they use the same transaction
manager. Provider/vector work never runs for a rolled-back source transaction.

SYNC means AI Fabric attempts provider work after commit and returns observable final status when
possible. A provider failure does not roll back already committed business data; the durable row is
scheduled for retry. ASYNC and BATCH use the same execution path through workers.

A fresh transactional SYNC row is stored as COMMIT_PENDING. Only the originating post-commit
callback may claim it immediately; retry workers lease PENDING work only. If the process dies
between source commit and callback dispatch, cleanup releases the orphan after
syncCommitRecoveryTimeout (10 minutes by default), records
SYNC_COMMIT_DISPATCH_TIMEOUT, and preserves the provider retry budget. Optional analysis work is a
separate worker-owned dependency and cannot run before its primary indexing row completes.

Data Sync HTTP Semantics

Push data sync now returns:

• 400 PROJECTION_REJECTED for invalid approved projections;
• 503 INDEXING_RETRYABLE when work is durable but synchronous provider execution needs retry;
• 500 INDEXING_PERMANENT when synchronous work exhausted its retry policy and requires operator
  review;
• 500 INDEXING_SUBMISSION_FAILED when durable handoff itself fails.

The API never reports provider failure as a successful vector update.

Release Gate Evidence

Release-candidate verification completed on 2026-07-24:

• ai-fabric-core: 615 tests passed.
• ai-fabric-indexing: 65 tests passed, including real transaction ownership, retry exclusion,
  orphan recovery, stale ordering, and dependent-analysis behavior.
• ai-fabric-data-sync: 36 tests passed.
• The full 35-project infrastructure reactor was verified through a clean framework/unit build and
  an explicit ONNX-enabled integration tail.
• Current infrastructure reports contain 1,553 tests across 356 suites: zero failures, zero errors,
  and 9 intentional provider/environment connectivity skips.
• The integration-test module passed 94 tests; 6 provider/environment-dependent cases were
  intentionally skipped and are not represented as live-provider passes.
• Relationship-query, chat-session, and behavior integration modules passed 1, 23, and 15
  integration tests respectively. Their two connectivity-only tests were intentionally skipped
  outside a keyed live-provider profile.
• The full 21-module real-app reactor passed clean verify: 278 tests in 94 suites, with zero
  failures, errors, or skips.
• Live Data Sync passed 11 application tests and 12 shared smoke tests. Its complete annotation
  lifecycle was repeated five times without sleeps to exercise scheduler concurrency.
• The external AI Fabric course support app passed 71 tests against 0.4.0.
• The packaged Live Data Sync JAR passed health, initial 6/6/6 source/vector/synchronized counts,
  update to revision 2, workspace-filtered retrieval, delete to 5/5/5, and reset to 6/6/6.
• The release-candidate Docker image
  sha256:94f9d5aa8abcbce5f2a02b949fba539c99e619aba2b7a0cf9b426d127381241e
  passed the same lifecycle smoke.
• A live OpenAI proof used text-embedding-3-small and gpt-4o-mini; semantic retrieval selected
  the updated NovaBook evidence and generation returned INFORMATION_PROVIDED with five documents.
• Removed-API, stale-configuration, stub, secret, and diff-quality scans found no release blocker.
• Manual and keyed provider workflows now install the framework with -DskipITs, prepare ONNX
  assets explicitly for ONNX selections, and execute only the selected provider integration suite
  after provider configuration.

The default Docker target intentionally resolves AI Fabric as a Maven Central consumer. The
source-built release-candidate target records the exact pre-publication proof; the default target is
the post-publication consumer smoke for the immutable 0.4.0 artifacts.