Moving to 11.0: kernel adoption, and what 11.0 retires

Package metadata declares 11.0.0. This release retires three per-call arguments and serves stream_typed from the kernel projection; both are listed in the changelog. It does not remove legacy code: the compatibility facade and the legacy implementations are still in the source, and physical removal remains a separate, explicitly authorized operation behind its own gate.

Adopters who depend on a retired argument stay on 9.12, the newest release that still honours it. The retirement is not backported.

Choose the right entry point

Your project	Starting point	What to verify
New agent	from symfonic import Agent; simple-agent guide	Compose the capabilities your application needs
New application with UI and services	Scaffold	Generated configuration, storage, providers, tenancy and enabled capabilities
Existing SymfonicAgent application	Keep its current entry point while assessing the migration guide	Arguments, switches, persistence and continuation paths exercised by your application
Release or operational validation	Agent regression evals	Evidence from the generated application, not just library unit tests

Kernel adoption is composition: importing Agent does not automatically enable memory, extraction, consolidation, delegation, or telemetry. An existing FrameworkConfig setting is not proof that a separately composed capability consumes it. Consult the migration guide for the corresponding public composition entry point.

ask_user on an existing SymfonicAgent

FrameworkConfig(ask_user_enabled=True) is still an active compatibility setting. On run, stream, and stream_typed, it declines the migrated kernel route and sends the turn to the legacy body, where the built-in ask_user tool, checkpointer, question event, and HMAC pause token remain implemented. The fallback is counted and names ask_user_enabled. The inert_on value in agent/cutover/pause_surfaces.py describes only what the migrated route would do if this setting were admitted; it does not describe the behavior of the SymfonicAgent call after routing.

The first turn must supply both a tenant scope and a non-empty session_id. Without them, all three entry points raise SymfonicAgentError before calling the model because a later resume could not find a stable checkpoint. A pause is minted by the legacy body. resume() is routed separately and may redeem through the kernel continuation or the legacy continuation according to the deployment's continuation switch and the token it accepts. Exercise one real pause and redemption through your transport before rollout, including the question event and pause token returned to the client.

Choose one public composition for human interaction:

Agent entry point	Supported human-interaction setup
Existing SymfonicAgent	Keep ask_user_enabled=True, install the ask-user extra, and provide scope plus session_id on the first turn. No warning is emitted for the flag because it selects working legacy behavior; the missing identity inputs already fail loudly.
Native Agent and AgentHost on current main	Use a revision or package that contains human_continuation(...). Compose human_interaction(...) with durable payload, checkpoint, and consumption ports, and install human_continuation(...) on the host. The capability contributes the built-in ask_user tool spec and registration.

Do not add ask_user_tool_spec or InteractionRegistration beside a SymfonicAgent merely to restore the flag: those are parts of the native capability composition, not a patch for the compatibility facade. Move to that composition when the application moves to Agent and AgentHost. There is no recorded target version for admitting ask_user_enabled onto the kernel route; until its blocking and chunk projections gain a pause shape and admission is re-evaluated, the compatibility route serves the flag.

The ask-user extra remains meaningful for SymfonicAgent. It supplies the token-signing and supported SQLite/Postgres checkpoint dependencies used by the compatibility path, so a consumer that may enable the flag should retain it.

The SymfonicAgent compatibility behavior above is present in the 11.0.0 source and on current main. The clarification of what inert_on means landed on main after the 11.0.0 wheel was built. The native Agent and AgentHost recipe describes current main: human_continuation(...) was added after the 11.0.0 release cut, so use it only from a revision or package that contains that API. This consumer guidance is also a post-release documentation change; it does not update an installed 11.0.0 package or announce a newer package.

Supported FP-4 compositions

The generated scaffold composes platform.governance() and the native QUICK maintenance cycle. Its MEMORY_QUICK_NAP_TURNS is a real cadence: 0 omits the coordinator and a positive value constructs ConsolidationSchedule and a complete quick_phases roster. A quiet-window worker composes the wider DEEP roster itself; nightly_nap_enabled and nightly_nap_cron were operator metadata, not an engine scheduler.

LearningPolicy belongs to a DEEP factory that also receives the extractor collaborator. The model spelling is deliberately different at that boundary: phase_12_llm_model becomes procedural_model_name. The generated scaffold does not compose an LLM extractor, so it rejects every phase-12 LLM model/cap setting early rather than accepting a no-op. enable_semantic_merge is also not a policy field: QUICK uses explicit chat_model and embedding collaborators.

from symfonic.capabilities.memory import quick_phases

phases = quick_phases(
    graph=graph_backend,
    chat_model=chat_model,             # enables the merge collaborator
    embedding_provider=embeddings,
    lookback_hours=24,
    spreading_weight=0.5,
)

Prompt cache directives belong to stable provider-system contributions. The history passed to Agent.run is separate and this does not replace a legacy rolling-history cache policy.

from symfonic.capabilities.prompting import (
    CacheDirective, CacheTtl, Layer, PromptContribution, StaticSource,
)

rules = PromptContribution(
    contribution_id="deployment.rules",
    source=StaticSource("Stable operating rules."),
    layer=Layer.L1,
    cache=CacheDirective(cacheable=True, ttl=CacheTtl.ONE_HOUR),
)

governance() supplies the default credential-hygiene composition. Add a reflector and a trigger policy when the deployment needs metacognition. Recall sensitivity is factual public subject state (metacognition_sensitive_tags), which a retrieval integration must pass; it is not inferred automatically from retrieved prose. ConfidenceOnlyMetacognitionPolicy is an explicit opt-out of the default selective triggers.

For a durable human pause, create the capability with the deployment's durable payload/checkpoint/consumption ports, then install this host-level continuation factory. The resolver receives authenticated token claims and looks up only the signed scope hash; callers never submit a scope with the token. A successful resume is at-most-once. If host construction fails before the token is claimed, the caller can retry it.

from symfonic.platform import AgentHost, human_continuation

host = AgentHost(
    composer=compose_agent_for_scope,
    resources=resources,
    continuation_factory=human_continuation(
        capability=human_pause_capability,
        scope_for_claims=scope_for_authenticated_claims,
    ),
)
result = await host.resume(token, answer)

AgentHost.resume(token, answer) remains the external recovery entry point. Its host adapter authenticates the token, resolves the signed scope, claims the single-use token, and restores the paused turn before it invokes the scoped agent. Agent.continue_recovered(...) is the corresponding trusted in-process integration seam; its value is available as from symfonic.agent.facade_types import RecoveredContinuation. Constructing that value does not authenticate a token, select a scope, or authorize a recovery. Do not build it from a transport request; hosts construct it only after the verified recovery steps above.

The scaffold rejects ASK_USER_ENABLED=true, a non-empty DEV_SQLITE_CHECKPOINT_PATH, and every non-empty PROMPT_LAYER_MODE value at configuration load with the public migration route. This prevents a legacy setting from looking accepted when the scaffold has no durable resolver or explicit prompt contribution for it.

The same early-rejection rule covers uncomposed LLM extraction settings (PHASE_12_USE_LLM_EXTRACTOR and its model/caps) and legacy speaker, layer, role, blend, and relevance controls. Their names appear in generated settings only so a non-default request fails with a route to deep_phases, RetrievalPolicy, or a composed governance policy; the scaffold does not silently accept settings it cannot apply.

The scaffold also rejects MESSAGES_CACHE_POLICY, SYSTEM_PREFIX_CACHE_TTL, and MANIFEST_CACHE_POSITION. A deployment that wants a provider cache must declare stable PromptContribution regions as above; it must separately choose and measure any history-cache strategy. test_fp4_scaffold_migration.py exercises these rejection paths from generated settings.

The installed-artifact FP-4 probe verifies generated settings and the public prompt, governance, and continuation extension seams. It does not exercise the generated application's setup.agent.build_agent, API, or worker lifecycle; that application-closure journey is tracked for FP-5.

What compatibility means here

The compatibility facade and legacy implementations remain in the source. This documentation adds no new deprecation. It does not promise that every historical argument is accepted: existing validation and retirement refusals still apply. Test the exact installed artifact and configuration you use.

A kernel default route does not prove that its legacy fallback is unreachable. Likewise, migrating the examples does not authorize deleting the implementation behind an existing compatibility route.

Pause and resume need particular care. Do not assume a legacy token can be redeemed by a kernel-native checkpoint path. The continuation migration window has eligibility checks and depends on a legacy destination; its release-line bound is derived from that destination's retirement line. Validate outstanding pauses and their redemption path before changing a deployment.

The release/retirement contracts contain version markers such as 10.4 and 11.0. 10.4 is a contract input naming the declared bound of the compatibility window; no 10.x release was ever cut, so the newest version that honours the legacy pins is 9.12. This page does not change those markers, and it does not replace the fourteen-condition retirement gate.

Acceptance checklist for an adopter

Use an isolated test tenant and a generated project built from the candidate wheel. Record the wheel version, configuration and model used.

Feature	Evidence to require
Memory and recall	A fact persists, reaches a later turn's prompt, and stays invisible to another tenant
Vector retrieval	The configured embedder and vector backend are actually called; graph-only mode is reported explicitly
Extraction	Durable extracted records, or an explicit empty/degraded outcome; a fluent answer is not evidence of a write
QUICK consolidation	Cadence triggers a completed cycle; inspect phases and durable effects, not only a scheduling event
DEEP consolidation	Manual and scheduled entry points use the intended composition, with scope exclusion, rollback and restart checks
Tools and delegation	Final arguments, execution/result correlation and child scope; refusal must prevent execution
Procedural skills	Draft, review, approval, prompt inclusion and enforcement are separate observable steps
Observability	Conversation/run/event correlation, safe counters and opt-in redacted content capture

Run applicable scenario packs and explicitly report non-applicable ones. Keep deterministic assertions about storage, isolation and tool execution separate from judgments about model answers. A run with a scripted provider does not establish live-model quality; a successful live-model run does not establish atomicity or tenant isolation.

Bounded work per sweep is not a promise of bounded total database size or constant-cost vector search. Maintainers can inspect the source-repository evidence in docs/design/sc20-bounded-consolidation-worksets.md; that internal design document is not published as part of this site.

Release handoff

Before calling a candidate ready, check documentation links and examples, build/install the wheel, generate the scaffold, run its applicable evals and exercise the UI against that same backend. Keep the resulting evidence with the candidate SHA.

Publishing 10.0, introducing any new deprecation, and removing legacy each require their own decision. None is performed by this documentation update.