Table of Contents

Executable Samples

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 7.0 Compatibility and API Boundary for exact current API names, namespaces, and supported construction patterns.

They sit between the problem-first tutorials and the hands-on labs:

Tutorial
   ↓
Executable Sample
   ↓
Hands-On Lab
   ↓
Working Repository

The canonical sample source and detailed sample documentation remain under samples/ in the GitHub repository. This page keeps the published DocFX learning path intact while giving you enough information to choose and run the right companion sample before following the canonical README for deeper explanation.

Complete Sample Catalog

All executable sample projects currently under samples/ are listed below, grouped by the same learning areas used throughout the site.

Area Sample Core boundary
Foundational Decision Before Execution A blocked decision never reaches the executor.
Foundational Policy Context and Explicit Decision Outcomes Policy consumes explicit facts and returns a structured outcome without performing the side effect.
Foundational Decision Receipts and Acknowledgment Acknowledgment satisfies a governance requirement; it does not become execution authority.
Foundational Scoped Capability and Host-Owned Execution Narrow authority is validated again at the host-owned execution boundary.
Foundational Governed AI Tool Gateway The model may propose; the host retains execution authority.
Governance and Policy Architecture Decision Pipeline Refactoring Explicit outcomes remain separate from protected execution.
Governance and Policy Architecture Minimal Policy Simulation Harness Simulation evaluates policy behavior without creating execution authority.
Governance and Policy Architecture Federated Governance and Independent Authority Coordination An outage cannot reclassify a federated operation as local-only.
Governance and Policy Architecture Distributed Acknowledgment and Continuation Workflows Acknowledgment evidence is not portable execution authority.
Governance and Policy Architecture Decision Explainability for Human Operators Explanation projects governance evidence; it does not replace the evidence or create authority.
Governance and Policy Architecture Adaptive Risk Context, Freshness, and Drift Changing risk evidence triggers explicit freshness and reevaluation rules.
Security and Trust Architecture Replay Protection and Bounded-Use Authority Bounded-use authority needs an atomic state transition at the consumption boundary.
Security and Trust Architecture Cross-System Capability Exchange and Delegated Authority A cross-system artifact is validated into a local executor contract rather than used as one directly.
Security and Trust Architecture Durable Decision Ledger and Audit Chain Local chain verification and independently retained checkpoints provide different evidence properties.
ASP.NET Core Architecture Middleware Ordering Changes Behavior Middleware order changes which components can observe and handle a request or failure.
ASP.NET Core Architecture Centralized Error Handling and Problem Details Expected governance outcomes remain distinct from unexpected application failures.

Foundational Sample Set

The five foundational tutorials each have an executable companion sample.

Decision Before Execution

Learning objective: Observe how an explicit governance decision controls whether a host-owned executor is invoked.

Difficulty: Beginner

Key invariant:

A blocked decision never reaches the executor.

Run from the repository root:

dotnet run --project samples/decision-before-execution/Sample/DecisionBeforeExecution.csproj

Policy Context and Explicit Decision Outcomes

Learning objective: Observe how actor, resource, operation, environment, correlation, and policy identity become explicit decision inputs, and how policy returns meaningful outcomes instead of collapsing the result into a boolean.

Difficulty: Beginner

Key invariant:

Policy evaluation consumes an explicit context snapshot and returns a structured outcome without performing the governed side effect.

Run from the repository root:

dotnet run --project samples/policy-context-and-explicit-decision-outcomes/Sample/PolicyContextAndExplicitDecisionOutcomes.csproj

Decision Receipts and Acknowledgment

Learning objective: Observe how a consequential operation can pause for a narrowly bound acknowledgment, validate the response, re-evaluate current policy, and preserve a correlated audit timeline without treating acknowledgment as standing permission.

Difficulty: Intermediate

Key invariant:

Acknowledgment is a governance boundary, not an execution bypass.

Decision, acknowledgment, re-evaluation, and execution remain distinguishable evidence events throughout the flow.

Run from the repository root:

dotnet run --project samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj

Scoped Capability and Host-Owned Execution

Learning objective: Observe how an allowed decision can produce short-lived, narrowly bound execution authority and how the host validates those bindings again against current execution context immediately before the side effect.

Difficulty: Intermediate

Key invariants:

A blocked decision cannot mint execution authority.

Expired or stale execution authority never reaches the executor.

Run from the repository root:

dotnet run --project samples/scoped-capability-and-host-owned-execution/Sample/ScopedCapabilityAndHostOwnedExecution.csproj

Governed AI Tool Gateway

Learning objective: Run an end-to-end AI-assisted governance flow where a simulated model may propose a tool action, but the host owns the tool allowlist, authoritative context, policy decision, acknowledgment, scoped capability, dry-run execution, and audit evidence.

Difficulty: Advanced

Key invariant:

The model may propose. The host retains execution authority.

Run from the repository root:

dotnet run --project samples/governed-ai-tool-gateway/Sample/GovernedAiToolGateway.csproj

The same executable includes a deterministic local observability demonstration using ActivitySource, trace/span relationships, structured activity events, distinct proposal/correlation identity, policy-version evidence, and the existing decision receipt. It prints allowed, denied, and acknowledgment-required traces without requiring a real AI provider or telemetry backend.

Governance and Policy Architecture Samples

Decision Pipeline Refactoring

Learning objective: Diagnose governance logic scattered around protected side effects, then observe a reference refactor that makes authoritative context, explicit outcomes, continuation requirements, protected execution, and evidence distinct.

Difficulty: Intermediate

Key invariant:

Denied, Deferred, AcknowledgmentRequired, and EscalationRecommended produce zero executor calls; Allowed produces exactly one.

Run from the repository root:

dotnet run --project samples/decision-pipeline-refactoring/Sample/DecisionPipelineRefactoring.csproj

Minimal Policy Simulation Harness

Learning objective: Compare deterministic governance outcomes for the same fictional proposed intent while region, tenant, risk, environment, or policy version changes, without invoking a protected executor.

Difficulty: Intermediate

Key invariant:

Simulation evaluates policy behavior; it does not create execution authority or perform the governed side effect.

The sample emits structured scenario results with decision outcome, reason code, policy identity/version, matched constraint evidence, and an explicit non-execution marker.

Run from the repository root:

dotnet run --project samples/policy-simulation-harness/Sample/PolicySimulationHarness.csproj

Federated Governance and Independent Authority Coordination

Learning objective: Observe how independently operated governance authorities contribute to one deterministic decision while authority-set resolution, contribution health, disagreement handling, coordinator failure, and authority-set drift remain explicit.

Key invariant:

An outage cannot reclassify a federated operation as local-only.

Run from the repository root:

dotnet run --project samples/federated-governance-coordination/Sample/FederatedGovernanceCoordination.csproj

Run the focused tests:

dotnet test samples/federated-governance-coordination/Tests/FederatedGovernanceCoordination.Tests.csproj

Distributed Acknowledgment and Continuation Workflows

Learning objective: Observe acknowledgment evidence crossing system boundaries while recipient-owned trust validation, durable continuation binding, current-context reconstruction, current policy re-evaluation, a single-use continuation claim, and local execution authority remain separate.

Key invariant:

Acknowledgment evidence is not portable execution authority.

Run from the repository root:

dotnet run --project samples/distributed-acknowledgment-continuation/Sample/DistributedAcknowledgmentContinuation.csproj

Run the focused tests:

dotnet test samples/distributed-acknowledgment-continuation/Tests/DistributedAcknowledgmentContinuation.Tests.csproj

Decision Explainability for Human Operators

Learning objective: Observe how structured governance evidence can be projected into deterministic, audience-aware human explanations without rewriting the source decision, disclosing protected context, or creating new policy or execution authority.

Key invariant:

Human explanation is a projection of structured governance evidence. It is not the evidence itself and it does not create policy or execution authority.

Run from the repository root:

dotnet run --project samples/decision-explainability/Sample/DecisionExplainability.csproj

Run the focused tests:

dotnet test samples/decision-explainability/Tests/DecisionExplainability.Tests.csproj

Adaptive Risk Context, Freshness, and Drift

Learning objective: Observe how a changing risk observation stays bound to its original decision while freshness rules, policy drift, current-context reconstruction, re-evaluation, bounded authority, and final host-owned execution remain explicit.

Key invariant:

A changing risk signal triggers explicit freshness and reevaluation rules. It does not silently mutate authorization or execution authority.

Run from the repository root:

dotnet run --project samples/adaptive-risk-context/Sample/AdaptiveRiskContext.csproj

Run the focused tests:

dotnet test samples/adaptive-risk-context/Tests/AdaptiveRiskContext.Tests.csproj

Security and Trust Architecture Samples

Replay Protection and Bounded-Use Authority

Learning objective: Observe why bounded-use authority requires state, reproduce a check-then-act race, and prove that an atomic consume boundary permits exactly one consumer to claim the final use inside the teaching process.

Difficulty: Intermediate

Key invariant:

With MaximumUses = 1, two concurrent consumers produce one accepted consumption, one rejected replay, and one protected execution.

The sample also demonstrates that successful capability consumption does not establish exactly-once completion of an external side effect.

Run from the repository root:

dotnet run --project samples/replay-protection-and-bounded-use/Sample/ReplayProtectionAndBoundedUse.csproj

Cross-System Capability Exchange and Delegated Authority

Learning objective: Observe how a recipient independently validates issuer/key trust, audience and presenter bindings, operation/resource/request bindings, lifetime, delegation policy, revocation, local policy, and bounded-use state before creating a local command for a host-owned executor.

Key invariant:

The raw cross-system artifact never becomes the executor contract.

Run from the repository root:

dotnet run --project samples/cross-system-capability-exchange/Sample/CrossSystemCapabilityExchange.csproj

Run the focused tests:

dotnet test samples/cross-system-capability-exchange/Tests/CrossSystemCapabilityExchange.Tests.csproj

Durable Decision Ledger and Audit Chain

Learning objective: Observe how deterministic canonicalization, idempotent append semantics, predecessor linkage, streaming verification, and an independently retained checkpoint teaching model contribute different evidence properties without turning an in-memory chain into an immutable ledger.

Difficulty: Advanced

Key invariants:

A verified local prefix does not prove the newest records are present.

An independently retained checkpoint can expose a missing checkpointed tail, while a single verifier still cannot detect every split view without cross-verifier comparison.

Run from the repository root:

dotnet run --project samples/durable-decision-ledger-audit-chain/Sample/DurableDecisionLedgerAuditChain.csproj

Run the focused tests:

dotnet test samples/durable-decision-ledger-audit-chain/Tests/DurableDecisionLedgerAuditChain.Tests.csproj

ASP.NET Core Architecture Samples

Middleware Ordering Changes Behavior

Learning objective: Observe request/response traversal order and prove that an exception boundary can only handle failures produced by middleware or endpoints that execute downstream from it.

Difficulty: Intermediate

Key invariants:

Requests enter middleware in registration order; responses unwind in reverse order.

An exception boundary cannot catch a failure that occurs before the boundary is entered.

Run the corrected pipeline from the repository root:

dotnet run --project samples/middleware-ordering-changes-behavior/Sample/MiddlewareOrderingChangesBehavior.csproj -- --PipelineMode=correct --urls http://127.0.0.1:5080

Restart with --PipelineMode=incorrect to move the fault-producing middleware outside the sample exception boundary and compare the observable behavior.

Centralized Error Handling and Problem Details

Learning objective: Observe how a small ASP.NET Core host keeps unexpected application failures inside a centralized exception boundary while expected governance outcomes are mapped explicitly by the host, with safe Problem Details and trace correlation across the public and operational surfaces.

Key invariant:

A denied decision is not an exception merely because execution does not proceed.

Run from the repository root:

dotnet run --project samples/centralized-error-handling-and-problem-details/Sample/CentralizedErrorHandlingAndProblemDetails.csproj --urls http://127.0.0.1:5082

Run the focused integration tests:

dotnet test samples/centralized-error-handling-and-problem-details/Tests/CentralizedErrorHandlingAndProblemDetails.Tests.csproj

Run the Complete Sample Suite

The shared sample solution is samples/Samples.slnx.

From the repository root:

dotnet restore samples/Samples.slnx
dotnet build samples/Samples.slnx --no-restore
dotnet test samples/Samples.slnx --no-build

The focused xUnit projects make architectural invariants executable rather than leaving them only as prose claims.

Sample Design Principles

The canonical samples/README.md contains the full sample guidance. The recurring principles are:

  • Keep samples small. Optimize for learning value rather than production completeness.
  • Keep side effects visible. Evaluation, decision, and execution should remain distinguishable.
  • Test architectural invariants. Tests should prove meaningful boundaries such as blocked execution, stale capability rejection, and unknown-tool rejection.
  • Prefer deterministic local behavior. Use in-memory state, fakes, simulation, and dry-run execution where practical.
  • Use fictional data. Do not place real credentials, secrets, tokens, personal information, or production connection strings in teaching samples.
  • Keep secrets host-owned. A model or proposal generator should not receive infrastructure credentials merely because it can propose an action.
  • Do not hide policy in prompt text. Prompt guidance may influence a proposal, but host-side controls remain the authoritative execution boundary.
  • Prefer narrow semantic operations. Small operations are easier to validate, govern, test, and audit than broad arbitrary-execution primitives.

The samples intentionally omit production infrastructure that is not required to make the lesson visible. Follow each canonical README's What This Sample Intentionally Omits section before adapting a sample to a real system.

Working Implementations

After a sample or lab, compare the deliberately small teaching architecture with fuller implementations:

The goal is not to make the sample imitate production complexity. The goal is to make the architectural boundary recognizable before you inspect how broader operational concerns change it.

Source of Truth and Licensing

The detailed sample READMEs remain canonical under samples/; this DocFX page is a navigation and learning-path summary. When sample setup, behavior, or invariants change, update the canonical sample README first and keep this landing page's summary aligned with it.

Documentation and educational content in docs/ are licensed under CC BY 4.0. Executable sample code and sample projects under samples/ are licensed under the MIT License unless otherwise noted.

See LICENSING.md for the repository's component-specific licensing policy.

Read it. Run it. Question it. Improve it.

Edit this page