1.0: Update API references and examples for AsiBackbone 6.0

.github/workflows/docs-validation.yml

@@ -21,6 +21,7 @@ on:
       - 'tools/generate-sitemap.cs'
       - 'tools/prepare-indexnow.cs'
       - 'tools/publish-x.cs'
+      - 'tools/validate-asibackbone-6-api-references.cs'
       - 'tools/validate-doc-metadata.cs'
       - 'tools/validate-docfx-template-baseline.cs'
       - '.config/dotnet-tools.json'
@@ -64,6 +65,9 @@ jobs:
       - name: Validate DocFX template baseline
         run: dotnet run --file tools/validate-docfx-template-baseline.cs
 
+      - name: Validate AsiBackbone 6.0 API references
+        run: dotnet run --file tools/validate-asibackbone-6-api-references.cs
+
       - name: Restore .NET tools
         run: dotnet tool restore
 

README.md

@@ -83,6 +83,7 @@ Want to understand why this boundary exists or experiment with it?
 | Learn the foundational governed-execution boundary | [Decision Before Execution](docs/tutorials/decision-before-execution.md) |
 | Route from a problem you already recognize | [Find Your Path](docs/getting-started/find-your-path.md) |
 | See the curriculum and prerequisites at a glance | [Learning Path Map](docs/getting-started/learning-path-map.md) |
+| Copy exact AsiBackbone 6.0 API syntax | [AsiBackbone 6.0 API Boundary](docs/getting-started/asibackbone-6-api-boundary.md) |
 | Decide whether ASP.NET Core authorization is already enough | [When ASP.NET Core Authorization Is Enough](docs/architecture/when-aspnet-core-authorization-is-enough.md) |
 
 ## What This Architecture Looks Like in Practice
@@ -140,6 +141,7 @@ AsiBackbone Learning is an educational and architectural resource.
 
 - It teaches architectural patterns; it does not certify compliance or guarantee security.
 - Examples do not replace application-specific security, legal, regulatory, safety, or operational review.
+- Learning-owned sample types are framework-neutral teaching models, not `AsiBackbone.*` package API signatures.
 - Learning is not an AI model, an artificial general intelligence or artificial superintelligence implementation, or a robotics controller.
 - No `AsiBackbone` package is required, and no pattern is presented as universally correct.
 

docs/advanced/distributed-acknowledgment-and-continuation-workflows.md

@@ -150,6 +150,8 @@ accounts.bulk-suspend
 
 System A evaluates a tenant administrator's request to suspend a bounded set of fictional accounts. Current policy requires acknowledgment of the operational impact. System B presents the challenge to the required responder and produces evidence of the response. System C owns the eventual account executor. The systems are separate enough that System C cannot safely assume it still has System A's original in-memory context. The challenge therefore needs durable bindings that System C can validate later. A compact challenge model might contain:
 
+> **Illustrative API:** This local `AcknowledgmentChallenge` shape is a teaching model, not the `AsiBackbone.AspNetCore` package type. See the [AsiBackbone 6.0 API Boundary](../getting-started/asibackbone-6-api-boundary.md) before copying package-integration syntax.
+
 ```csharp
 public sealed record AcknowledgmentChallenge(
     string ChallengeId,

docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md

@@ -312,10 +312,12 @@ But if the purpose of the repository was to hide EF Core or constrain persistenc
 
 Prefer methods that expose the operation the caller needs when the repository is intended to be a real boundary:
 
+> **Illustrative API:** The repository and receipt names in the following examples are local teaching shapes, not `AsiBackbone.*` package signatures. See the [AsiBackbone 6.0 API Boundary](../getting-started/asibackbone-6-api-boundary.md) for the exact current receipt and persistence contracts.
+
 ```csharp
 Task<Account?> FindForDisableAsync(...)
 ValueTask<CapabilityUseResult> TryConsumeAsync(...)
-Task AppendAsync(DecisionReceipt receipt, ...)
+Task AppendAsync(LearningDecisionReceipt receipt, ...)
 ```
 
 Do not create one method per `DbSet` operation simply to avoid naming `DbContext`.
@@ -815,7 +817,7 @@ Prefer explicit code when the operation is meaningful because of the workflow:
 
 ```csharp
 await decisionReceiptStore.AppendAsync(
-    DecisionReceipt.ExecutionStarted(...),
+    LearningDecisionReceipt.ExecutionStarted(...),
     cancellationToken);
 ```
 
@@ -1235,7 +1237,7 @@ Governance decision
 Execution-boundary service
         ↓
 ICapabilityUseStore
-IDecisionReceiptStore
+ILearningDecisionReceiptStore
         ↓
 EF Core implementations
         ↓
@@ -1265,11 +1267,11 @@ public sealed class ExecutionPersistenceCoordinator
 {
     private readonly ApplicationDbContext _dbContext;
     private readonly EfCoreCapabilityUseStore _useStore;
-    private readonly EfCoreDecisionReceiptStore _auditStore;
+    private readonly EfCoreLearningDecisionReceiptStore _auditStore;
 
     public async Task<CapabilityUseResult> TryStartAsync(
         string capabilityId,
-        DecisionReceipt executionStart,
+        LearningDecisionReceipt executionStart,
         CancellationToken cancellationToken)
     {
         await using var transaction =

docs/case-studies/governed-administrative-operation.md

@@ -664,6 +664,8 @@ One correlation identifier connects the lifecycle, but different records answer
 
 Use one explicit linkage envelope across the three core evidence types—decision, grant, and execution:
 
+> **Illustrative API:** The receipt records below are case-study models, not `AsiBackbone.*` package signatures. Compare the exact 6.0 receipt surface in the [AsiBackbone 6.0 API Boundary](../getting-started/asibackbone-6-api-boundary.md).
+
 ```csharp
 public sealed record EvidenceCorrelation(
     string CorrelationId,

docs/case-studies/human-acknowledgment-workflow.md

@@ -443,6 +443,7 @@ The client cannot create a privileged acknowledgment challenge simply by request
 A challenge should survive beyond one HTTP request or browser session when the workflow can pause.
 
 ```csharp
+// Illustrative case-study model; not an AsiBackbone package API.
 public enum AcknowledgmentChallengeStatus
 {
     Pending,

docs/getting-started/asibackbone-6-api-boundary.md

@@ -0,0 +1,144 @@
+---
+description: Distinguish Learning teaching models from the finalized AsiBackbone 6.0 API, including supported construction, endpoint markers, and removed members.
+---
+
+# AsiBackbone 6.0 API Boundary
+
+AsiBackbone Learning teaches architecture with two different kinds of code:
+
+1. **Learning-owned teaching models** are small, framework-neutral types compiled from this repository. They make an architectural boundary easy to observe, but they are not package API signatures.
+2. **AsiBackbone 6.0 API examples** use the finalized public names and namespaces from the implementation repository's `release/6.0.0` branch.
+
+Keep that distinction visible when copying an example. A local teaching type named for a concept may be intentionally smaller than the similarly named framework type.
+
+> **API status:** Unless a section is labeled **AsiBackbone 6.0 API**, code in Learning is illustrative or belongs to a Learning sample. Follow the linked implementation source or the [5.x to 6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) for exact package syntax.
+
+## Executable Sample Package Policy
+
+The projects under `samples/` are executable Learning companions, not package-integration samples. They currently contain no `PackageReference` to an `AsiBackbone.*` package. Their local records, policies, evaluators, and gateways are teaching models owned by this repository.
+
+That is deliberate:
+
+- the samples remain runnable while the 6.0 package line is prepared;
+- architectural invariants can be studied without adopting a framework;
+- local types do not claim to reproduce every constructor, member, namespace, persistence seam, or security control in the implementation.
+
+If a future sample adds an `AsiBackbone.*` package reference, it must pin a released 6.x version through the sample package-management files, update the lock file, compile against that package, and identify itself as a package-integration sample.
+
+## Finalized Core Names
+
+The complete review covers 232 public type entries across ten managed packages. The authoritative inventory is the [6.0 public API naming convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md).
+
+The names most often used by Learning material are:
+
+| Purpose | AsiBackbone 6.0 public type |
+| --- | --- |
+| Evaluation context contract | `AsiBackbone.Core.Constraints.IGovernanceEvaluationContext` |
+| Default context | `AsiBackbone.Core.Constraints.GovernanceEvaluationContext` |
+| Constraint | `AsiBackbone.Core.Constraints.IGovernanceConstraint<TContext>` |
+| Policy evaluator | `AsiBackbone.Core.Evaluation.IGovernancePolicyEvaluator<TContext>` |
+| Default evaluator | `AsiBackbone.Core.Evaluation.DefaultGovernancePolicyEvaluator<TContext>` |
+| Evaluator builder | `AsiBackbone.Core.Evaluation.GovernancePolicyEvaluatorBuilder<TContext>` |
+| Evaluator options | `AsiBackbone.Core.Evaluation.GovernancePolicyOptions` |
+| Decision policy | `AsiBackbone.Core.Evaluation.IGovernanceDecisionPolicy<TContext>` |
+| Decision | `AsiBackbone.Core.Decisions.GovernanceDecision` |
+| Decision receipt | `AsiBackbone.Core.Audit.DecisionReceipt` |
+| Receipt sink | `AsiBackbone.Core.Audit.IDecisionReceiptSink` |
+| Durable audit ledger | `AsiBackbone.Core.Audit.IGovernanceAuditLedgerStore` |
+| Actor context | `AsiBackbone.Core.Actors.GovernanceActorContext` |
+| ASP.NET Core endpoint service | `AsiBackbone.AspNetCore.Endpoints.IEndpointGovernanceService` |
+| Acknowledgment challenge service | `AsiBackbone.AspNetCore.Handshakes.IAcknowledgmentChallengeService` |
+
+These are implementation types. A Learning snippet that defines its own decision, receipt, context, or acknowledgment record is a teaching model unless the section explicitly says otherwise.
+
+## Construct an Evaluator
+
+The five partial evaluator constructors retained during 5.x do not exist in 6.0. Use the builder or the full-dependency constructor.
+
+**AsiBackbone 6.0 API:**
+
+```csharp
+using AsiBackbone.Core.Constraints;
+using AsiBackbone.Core.Evaluation;
+
+IGovernancePolicyEvaluator<GovernanceEvaluationContext> evaluator =
+    DefaultGovernancePolicyEvaluator
+        .CreateBuilder<GovernanceEvaluationContext>()
+        .AddConstraints(constraints)
+        .AddThreatModelContributors(threatModelContributors)
+        .WithDecisionPolicy(decisionPolicy)
+        .WithOptions(options)
+        .WithLogger(logger)
+        .Build();
+```
+
+The supported direct constructor accepts the complete dependency set:
+
+**AsiBackbone 6.0 API:**
+
+```csharp
+var evaluator = new DefaultGovernancePolicyEvaluator<MyPolicyContext>(
+    constraints,
+    threatModelContributors: null,
+    decisionPolicy: null,
+    options: null,
+    logger: null);
+```
+
+For dependency injection, prefer a factory that resolves the host's configured constraints, contributors, decision policy, `IOptions<GovernancePolicyOptions>.Value`, and logger before calling the builder. Registering only the concrete evaluator type requires the container to resolve all five constructor dependencies.
+
+Inspect the exact implementation in [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs), its [`CreateBuilder` factory](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.Factory.cs), and [`GovernancePolicyEvaluatorBuilder`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/GovernancePolicyEvaluatorBuilder.cs).
+
+## Mark Endpoint Policy Metadata
+
+The 5.x `RequireGovernancePolicy` route-builder methods were removed. Use `MarkGovernancePolicy`.
+
+**AsiBackbone 6.0 API:**
+
+```csharp
+using AsiBackbone.AspNetCore.Endpoints;
+
+app.MapPost("/operations", HandleOperation)
+    .MarkGovernancePolicy<ConsequentialOperationPolicy>();
+
+app.MapPost("/exports", HandleExport)
+    .MarkGovernancePolicy(typeof(ExportPolicyMarker));
+```
+
+The marker records policy metadata. It does not, by itself, resolve a policy, select constraints, or enforce execution. See the exact [`EndpointGovernanceRouteBuilderExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceRouteBuilderExtensions.cs) behavior.
+
+## Removed Compatibility Surface
+
+The upstream obsolete-member inventory found exactly seven public members whose compatibility window ended at 6.0:
+
+| Removed after 5.x | Supported 6.0 path |
+| --- | --- |
+| `DefaultAsiBackbonePolicyEvaluator<TContext>(constraints, decisionPolicy = null)` | Builder with `AddConstraints` and `WithDecisionPolicy` |
+| `DefaultAsiBackbonePolicyEvaluator<TContext>(constraints, decisionPolicy, options)` | Builder plus `WithOptions` |
+| `DefaultAsiBackbonePolicyEvaluator<TContext>(constraints, decisionPolicy, options, logger)` | Builder plus `WithOptions` and `WithLogger` |
+| `DefaultAsiBackbonePolicyEvaluator<TContext>(constraints, threatModelContributors, decisionPolicy = null)` | Builder plus `AddThreatModelContributors` and `WithDecisionPolicy` |
+| `DefaultAsiBackbonePolicyEvaluator<TContext>(constraints, threatModelContributors, decisionPolicy, options)` | Builder plus contributors, policy, and options |
+| `RequireGovernancePolicy<TPolicy>(RouteHandlerBuilder)` | `MarkGovernancePolicy<TPolicy>()`, or `MarkGovernancePolicy(typeof(TPolicy))` for a plain marker |
+| `RequireGovernancePolicy<TBuilder>(TBuilder, Type)` | `MarkGovernancePolicy(builder, policyType)` |
+
+The non-obsolete `RequireGovernancePolicyAttribute` remains part of the implementation. Historical 4.x and 5.x migration material may retain old names when it is clearly presented as history; current examples must not present the removed members as callable 6.0 APIs.
+
+## Decision Receipt Is Not Execution Proof
+
+`DecisionReceipt` records the policy decision outcome and reasons. Later acknowledgment, capability, gateway, emission, and execution lifecycle evidence can correlate with it, but the decision receipt does not prove that the host executed the protected operation.
+
+Learning samples may use smaller local receipt or lifecycle records to make that distinction visible. Compare them with the exact 6.0 [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) and [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) source before adopting a package integration.
+
+## Review Checklist
+
+Before publishing an API-facing Learning change:
+
+- label teaching code as illustrative or Learning-owned;
+- label exact framework syntax as AsiBackbone 6.0 API;
+- use finalized 6.0 names and namespaces;
+- do not call removed evaluator constructors or route-builder methods;
+- link implementation source to `release/6.0.0`, not `main` or a 5.x branch;
+- pin any future `AsiBackbone.*` sample package reference to a released 6.x version and commit its lock-file update;
+- preserve old names only in clearly historical migration or release material.
+
+The repository's API-reference validator enforces the machine-checkable parts of this boundary during documentation validation.

docs/getting-started/index.md

@@ -20,6 +20,7 @@ Choose the shortest path that matches how you want to learn:
 | Solve a specific architecture problem | [**Find Your Path**](find-your-path.md) |
 | See the complete curriculum visually | [**Learning Path Map**](learning-path-map.md) |
 | Learn by running code | [**Executable Samples**](../samples/index.md) |
+| Copy exact AsiBackbone 6.0 API syntax | [**AsiBackbone 6.0 API Boundary**](asibackbone-6-api-boundary.md) |
 | Practice by changing or challenging the design | [**Hands-On Labs**](../labs/index.md) |
 | Compare a simpler alternative | [**When ASP.NET Core Authorization Is Enough**](../architecture/when-aspnet-core-authorization-is-enough.md) |
 
@@ -106,6 +107,8 @@ The [`samples/`](../samples/index.md) area contains intentionally small .NET tea
 
 They are teaching artifacts rather than production frameworks.
 
+Their local types are not package API signatures. Use the [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md) when you need exact current namespaces, evaluator construction, endpoint markers, or migration guidance.
+
 ### Tests
 
 Sample tests make important architectural claims repeatable and observable. Typical invariants include:

docs/getting-started/toc.yml

@@ -4,6 +4,8 @@
   href: learning-path-map.md
 - name: Find Your Path
   href: find-your-path.md
+- name: AsiBackbone 6.0 API Boundary
+  href: asibackbone-6-api-boundary.md
 - name: Adoption Personas and Entry Points
   href: adoption-personas-and-entry-points.md
 - name: Learning Model

docs/labs/build-a-governed-api-operation.md

@@ -665,6 +665,7 @@ A generic boolean does not say what was acknowledged or what operation it belong
 Create a small challenge model:
 
 ```csharp
+// Illustrative lab model; not an AsiBackbone package API.
 public sealed record AcknowledgmentChallenge(
     string ChallengeId,
     string ActorId,

docs/samples/index.md

@@ -7,6 +7,8 @@ _disableBreadcrumb: true
 
 Executable samples are the **runnable demonstration layer** of AsiBackbone Learning.
 
+> **Code scope:** These projects compile Learning-owned, framework-neutral teaching models. They do not currently reference `AsiBackbone.*` packages, and similarly named local types are not package API signatures. See the [AsiBackbone 6.0 API Boundary](../getting-started/asibackbone-6-api-boundary.md) for exact current API names, namespaces, and supported construction patterns.
+
 They sit between the problem-first tutorials and the hands-on labs:
 
 ```text

docs/tutorials/index.md

@@ -8,6 +8,8 @@ AsiBackbone Learning tutorials are **problem-first**. They begin with an archite
 
 The goal is understanding—not framework adoption.
 
+> **Code scope:** Tutorial snippets and companion projects are Learning-owned teaching models unless a section is explicitly labeled **AsiBackbone 6.0 API**. For exact current namespaces and syntax, use the [AsiBackbone 6.0 API Boundary](../getting-started/asibackbone-6-api-boundary.md).
+
 ## Learning Path at a Glance
 
 | Step | Tutorial | Difficulty | Boundary added |

samples/README.md

@@ -4,6 +4,8 @@ The `samples/` directory is the executable companion-code area for **AsiBackbone
 
 It is intended to contain intentionally small .NET examples that complement the architectural tutorials and make important system boundaries observable through runnable code and tests.
 
+> **Code scope:** Sample projects compile Learning-owned, framework-neutral teaching models. They do not currently reference `AsiBackbone.*` packages, and similarly named local types are not package API signatures. Use the [AsiBackbone 6.0 API Boundary](../docs/getting-started/asibackbone-6-api-boundary.md) for exact current namespaces, evaluator construction, endpoint markers, and migration guidance.
+
 > **Read it. Run it. Question it. Improve it.**
 
 ## Current Status