Cephalon Compatibility

This guide describes the compatibility contract that must stay aligned across Cephalon packages, package manifests, scaffolding, templates, and CLI workflows.

See also: Engineering standards is the broader quality baseline this compatibility contract is part of; Long-range engine direction explains why compatibility discipline matters across multi-decade horizons and why additive opt-in changes plus deliberate obsoletion are preferred over silent contract churn even during the POC phase.

Compatibility contract at a glance

Concern	Source of truth	Must stay aligned
Cephalon package version	the package version you ship for the current engine/tooling release	Cephalon.Cli new defaults, Cephalon.Scaffolding output, Cephalon.TemplatePack package metadata, starter cephalon.package.json files, and versioned doc examples
Target framework baseline	the TargetFramework used by shipped src/Cephalon.* projects	CLI defaults, scaffolded project files, generated module manifests, template project files, sample/reference-module projects, and docs examples
Blueprint, pattern, technology, and transport identifiers	the runtime/app-model contracts in Cephalon.Abstractions and Cephalon.Engine	scaffold plans, CLI parsing/help text, template coverage, samples, and hand-authored docs
Package manifest contract	cephalon.package.json plus engine package-loading and policy enforcement	scaffolded module output, template module starters, reference modules, module-authoring docs, operations docs, and trust/package-policy guidance
Technology-pack execution ownership contract	the public execution/binding contracts and capability/runtime surfaces shipped by technology packs and adapters	component docs, package-surface tests, reference-doc output, operator/runtime guidance, and roadmap/backlog/maturity-audit planning truth
REST authoring and governance contract	the module-owned projection, runtime-catalog, and governance surfaces in Cephalon.Behaviors.Http and Cephalon.AspNetCore	REST-enabled Cephalon.Scaffolding output, cephalon-monolith / cephalon-slice / cephalon-microservice, cephalon-rest-behavior-module, cephalon-rest-module, blueprint samples, REST strategy docs, module-authoring docs, component docs, runtime/operator guidance, and host governance config examples
Reference-doc publishing flow	Cephalon.ReferenceDocs, the CLI docs commands, and the host ReferenceDocs section	scaffolded host appsettings/readmes, docs-publish command help, hosted docs guidance, and docs examples
Release package-artifact flow	scripts/publish-package-artifacts.ps1, scripts/validate-release.ps1, and the release-validation workflow	intended packable project set, shared NuGet metadata/readme defaults, CLI tool packaging, release checksum/provenance metadata, artifact uploads, and package-publishing docs
Framework readiness and deployment-mode claims	scripts/deployment-mode-support.json, docs/deployment-mode-support.md, scripts/validate-dotnet-readiness.ps1, and the dedicated .NET 11 readiness workflow lane	global.json, shipped TFMs, template baselines, scaffolding/runtime defaults, docs claims, package-publishing guidance, and roadmap/backlog planning

Alignment rules

Version and framework baselines

• when the shipped Cephalon package version changes, update CLI defaults, template-pack package metadata, starter manifests, and docs snippets that show a literal version
• when the supported target framework changes, update shipped src/Cephalon.* projects together with CLI defaults, scaffolded output, template projects, sample/reference-module manifests, and docs examples
• keep the shipping framework baseline separate from the readiness lane: net10.0 remains the current shipping floor until an intentional migration updates repo truth across code, docs, templates, and package metadata together
• keep scaffolded package references aligned with the repository package catalog so generated test infrastructure dependencies do not drift from Directory.Packages.props

Framework readiness and deployment-mode claims

• use scripts/deployment-mode-support.json as the explicit deployment-mode support manifest, and use scripts/validate-dotnet-readiness.ps1 as the repo-native validation and reporting surface for current SDK selection, future-SDK assessment, target-framework audit results, and deployment-mode claim status
• treat .NET 11 as a readiness lane until an intentional migration changes the shipping baseline; preview compatibility does not, by itself, change Cephalon’s supported default target framework
• keep higher-SDK validation separate from global.json pinning so Cephalon can assess future SDKs without silently changing the stable shipping toolchain
• keep docs/deployment-mode-support.md aligned as the human-facing explanation of that same manifest-backed support contract, and keep cephalon doctor plus cephalon doctor --app-root <path> aligned as the adoption-facing readback path for the same support truth
• do not claim trim, Native AOT, or single-file support until the manifest, project settings, validation coverage, workflow automation, and docs all agree on the same support statement
• analyzer-only settings are readiness signals, not support claims
• once the planned scripts/validate-deployment-mode-claims.ps1 validation harness ships, a claim-overstated verdict from the harness blocks any advancement of the matching deployment-mode support statement until the underlying warnings and errors are resolved; claim-truthful is the only verdict that unlocks promotion from not-claimed to claimed (see deployment-mode-support.md)

Package manifest compatibility

• module packages should emit version, compatibility.minimumEngineVersion, and compatibility.supportedTargetFrameworks at minimum
• use compatibility.maximumEngineVersion only when support is intentionally capped
• keep cephalon.package.json examples aligned with runtime enforcement in /engine/packages, Engine:PackagePolicy, and Engine:Trust, including any declared package dependencies
• when a package is published externally, keep distribution and provenance metadata aligned with the real release channel, artifact location, source revision, and provenance evidence you shipped
• keep trust-policy examples aligned with the shipped signature-verification paths, including TrustedSignaturePublicKeys, TrustedSignatureCertificates, TrustedSignatureCertificateAuthorities, and the runtime verificationSource / certificateThumbprint fields surfaced through /engine/packages
• keep starter manifests aligned with the module author’s actual assembly target framework and the engine version they intend to support

Generation surfaces

• Cephalon.Engine owns blueprint, pattern, transport, and technology semantics
• Cephalon.Scaffolding renders those semantics into concrete files and package references
• Cephalon.Cli is the richer generation and docs-publishing shell over the same contracts
• Cephalon.TemplatePack is the lightweight install surface for the same shipped blueprint family and module starter conventions
• when blueprint, transport, docs-hosting, or package-manifest behavior changes, update all affected surfaces together instead of letting one generator path drift

Technology-pack execution ownership

• when a technology pack moves from descriptor-only or application-managed behavior into a real managed execution lane, update the public contracts, component docs, capability metadata, runtime-surface metadata, reference docs, and package-surface expectations together
• keep execution ownership explicit in both public contracts and runtime metadata; do not let a pack read as cephalon-managed or provider-managed unless the implementation truly owns the path
• keep narrow managed proofs honest about their trigger path and boundaries, for example when an adapter-managed execution lane depends on an existing staged-publication flow instead of a generic inbound broker story
• for Cephalon.Eventing, the core pack owns channel and subscription descriptors, staged publication, application-managed runtime reporting, the public IEventSubscriptionExecutionBindingCatalog binding read seam, the abstraction-level IEventSubscriptionExecutionReadinessCatalog readiness read seam, the abstraction-level IEventPublicationDispatcher publication action seam, the abstraction-level IEventPublicationRuntimeCatalog publication-state read seam, the abstraction-level event-dispatch runtime descriptor/state contracts, /engine/event-subscription-readiness, POST /engine/event-publications, /engine/event-publications/runtime*, /engine/event-dispatch-runtimes, /engine/event-dispatches, /engine/event-dispatches/terminal-failures, snapshot.EventSubscriptionExecutionReadiness, snapshot.EventPublicationStates, snapshot.EventDispatchRuntimes, snapshot.EventDispatchStates, stable EventSubscriptionRuntimeMetadataKeys, stable EventDispatchRuntimeMetadataKeys, and an opt-in cephalon-managed direct in-process subscription execution lane over registered IEventSubscriptionExecutor services; that in-process lane can optionally use bounded process-local retries through InProcessSubscriptionMaxAttempts and InProcessSubscriptionRetryDelayMilliseconds, and process-local duplicate-completed execution suppression through EnableInProcessSubscriptionIdempotency plus InProcessSubscriptionIdempotencyRetentionMinutes, but it still does not claim broker-owned retries, durable retry queues, durable inbox ownership, cross-node exactly-once delivery, downstream dispatch completion, or distributed scheduling; outbox-backed publication runtime state means accepted/staged handoff, not completed delivery; terminal dispatch-state posture is a first-class operator read over dispatch reports and supported dispatch stores, not a dead-letter or inbox claim; Wolverine remains an optional provider-managed proof over those seams with bounded DispatchMaxAttempts dispatch retry that marks exhausted poison staged publications terminal in the dispatch store, bounded SubscriptionMaxAttempts retry scheduling for declared executor-backed subscriptions, and terminal exhausted-attempt failure reporting, not an engine requirement or a generic broker/inbox/dead-letter ownership claim, and the in-process lane plus operator publication route must stay honest about being bounded, non-durable, and non-brokered
• for Cephalon.Agentics, the current managed/operator proof is the dispatcher-plus-run-state path around registered IAgentToolExecutor services, including opt-in bounded process-local retry posture through ExecutionMaxAttempts, retry-scheduled observations, retry counters, and /engine/agent-tool-runs/retry-pending, plus opt-in process-local duplicate-completed suppression through EnableExecutionIdempotency, ExecutionIdempotencyRetentionMinutes, duplicateCompleted, idempotencyOutcome = duplicate-skipped, and /engine/agent-tool-runs/idempotency-duplicates; approval-required and terminal-failure posture are now first-class read filters through /engine/agent-tool-runs/approval-required, /engine/agent-tool-runs/terminal-failures, and TerminalFailure on AgentToolRunState; IAgentToolDispatcher, AgentToolExecutionRequest, AgentToolExecutionResult, and IAgentToolRunCatalog live in Cephalon.Abstractions.Agentics so hosts can expose /engine/agent-tool-runs*, POST /engine/agent-tools/{toolId}/runs, and snapshot.AgentToolRuns without depending on implementation types; broader autonomous planning, memory persistence, durable approval workflows, durable retry queues, durable inboxes, dead-letter systems, cross-node exactly-once delivery, distributed scheduling, or AI-provider orchestration are not part of that compatibility promise until a package owns them explicitly
• for Cephalon.Retrieval, the current managed proof is the provider-fed lexical index/query/freshness path around registered IKnowledgeDocumentProvider services, with IKnowledgeIndexCatalog, IKnowledgeIndexer, IKnowledgeQueryEngine, KnowledgeQueryRequest, KnowledgeQueryResult, and KnowledgeQueryMatch now living in Cephalon.Abstractions.Retrieval so hosts can expose /engine/knowledge-indexes*, POST /engine/knowledge-indexes/{collectionId}/reindex, POST /engine/knowledge-indexes/{collectionId}/queries, and snapshot.KnowledgeIndexes without depending on implementation types; query route calls return the caller-supplied query in the immediate result, but runtime/operator introspection stores query fingerprint, length, match count, actor, correlation id, and safe metadata instead of raw query text; RetrievalOptions.EnableBackgroundReindexing adds an opt-in in-process IHostedService scheduler over the same indexer path and surfaces retrieval.background-reindexing plus backgroundReindexing* metadata; vector databases, embeddings, durable or distributed indexes, rerankers, provider-specific semantic search, distributed scheduler coordination, and leader-election semantics are not part of that compatibility promise until a package owns them explicitly
• for Cephalon.MultiTenancy, the base-pack managed proof is the configuration-driven tenant-resolution and ambient-context path around ITenantResolver and ITenantContextAccessor; Cephalon.MultiTenancy.Governance now owns companion proofs for membership cataloging/evaluation, local durable membership/invitation/domain/action stores, invitation cataloging/validation, host-agnostic invitation delivery dispatch/run-state/outcome persistence, opt-in local retry storage/execution/scheduling, delivery-status reconciliation and observation storage, host-driven tenant administration, declared domain-ownership validation/workflow/proof challenge/publication planning/HTTP proof publication/proof collection/proof verification/polling, and governance-action decision/workflow state.

Cephalon.MultiTenancy.Governance.AspNetCore owns the optional fail-closed ASP.NET Core governance endpoints and provider-neutral normalized callback signature/replay protections; Cephalon.MultiTenancy.Governance.HttpDelivery owns the optional generic HTTP webhook ITenantInvitationDeliverySender; Cephalon.MultiTenancy.Governance.SmtpDelivery owns the optional SMTP relay sender with a replaceable ISmtpInvitationDeliveryClient seam; Cephalon.MultiTenancy.Governance.SendGridDelivery owns the optional SendGrid Mail Send API sender with a replaceable ISendGridInvitationDeliveryClient seam; Cephalon.MultiTenancy.Governance.MailgunDelivery owns the optional Mailgun Messages API sender with a replaceable IMailgunInvitationDeliveryClient seam; Cephalon.MultiTenancy.Governance.AmazonSesDelivery owns the optional Amazon SES v2 sender with a replaceable IAmazonSesInvitationDeliveryClient seam plus diagnostics 4576-4577; Cephalon.MultiTenancy.Governance.MicrosoftGraphDelivery owns the optional Microsoft Graph sendMail sender with replaceable IMicrosoftGraphInvitationDeliveryClient and IMicrosoftGraphInvitationDeliveryAccessTokenProvider seams plus diagnostics 4572-4573; Cephalon.MultiTenancy.Governance.MicrosoftGraphDelivery.AzureIdentity owns the optional Azure.Identity token provider for that Graph sender with configuration/code-first setup, explicit TokenCredential injection, default Graph .default scope selection, and diagnostics 4574-4575; Cephalon.MultiTenancy.Governance.SendGridDelivery.AspNetCore owns the optional ASP.NET Core SendGrid Event Webhook translator endpoint, including signed-webhook verification, process-local signed-callback replay protection, observation-store-backed sg_event_id duplicate suppression, diagnostics 4562-4565, and the tenant-invitation-delivery-sendgrid-status-callbacks runtime surface; Cephalon.MultiTenancy.Governance.MailgunDelivery.AspNetCore owns the optional ASP.NET Core Mailgun webhook translator endpoint, optional Mailgun HMAC-SHA256 signed-webhook verification, bounded process-local signed-token replay protection, observation-store-backed event-data.id duplicate suppression, diagnostics 4568-4571, and the tenant-invitation-delivery-mailgun-status-callbacks runtime surface; and Cephalon.MultiTenancy.Governance.AmazonSesDelivery.AspNetCore owns the optional ASP.NET Core Amazon SES over SNS translator endpoint, SES event payload translation, opt-in SNS signature verification, bounded process-local SNS replay protection, observation-store-backed SNS MessageId duplicate suppression, opt-in verified SNS subscription confirmation through IAmazonSesSnsSubscriptionConfirmationClient, opt-in verified SNS unsubscribe-confirmation observation without invoking SubscribeURL, diagnostics 4578-4584, and the tenant-invitation-delivery-amazon-ses-status-callbacks runtime surface. Actual DNS proof publication, provider-backed proof publication or mutation, remediation execution beyond state transitions, distributed or provider-backed governance storage, Microsoft Entra application registration/permission consent/mailbox access policy, AWS account/IAM/identity verification, DKIM/SPF/DMARC, SES sandbox/configuration-set event destination setup, SNS topic/subscription creation, automatic resubscribe/restore, subscription lifecycle governance, additional provider-specific email API senders beyond the shipped SMTP/SendGrid/Mailgun/Amazon SES/Microsoft Graph set, SMS/chat/CRM/identity-provider invitation senders, distributed retry queues, cross-node retry leases, provider-specific or distributed callback inboxes, cross-node callback replay protection, distributed event-id ledgers, identity-provider synchronization, callback translation beyond shipped SendGrid/Mailgun/Amazon SES translators, provider-specific callback signature verification beyond shipped SendGrid/Mailgun/Amazon SNS hardening, provider polling, public onboarding, and tenant-admin UI/backoffice flows remain outside the compatibility promise until a package owns them explicitly

Cephalon.MultiTenancy.Governance.AspNetCore also owns the optional fail-closed MapCephalonTenantInvitationDeliveryDispatches() endpoint for POST /engine/tenant-invitations/delivery-dispatches over ITenantInvitationDeliveryDispatcher, plus MapCephalonTenantInvitationDeliveryStatusObservations() for bounded/filterable GET /engine/tenant-invitations/delivery-status/observations reads, filtered status/attention/remediation/outcome/source/providerMessageId/channel/sender/tenant summaries, stable attention-category filters, stable provider-message filters, stable remediation-action filters, and deterministic remediation hints over ITenantInvitationDeliveryStatusObservationStore; this compatibility promise covers dispatch action mapping, normalized observation reads/summaries/drill-downs/hints, and runtime posture only, not provider-specific senders, distributed retry queues, provider-specific callback inboxes, provider polling, distributed remediation execution, distributed replay ledgers, or exactly-once delivery. SendGrid Event Webhook payload translation, optional signed-webhook verification, bounded process-local signed-callback replay protection, and observation-store-backed sg_event_id duplicate suppression belong to Cephalon.MultiTenancy.Governance.SendGridDelivery.AspNetCore, and its compatibility promise does not include durable inboxes, distributed replay, distributed event-id ledgers, provider polling, or non-SendGrid provider translation/signature semantics. Mailgun webhook payload translation, optional Mailgun HMAC-SHA256 signed-webhook verification, bounded process-local replay-token rejection, and observation-store-backed event-data.id duplicate suppression belong to Cephalon.MultiTenancy.Governance.MailgunDelivery.AspNetCore, and its compatibility promise does not include durable inboxes, distributed replay, distributed event-id ledgers, provider polling, or exactly-once delivery. SNS-wrapped Amazon SES event payload translation, opt-in SNS signature verification, bounded process-local SNS replay protection, observation-store-backed SNS MessageId duplicate suppression, opt-in verified SNS subscription confirmation, and opt-in verified SNS unsubscribe-confirmation observation belong to Cephalon.MultiTenancy.Governance.AmazonSesDelivery.AspNetCore, and its compatibility promise does not include SNS topic/subscription creation, SES configuration-set event destination setup, automatic resubscribe/restore, subscription lifecycle governance, durable inboxes, distributed replay, distributed event-id ledgers, provider polling, or exactly-once delivery.

REST authoring and governance

• when behavior-backed REST authoring, shorthand projection, or host-governance semantics change, update REST-enabled Cephalon.Scaffolding output, the REST-enabled blueprint app starters, cephalon-rest-behavior-module, the matching blueprint samples, module-authoring guidance, component docs, compatibility guidance, and runtime/operator docs together
• keep starter guidance aligned with the settled module-owned boundary: REST-enabled blueprint app starters and blueprint samples now treat RestBehaviorModuleBase.ConfigureRestBehaviors(...) plus MapProfile<TBehavior>() as the default public REST path, cephalon-rest-behavior-module remains the recommended package starter for behavior-backed public REST, and cephalon-rest-module remains the generic non-behavior REST starter
• keep behavior REST ownership metadata aligned with the same boundary: restPublicationActivationOwnership and restProfileMetadataOwnership stay application-managed, while restMaterializationOwnership stays cephalon-managed only for the explicit module-owned activation paths that Cephalon materializes into real ASP.NET Core routes and runtime catalogs

Reference-doc and DocFX flows

• XML comments on supported public APIs are the common source for IntelliSense, Cephalon.ReferenceDocs, and DocFX-style publishing
• keep the CLI docs commands, the publish script, scaffolded ReferenceDocs config, and hosted-reference docs guidance aligned when publishing behavior changes
• keep tests outside the supported reference-doc/DocFX input set unless we intentionally promote them into published documentation scope
• keep shared test-harness types internal while the test project stays outside the supported published docs set, leaving only framework-required xUnit classes and rare reflective transport-contract exceptions public

Package publishing flow

• keep the release package-artifact script aligned with the intended packable surface instead of relying on ambient dotnet pack defaults across the whole solution
• keep shared NuGet metadata, package readme defaults, CLI tool packaging, and release artifact output aligned across shipped packages, the CLI tool package, and the reference module package
• keep the release checksum/provenance manifest aligned with the actual repository source revision, packed file set, and published checksum sidecar
• keep the stable cephalon command name aligned across Cephalon.Cli packaging, docs, and validation coverage whenever the tool install surface changes

Repository verification points

• ScaffoldGeneratorTests verifies scaffolded package versions and generated module manifests
• TemplatePackTests verifies starter coverage, package contents, and emitted module manifest conventions
• CliApplicationTests verifies CLI entry points and end-to-end command behavior for the user-facing shell
• PackagePublishingTests verifies the intended release artifact set, packaged readmes, and the local-install smoke path for the Cephalon.Cli tool package
• EngineBuilderTests verifies package-manifest compatibility enforcement such as engine-version and target-framework checks
• PackageSurfaceTests verifies the intended exported surface of the CLI, reference-doc tooling, adapters, scaffolding, and companion packs
• TestHarnessSurfaceTests verifies that tests/Cephalon.Tests exports only xUnit test classes plus the explicit reflective transport-contract allow list and keeps XML-document generation disabled

Maintainer checklist

Use this checklist whenever compatibility-sensitive behavior changes:

1. If the Cephalon package version changed, did you update CLI defaults, scaffold output, template-pack metadata, starter manifests, and versioned docs examples?
2. If the target framework changed, did you update project files, starter manifests, template files, samples, and docs examples together?
3. If blueprint or transport semantics changed, did you update runtime contracts, scaffolding, CLI help/behavior, template starters, and docs together?
4. If cephalon.package.json changed, did you update engine enforcement, scaffold/template output, authoring docs, and operational guidance together?
5. If reference-doc publishing changed, did you update Cephalon.ReferenceDocs, CLI docs commands, scaffolded ReferenceDocs config, and docs/reference-docs.md together?
6. If framework-readiness or future-SDK behavior changed, did you update scripts/deployment-mode-support.json, scripts/validate-dotnet-readiness.ps1, the release-validation workflow, docs/deployment-mode-support.md, docs/dotnet11-readiness.md, docs/project-memory.md, and planning docs together?
7. If trim, Native AOT, or single-file support claims changed, did you add explicit validation and update the deployment-mode support manifest plus package-publishing/support docs instead of relying on analyzer output or local assumptions?
8. If a technology pack moved into a managed proof, did you update component docs, operations docs, package-surface allow lists, generated reference docs, and planning truth in the same slice?