From ec606e7a32ca3e597dd31bfdc976bf7ea9390647 Mon Sep 17 00:00:00 2001 From: "Christopher D. Cavell" <28095137+cdcavell@users.noreply.github.com> Date: Fri, 18 Sep 2026 05:36:16 -0500 Subject: [PATCH 01/10] docs: align Learning terminology with AsiBackbone 6.0 (#343) Closes #339 ## Summary - align Learning terminology and branding with AsiBackbone 6.0 across documentation, navigation, diagrams, templates, and samples - replace obsolete audit-residue language with decision receipts while keeping acknowledgment, capability grants, and host-owned execution as distinct lifecycle concepts - rename the foundational tutorial, lab, and sample and update implementation links to the release/6.0.0 API surface - run documentation and sample validation for pull requests targeting release/1.0.0 ## Validation - `dotnet restore Samples.slnx --locked-mode` - `dotnet build Samples.slnx --no-restore` - `dotnet format Samples.slnx --verify-no-changes --no-restore --verbosity minimal` - `dotnet test Samples.slnx --no-build` (300 passed) - `dotnet tool run docfx docs/docfx.json --warningsAsErrors` - DocFX template baseline, metadata, sitemap, IndexNow, feed, and X publisher self-tests - Lychee link validation (2,784 OK, 0 errors, 3 configured exclusions) --- .gitattributes | 2 +- .github/DISCUSSION_TEMPLATE/show-and-tell.yml | 4 +- .../DISCUSSION_TEMPLATE/tutorial-ideas.yml | 2 +- .github/ISSUE_TEMPLATE/01-bug-report.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 4 +- .github/workflows/docs-validation.yml | 1 + .github/workflows/link-validation.yml | 2 +- .github/workflows/samples-validation.yml | 1 + .zenodo.json | 4 +- CHANGELOG.md | 2 +- CITATION.cff | 8 +- CODE_OF_CONDUCT.md | 8 +- CONTRIBUTING.md | 18 +- GOVERNANCE.md | 6 +- LICENSING.md | 2 +- README.md | 16 +- RELEASE.md | 2 +- ROADMAP.md | 26 +-- SECURITY.md | 6 +- SUPPORT.md | 2 +- X_PUBLISHING.md | 2 +- community/article-backlog.md | 8 +- community/requested-topics.md | 14 +- community/tutorial-ideas.md | 34 +-- ...sion-explainability-for-human-operators.md | 10 +- ...knowledgment-and-continuation-workflows.md | 6 +- ...-ledgers-and-cryptographic-audit-chains.md | 32 +-- ...ts-and-multi-agent-execution-boundaries.md | 12 +- ...governed-execution-in-regulated-systems.md | 4 +- docs/advanced/index.md | 16 +- .../regional-and-tenant-policy-overlays.md | 8 +- .../agent-memory-and-governance-boundaries.md | 14 +- ...ability-and-end-to-end-decision-tracing.md | 22 +- ...ction-uncertainty-and-recovery-patterns.md | 2 +- ...-tool-workflows-and-recovery-boundaries.md | 20 +- docs/ai-integration/index.md | 12 +- ...intent-and-schema-validation-boundaries.md | 6 +- ...ization-models-and-host-owned-execution.md | 4 +- ...eshes-zero-trust-and-governed-execution.md | 4 +- ... => asibackbone-and-governed-execution.md} | 23 +- .../constraint-conditioned-decision-model.md | 6 +- ...query-separation-and-governed-execution.md | 6 +- ...ails-and-governance-decision-provenance.md | 40 ++-- docs/architecture/glossary.md | 47 ++-- ...pine-and-capability-validation-diagrams.md | 8 +- ...vernance-tool-selection-and-composition.md | 2 +- docs/architecture/index.md | 12 +- ...ent-to-execution-accountability-pattern.md | 10 +- ...ines-and-distributed-policy-enforcement.md | 12 +- .../terminology-and-established-concepts.md | 39 ++-- docs/architecture/toc.yml | 4 +- ...-a-simple-application-service-is-enough.md | 4 +- ...s-human-approval-and-governed-execution.md | 6 +- ...ing-agent-diff-is-not-project-authority.md | 2 +- .../2026/authorization-check-runs-too-late.md | 2 +- ...-badge-does-not-prove-package-integrity.md | 4 +- docs/articles/index.md | 4 +- ...ized-error-handling-and-problem-details.md | 12 +- ...ss-boundaries-and-transaction-reasoning.md | 62 +++--- docs/aspnetcore/index.md | 6 +- ...d-logging-without-sensitive-data-sprawl.md | 18 +- ...pproval-and-infrastructure-change-gates.md | 2 +- .../governed-administrative-operation.md | 6 +- .../human-acknowledgment-workflow.md | 4 +- docs/docfx.json | 14 +- .../adoption-personas-and-entry-points.md | 6 +- docs/getting-started/find-your-path.md | 8 +- docs/getting-started/index.md | 10 +- docs/getting-started/learning-model.md | 4 +- docs/getting-started/learning-path-map.md | 8 +- ...raint-composition-and-policy-precedence.md | 16 +- ...obabilistic-inputs-in-policy-evaluation.md | 14 +- ...escalation-patterns-in-governed-systems.md | 20 +- .../human-in-the-loop-governance-workflows.md | 26 +-- docs/governance/index.md | 6 +- ...licy-versioning-and-decision-provenance.md | 20 +- ...y-testing-and-decision-table-strategies.md | 6 +- ...isk-based-decisions-in-governed-systems.md | 12 +- docs/images/architecture/governance-spine.svg | 2 +- docs/index.md | 10 +- ...nalyze-flawed-high-consequence-workflow.md | 4 +- docs/labs/build-a-governed-api-operation.md | 20 +- .../compare-competing-policy-architectures.md | 4 +- ...-owned-proposal-and-execution-authority.md | 2 +- docs/labs/decision-before-execution.md | 8 +- ...> decision-receipts-and-acknowledgment.md} | 64 +++--- docs/labs/governed-ai-tool-gateway.md | 14 +- docs/labs/hidden-execution-side-effect.md | 8 +- docs/labs/index.md | 22 +- ...-context-and-explicit-decision-outcomes.md | 12 +- ...y-simulation-and-change-impact-analysis.md | 12 +- ...ersion-evidence-in-governance-decisions.md | 14 +- .../labs/replay-protection-and-bounded-use.md | 6 +- ...-degraded-mode-and-fail-safe-governance.md | 6 +- ...ped-capability-and-host-owned-execution.md | 10 +- docs/labs/toc.yml | 4 +- docs/samples/index.md | 18 +- docs/samples/toc.yml | 4 +- docs/security/index.md | 4 +- .../replay-protection-and-bounded-use.md | 18 +- ...secret-handling-across-trust-boundaries.md | 4 +- .../secure-logging-across-trust-boundaries.md | 12 +- ...ication-key-custody-and-tamper-evidence.md | 20 +- ...chain-integrity-for-dotnet-repositories.md | 10 +- ...reat-modeling-as-architecture-reasoning.md | 6 +- .../trust-boundaries-and-least-privilege.md | 4 +- docs/templates/conceptual.extension.js | 2 +- docs/templates/layout/_master.tmpl | 6 +- docs/tutorials/decision-before-execution.md | 24 +-- ...> decision-receipts-and-acknowledgment.md} | 204 +++++++++--------- docs/tutorials/governed-ai-tool-gateway.md | 38 ++-- docs/tutorials/index.md | 8 +- ...-context-and-explicit-decision-outcomes.md | 44 ++-- ...ped-capability-and-host-owned-execution.md | 46 ++-- docs/tutorials/toc.yml | 4 +- samples/README.md | 20 +- samples/Samples.slnx | 4 +- samples/decision-before-execution/README.md | 8 +- .../README.md | 47 ++-- .../DecisionReceiptsAndAcknowledgment.csproj} | 0 .../Sample/Program.cs | 123 ++++++----- .../Sample/packages.lock.json | 0 .../Tests/AcknowledgmentBoundaryTests.cs | 24 +-- ...ionReceiptsAndAcknowledgment.Tests.csproj} | 2 +- .../Tests/packages.lock.json | 4 +- .../README.md | 4 +- samples/governed-ai-tool-gateway/README.md | 22 +- .../Sample/GovernanceObservability.cs | 28 +-- .../Sample/Program.cs | 16 +- .../Tests/GovernedGatewayTests.cs | 4 +- .../README.md | 10 +- samples/policy-simulation-harness/README.md | 2 +- .../README.md | 10 +- .../README.md | 26 +-- tools/generate-feed.cs | 8 +- tools/publish-x.cs | 2 +- tools/validate-doc-metadata.cs | 12 +- 137 files changed, 991 insertions(+), 942 deletions(-) rename docs/architecture/{accountable-systems-infrastructure-and-governed-execution.md => asibackbone-and-governed-execution.md} (82%) rename docs/labs/{acknowledgment-and-audit-residue.md => decision-receipts-and-acknowledgment.md} (83%) rename docs/tutorials/{acknowledgment-and-audit-residue.md => decision-receipts-and-acknowledgment.md} (75%) rename samples/{acknowledgment-and-audit-residue => decision-receipts-and-acknowledgment}/README.md (72%) rename samples/{acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj => decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj} (100%) rename samples/{acknowledgment-and-audit-residue => decision-receipts-and-acknowledgment}/Sample/Program.cs (87%) rename samples/{acknowledgment-and-audit-residue => decision-receipts-and-acknowledgment}/Sample/packages.lock.json (100%) rename samples/{acknowledgment-and-audit-residue => decision-receipts-and-acknowledgment}/Tests/AcknowledgmentBoundaryTests.cs (95%) rename samples/{acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj => decision-receipts-and-acknowledgment/Tests/DecisionReceiptsAndAcknowledgment.Tests.csproj} (86%) rename samples/{acknowledgment-and-audit-residue => decision-receipts-and-acknowledgment}/Tests/packages.lock.json (99%) diff --git a/.gitattributes b/.gitattributes index af55d00..a976d09 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,4 @@ -# ASI Backbone Learning - Git attributes +# AsiBackbone Learning - Git attributes # # Line-ending normalization is defined here rather than left to each # contributor's local Git configuration. Text files are stored with LF in the diff --git a/.github/DISCUSSION_TEMPLATE/show-and-tell.yml b/.github/DISCUSSION_TEMPLATE/show-and-tell.yml index e3e12f9..0b3f439 100644 --- a/.github/DISCUSSION_TEMPLATE/show-and-tell.yml +++ b/.github/DISCUSSION_TEMPLATE/show-and-tell.yml @@ -2,9 +2,9 @@ body: - type: markdown attributes: value: | - Use Show and tell to share projects, experiments, adaptations, diagrams, or implementations inspired by concepts and patterns from ASI Backbone Learning. + Use Show and tell to share projects, experiments, adaptations, diagrams, or implementations inspired by concepts and patterns from AsiBackbone Learning. - Sharing an implementation does not make it a canonical ASI Backbone pattern. Please describe what you changed, learned, and would like feedback on. + Sharing an implementation does not make it a canonical AsiBackbone pattern. Please describe what you changed, learned, and would like feedback on. - type: textarea id: project diff --git a/.github/DISCUSSION_TEMPLATE/tutorial-ideas.yml b/.github/DISCUSSION_TEMPLATE/tutorial-ideas.yml index 7adec0f..7bc2afa 100644 --- a/.github/DISCUSSION_TEMPLATE/tutorial-ideas.yml +++ b/.github/DISCUSSION_TEMPLATE/tutorial-ideas.yml @@ -2,7 +2,7 @@ body: - type: markdown attributes: value: | - Use Tutorial Ideas to propose new tutorials, labs, examples, learning paths, or educational topics for ASI Backbone Learning. + Use Tutorial Ideas to propose new tutorials, labs, examples, learning paths, or educational topics for AsiBackbone Learning. A good proposal starts with the learning problem before prescribing a particular product or implementation. diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.yml b/.github/ISSUE_TEMPLATE/01-bug-report.yml index b297517..b373a60 100644 --- a/.github/ISSUE_TEMPLATE/01-bug-report.yml +++ b/.github/ISSUE_TEMPLATE/01-bug-report.yml @@ -7,7 +7,7 @@ body: - type: markdown attributes: value: | - Thank you for helping improve ASI Backbone Learning. + Thank you for helping improve AsiBackbone Learning. Use this form for concrete defects in documentation, tutorials, samples, labs, DocFX output, workflows, links, or repository configuration. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 6d0c300..02b93cf 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,6 +1,6 @@ blank_issues_enabled: true contact_links: - - name: ASI Backbone Organization Discussions + - name: AsiBackbone Organization Discussions url: https://github.com/orgs/AsiBackbone/discussions - about: Ask architecture questions, propose learning topics, compare patterns, and discuss broader ideas across the ASI Backbone organization. \ No newline at end of file + about: Ask architecture questions, propose learning topics, compare patterns, and discuss broader ideas across the AsiBackbone organization. \ No newline at end of file diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml index 2bc8568..c5de426 100644 --- a/.github/workflows/docs-validation.yml +++ b/.github/workflows/docs-validation.yml @@ -9,6 +9,7 @@ on: pull_request: branches: - main + - release/1.0.0 push: branches: diff --git a/.github/workflows/link-validation.yml b/.github/workflows/link-validation.yml index fd37d64..edf04be 100644 --- a/.github/workflows/link-validation.yml +++ b/.github/workflows/link-validation.yml @@ -6,6 +6,7 @@ on: pull_request: branches: - main + - release/1.0.0 push: branches: @@ -59,4 +60,3 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} fail: true jobSummary: true - \ No newline at end of file diff --git a/.github/workflows/samples-validation.yml b/.github/workflows/samples-validation.yml index 0985465..ad395b8 100644 --- a/.github/workflows/samples-validation.yml +++ b/.github/workflows/samples-validation.yml @@ -6,6 +6,7 @@ on: pull_request: branches: - main + - release/1.0.0 push: branches: diff --git a/.zenodo.json b/.zenodo.json index b0ddd5c..dd9559b 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,8 +1,8 @@ { - "title": "ASI Backbone Learning", + "title": "AsiBackbone Learning", "version": "0.15.0", "upload_type": "lesson", - "description": "ASI Backbone Learning is the educational layer of the ASI Backbone organization: an open, community-oriented, DocFX-published collection of tutorials and architectural comparisons covering practical .NET architecture for governed execution, secure applications, AI integration, and policy-driven systems. Material connects conceptual explanations to working implementations in the AsiBackbone and NetCoreApplicationTemplate repositories. Learning is an educational and architectural resource; it is not a compliance certification, legal standard, security guarantee, or AI/AGI/ASI implementation. Documentation and educational material are licensed under CC BY 4.0. Executable sample code added under samples/ is licensed under the MIT License. See LICENSING.md for component-specific licensing terms.", + "description": "AsiBackbone Learning is the educational layer of the AsiBackbone organization: an open, community-oriented, DocFX-published collection of tutorials and architectural comparisons covering practical .NET architecture for governed execution, secure applications, AI integration, and policy-driven systems. Material connects conceptual explanations to working implementations in the AsiBackbone and NetCoreApplicationTemplate repositories. Learning is an educational and architectural resource; it is not a compliance certification, legal standard, security guarantee, or AI/AGI/ASI implementation. Documentation and educational material are licensed under CC BY 4.0. Executable sample code added under samples/ is licensed under the MIT License. See LICENSING.md for component-specific licensing terms.", "creators": [ { "name": "Cavell, Christopher D.", diff --git a/CHANGELOG.md b/CHANGELOG.md index bab0b7f..7be73af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ Learning releases are archival and citation snapshots of educational material. T ### Changed -- Aligned all sample tests on `Microsoft.Testing.Platform` and `xunit.v3`, matching the shared ASI Backbone repository posture. +- Aligned all sample tests on `Microsoft.Testing.Platform` and `xunit.v3`, matching the shared AsiBackbone repository posture. ## [0.15.0] - 2026-09-11 diff --git a/CITATION.cff b/CITATION.cff index 2bd563f..87f9fb3 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,10 +2,10 @@ cff-version: 1.2.0 message: >- If you use this material, please cite it using the metadata from this file. -title: "ASI Backbone Learning" +title: "AsiBackbone Learning" type: dataset abstract: >- - ASI Backbone Learning is the educational layer of the ASI Backbone + AsiBackbone Learning is the educational layer of the AsiBackbone organization: an open, community-oriented, DocFX-published collection of tutorials and architectural comparisons covering practical .NET architecture for governed execution, secure applications, AI integration, and @@ -31,7 +31,7 @@ identifiers: - type: doi value: "10.5281/zenodo.21938556" description: >- - Zenodo concept DOI for ASI Backbone Learning. Always resolves to the + Zenodo concept DOI for AsiBackbone Learning. Always resolves to the most recent archived version. Cite this when referring to the evolving work as a whole. repository-code: "https://github.com/AsiBackbone/Learning" @@ -51,7 +51,7 @@ keywords: - lesson references: - type: software - title: "ASI Backbone" + title: "AsiBackbone" authors: - family-names: Cavell given-names: "Christopher D." diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e351b69..b7dc6ed 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,7 +2,7 @@ ## Our Commitment -The ASI Backbone Learning community is intended to be a constructive, technically rigorous, and welcoming place for people to learn, question, experiment, and contribute. +The AsiBackbone Learning community is intended to be a constructive, technically rigorous, and welcoming place for people to learn, question, experiment, and contribute. We are committed to providing a community environment that is respectful and free from harassment, intimidation, and discrimination for everyone, regardless of experience level, background, identity, disability, appearance, nationality, race, ethnicity, religion, age, sex, gender identity or expression, sexual orientation, or other personal characteristics. @@ -46,7 +46,7 @@ A useful standard is: > Critique the pattern, implementation, evidence, or reasoning — not the person. -Canonical ASI Backbone patterns may be documented alongside alternative approaches when those alternatives are technically grounded and clearly identified. +Canonical AsiBackbone patterns may be documented alongside alternative approaches when those alternatives are technically grounded and clearly identified. ## Scope @@ -58,7 +58,7 @@ This Code of Conduct applies to participation in project spaces, including: - Code reviews - Documentation contributions - Repository-hosted community interactions -- Other public spaces where a participant is representing the ASI Backbone Learning project or organization +- Other public spaces where a participant is representing the AsiBackbone Learning project or organization It also applies when behavior outside the repository has a direct and material effect on the safety or effective participation of project contributors. @@ -110,6 +110,6 @@ The goal is to preserve an environment where participants can: ## Attribution -This Code of Conduct is maintained by the ASI Backbone Learning project and may evolve as the community grows. +This Code of Conduct is maintained by the AsiBackbone Learning project and may evolve as the community grows. Suggestions for improving the Code of Conduct may be proposed through the repository's normal contribution process. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32f2721..6c99645 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to ASI Backbone Learning +# Contributing to AsiBackbone Learning Thank you for your interest in contributing to `AsiBackbone/Learning`. @@ -106,7 +106,7 @@ Choose the category that best matches the conversation: - **Tutorial Ideas** — proposals for tutorials, labs, examples, learning paths, or future educational material. - **Show and tell** — projects, experiments, adaptations, diagrams, or implementations inspired by Learning concepts and patterns. -Use [**ASI Backbone Organization Discussions**](https://github.com/orgs/AsiBackbone/discussions) when a topic genuinely spans multiple ASI Backbone repositories or concerns the organization as a whole. +Use [**AsiBackbone Organization Discussions**](https://github.com/orgs/AsiBackbone/discussions) when a topic genuinely spans multiple AsiBackbone repositories or concerns the organization as a whole. A useful flow is: @@ -167,7 +167,7 @@ Where useful, distinguish among: - **Architecture Pattern** — the general idea - **Minimal Teaching Example** — the simplified demonstration -- **Working Repository Example** — the fuller implementation in another ASI Backbone repository +- **Working Repository Example** — the fuller implementation in another AsiBackbone repository Do not duplicate large portions of canonical implementation documentation when a direct reference will serve better. @@ -188,7 +188,7 @@ Where appropriate, include: Architectural disagreement can be educational. -Contributions may present approaches that differ from the current ASI Backbone implementation when those approaches are: +Contributions may present approaches that differ from the current AsiBackbone implementation when those approaches are: - Technically grounded - Clearly explained @@ -206,7 +206,7 @@ When architectural status materially affects how a page should be interpreted, u Use one of these values: -- **Canonical Pattern** — aligned with the current architecture of one or more ASI Backbone organization repositories. +- **Canonical Pattern** — aligned with the current architecture of one or more AsiBackbone organization repositories. - **Alternative Pattern** — a viable different approach, or a comparison centered on an approach that intentionally differs from the current canonical organization pattern. - **Experimental** — exploratory architecture that tests or extends boundaries without claiming an established organization pattern or production-ready design. Experimental pages should state important assumptions, unknowns, and limits explicitly. - **General learning material** — educational material for which no stronger architectural-status claim is necessary. @@ -524,7 +524,7 @@ Do not introduce category directories such as `articles/security/`, `articles/go ### Problem-Oriented Titles and Slugs -Lead with a developer problem rather than repository vocabulary. Use lowercase kebab-case slugs that remain meaningful outside the ASI Backbone organization. +Lead with a developer problem rather than repository vocabulary. Use lowercase kebab-case slugs that remain meaningful outside the AsiBackbone organization. Prefer: @@ -564,7 +564,7 @@ Before publishing a new standalone article, normally confirm that: - [ ] `feed: true` opts the article into the existing publication feed. - [ ] The article stands alone without requiring earlier tutorials or Learning-specific background. - [ ] The opening establishes a concrete technical problem before introducing repository-specific language. -- [ ] The article does not assume that the reader adopts `AsiBackbone` or another ASI Backbone implementation. +- [ ] The article does not assume that the reader adopts `AsiBackbone` or another AsiBackbone implementation. - [ ] Established concepts are distinguished from repository-specific terminology where appropriate. - [ ] Deeper tutorials, samples, labs, ADRs, or implementation material are linked rather than reproduced wholesale. - [ ] Contextual links identify a small number of natural next steps and explain why each destination is relevant; reciprocal links are added only where they improve reader flow. @@ -869,7 +869,7 @@ These requests are part of maintaining a useful learning resource. Do not report security vulnerabilities through a public Issue when disclosure could create risk. -Follow the security reporting guidance provided by the repository or ASI Backbone organization when available. +Follow the security reporting guidance provided by the repository or AsiBackbone organization when available. Never include: @@ -912,7 +912,7 @@ The project may recognize contributors through Git history, release notes, contr ## Questions -If you are unsure whether an idea belongs in the repository, start an [ASI Backbone Organization Discussion](https://github.com/orgs/AsiBackbone/discussions). +If you are unsure whether an idea belongs in the repository, start an [AsiBackbone Organization Discussion](https://github.com/orgs/AsiBackbone/discussions). If you have identified a concrete problem, open an Issue. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 82914d2..94751d7 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -72,7 +72,7 @@ Scoped authority ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` A useful design principle is: @@ -183,7 +183,7 @@ Significant decisions include: - Changes to licensing - Changes to project scope - Removal or deprecation of major tutorial areas -- Changes that materially alter how the project relates to other ASI Backbone repositories +- Changes that materially alter how the project relates to other AsiBackbone repositories These should normally be discussed publicly before implementation. @@ -205,7 +205,7 @@ Learning content may be classified to help readers understand its status. ### Canonical Pattern -A pattern aligned with the current documented architecture of one or more ASI Backbone organization repositories. +A pattern aligned with the current documented architecture of one or more AsiBackbone organization repositories. Canonical does not mean universally correct. diff --git a/LICENSING.md b/LICENSING.md index 2997177..dcccee0 100644 --- a/LICENSING.md +++ b/LICENSING.md @@ -1,6 +1,6 @@ # Licensing -ASI Backbone Learning contains educational material and executable +AsiBackbone Learning contains educational material and executable software examples distributed under different licenses. ## Documentation and Educational Material diff --git a/README.md b/README.md index 9930e05..afc8c9c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![Learning social image](https://raw.githubusercontent.com/AsiBackbone/Learning/main/docs/images/asibackbone-social.png) -# ASI Backbone Learning +# AsiBackbone Learning [![Documentation Validation](https://github.com/AsiBackbone/Learning/actions/workflows/docs-validation.yml/badge.svg?branch=main)](https://github.com/AsiBackbone/Learning/actions/workflows/docs-validation.yml) [![Samples Validation](https://github.com/AsiBackbone/Learning/actions/workflows/samples-validation.yml/badge.svg?branch=main)](https://github.com/AsiBackbone/Learning/actions/workflows/samples-validation.yml) @@ -14,7 +14,7 @@ **You can use this material without installing the `AsiBackbone` framework.** Tutorials, samples, comparisons, and labs are intended to remain useful as independent architecture education. -In this project, **ASI** means **Accountable Systems Infrastructure**. Learning is the educational layer of the ASI Backbone organization; it is not an artificial general intelligence or artificial superintelligence implementation. +`AsiBackbone` is the product name. Learning is the educational layer of the AsiBackbone organization and keeps its architecture lessons useful independently of the product implementation. ## Quick Start — Run It in 10 Minutes @@ -114,7 +114,7 @@ The established five-part sequence moves from proposed intent to governed AI-ass 1. [Decision Before Execution](docs/tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](docs/tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](docs/tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](docs/tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](docs/tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](docs/tutorials/governed-ai-tool-gateway.md) @@ -122,7 +122,7 @@ Each foundational topic is reinforced by runnable samples, focused architectural Want to understand why Learning uses a problem-first tutorial model, how tutorials differ from labs, or how canonical and alternative patterns are handled? See the [Learning Model](docs/getting-started/learning-model.md). -## ASI Backbone Ecosystem +## AsiBackbone Ecosystem The organization contains complementary projects with different responsibilities: @@ -136,7 +136,7 @@ Learning connects to the implementation repositories when fuller examples are us ## Scope and Boundaries -ASI Backbone Learning is an educational and architectural resource. +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. @@ -156,7 +156,7 @@ Use the canonical project surfaces for deeper information rather than treating t - **Contribution guidance:** [CONTRIBUTING.md](CONTRIBUTING.md) - **Project status and planned work:** [ROADMAP.md](ROADMAP.md) - **Learning discussions:** [AsiBackbone/Learning Discussions](https://github.com/AsiBackbone/Learning/discussions) -- **Organization-wide discussion:** [ASI Backbone Organization Discussions](https://github.com/orgs/AsiBackbone/discussions) +- **Organization-wide discussion:** [AsiBackbone Organization Discussions](https://github.com/orgs/AsiBackbone/discussions) - **Governance:** [GOVERNANCE.md](GOVERNANCE.md) - **Security policy:** [SECURITY.md](SECURITY.md) - **Citation metadata:** [CITATION.cff](CITATION.cff) @@ -198,7 +198,7 @@ verification commands. ## License -ASI Backbone Learning uses component-specific licensing: +AsiBackbone Learning uses component-specific licensing: - Documentation, educational material, and diagrams: **CC BY 4.0** - Executable sample code under `samples/`: **MIT License** @@ -208,6 +208,6 @@ See [LICENSING.md](LICENSING.md) for the complete licensing policy. --- -**ASI Backbone Learning is not intended to provide doctrine. It is intended to provide patterns worth examining.** +**AsiBackbone Learning is not intended to provide doctrine. It is intended to provide patterns worth examining.** Read them. Test them. Challenge them. Adapt them. Improve them. diff --git a/RELEASE.md b/RELEASE.md index 175a6ad..438d7cb 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -8,7 +8,7 @@ Publish a stable release only from a clean commit on protected `main`. Before pu The `Publish Stable Release Evidence` workflow runs again when the GitHub Release is published. It checks out the exact tag and fails unless all of these operations succeed: -The repository-level `global.json` makes `Microsoft.Testing.Platform` the canonical test runner for these commands, matching the runner posture used across the ASI Backbone repositories. +The repository-level `global.json` makes `Microsoft.Testing.Platform` the canonical test runner for these commands, matching the runner posture used across the AsiBackbone repositories. ```powershell dotnet restore samples/Samples.slnx --locked-mode diff --git a/ROADMAP.md b/ROADMAP.md index c695f6b..3fd85b4 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -26,7 +26,7 @@ automation, and community intake surfaces. 1. [Decision Before Execution](docs/tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](docs/tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](docs/tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](docs/tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](docs/tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](docs/tutorials/governed-ai-tool-gateway.md) @@ -47,7 +47,7 @@ Scoped authority ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` The repository therefore enters a **post-foundation maintenance mode** rather than @@ -110,7 +110,7 @@ area solely for breadth: The Learning repository should become: -* A clear educational entry point into the ASI Backbone organization. +* A clear educational entry point into the AsiBackbone organization. * A practical learning resource rather than a product manual. * A bridge between architectural reasoning and working .NET implementations. * A source of intentionally small executable examples. @@ -252,7 +252,7 @@ They do not replace host-side policy, validation, authorization, or execution co ### Canonical Does Not Mean Universal -A canonical pattern represents an approach aligned with one or more current ASI Backbone organization implementations. +A canonical pattern represents an approach aligned with one or more current AsiBackbone organization implementations. It does not mean that the approach is universally correct. @@ -447,12 +447,12 @@ Escalate * [x] Pair with learner exercise. * [x] Strengthen links to working implementation references. -### Tutorial 3 — Acknowledgment and Audit Residue +### Tutorial 3 — Decision Receipts and Acknowledgment * [x] Publish foundational tutorial. * [x] Explain acknowledgment as a governance boundary. * [x] Preserve distinction between acknowledgment and authorization. -* [x] Explain decision lineage and audit residue. +* [x] Explain decision lineage and decision receipt. * [x] Address reason codes, correlation, and policy identity. * [x] Distinguish operational logging from governance evidence. * [x] Pair with executable companion sample. @@ -482,7 +482,7 @@ Escalate * [x] Include scoped authority. * [x] Preserve host-owned execution. * [x] Address tool allowlists and argument validation. -* [x] Discuss audit residue and failure handling. +* [x] Discuss decision receipt and failure handling. * [x] Pair with executable companion sample. ([#4](https://github.com/AsiBackbone/Learning/issues/4)) * [x] Add end-to-end lab. ([#4](https://github.com/AsiBackbone/Learning/issues/4)) * [x] Expand threat-model exercises. ([#4](https://github.com/AsiBackbone/Learning/issues/4)) @@ -525,7 +525,7 @@ They should not attempt to reproduce the full `AsiBackbone` or `NetCoreApplicati * [x] Decision Before Execution sample. * [x] Policy Context and Explicit Decision Outcomes sample. -* [x] Acknowledgment and Audit Residue sample. +* [x] Decision Receipts and Acknowledgment sample. * [x] Scoped Capability and Host-Owned Execution sample. ([#3](https://github.com/AsiBackbone/Learning/issues/3)) * [x] Governed AI Tool Gateway sample. ([#4](https://github.com/AsiBackbone/Learning/issues/4)) @@ -629,7 +629,7 @@ Potential initial labs: ### Intermediate Labs * [x] Add acknowledgment to a consequential workflow. -* [x] Preserve an audit receipt. +* [x] Preserve an decision receipt. * [x] Introduce capability-scoped execution. ([#3](https://github.com/AsiBackbone/Learning/issues/3)) * [x] Build a governed API operation. ([#54](https://github.com/AsiBackbone/Learning/issues/54)) * [x] Refactor scattered governance logic into a decision pipeline. ([#221](https://github.com/AsiBackbone/Learning/issues/221)) @@ -1299,7 +1299,7 @@ Useful signals include: * Questions converted into improved explanations. * Architectural discussions converted into tutorials or labs when they expose a real gap. * Alternative patterns contributed and reviewed. -* Patterns reused outside ASI Backbone repositories. +* Patterns reused outside AsiBackbone repositories. * Community Issues and Discussions. * External pull requests. * Contributors who begin with documentation or samples and later participate elsewhere in the organization. @@ -1323,7 +1323,7 @@ The Learning repository is not intended to become: * A certification program. * A security guarantee. * A production robotics controller. -* A repository that attempts to prove the broader theoretical ASI Backbone or Eden Hypothesis framework. +* A repository that attempts to prove the broader theoretical AsiBackbone or Eden Hypothesis framework. Its purpose is narrower: @@ -1333,12 +1333,12 @@ Its purpose is narrower: ## Long-Term Direction -Over time, Learning may become the primary educational entry point into the ASI Backbone organization. +Over time, Learning may become the primary educational entry point into the AsiBackbone organization. A mature learning ecosystem could look like: ```text - ASI Backbone Organization + AsiBackbone Organization | +--------------+--------------+ | | diff --git a/SECURITY.md b/SECURITY.md index aa39da3..55f60ba 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ Thank you for taking the time to report security concerns responsibly. -ASI Backbone Learning is an educational repository for practical .NET architecture, governed execution, policy-driven systems, secure application design, AI integration, and related architectural patterns. +AsiBackbone Learning is an educational repository for practical .NET architecture, governed execution, policy-driven systems, secure application design, AI integration, and related architectural patterns. The repository contains documentation, diagrams, exercises, executable teaching samples, and documentation/build automation. It is not a production security product, compliance certification, AI model, AGI or ASI implementation, autonomous-agent runtime, or robotics controller. @@ -110,7 +110,7 @@ Do not describe a repository, package, template, sample, workflow, or generated Areas especially relevant to this repository include: * executable teaching samples under `samples/`; -* examples that demonstrate policy evaluation, acknowledgment, audit residue, scoped capability, or host-owned execution; +* examples that demonstrate policy evaluation, acknowledgment, decision receipt, scoped capability, or host-owned execution; * AI tool-gateway examples and host-side execution boundaries; * sample handling of secrets, credentials, tokens, connection strings, or sensitive-looking data; * documentation that could materially misstate a security boundary or encourage unsafe production behavior; @@ -203,7 +203,7 @@ Repository cleanup does not invalidate a credential that has already been expose ## Reports for Related Repositories -Learning frequently links to fuller implementations in other ASI Backbone organization repositories. +Learning frequently links to fuller implementations in other AsiBackbone organization repositories. Security concerns in those implementations should be reported to the repository that owns the affected code: diff --git a/SUPPORT.md b/SUPPORT.md index 178fc9d..becca8a 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -10,7 +10,7 @@ Use [GitHub Discussions](https://github.com/orgs/AsiBackbone/discussions) for: - Help understanding or applying a tutorial or sample. - Ideas for new learning material that are not yet focused work items. - Comparing canonical, alternative, or experimental patterns. -- Broader questions that span multiple ASI Backbone repositories. +- Broader questions that span multiple AsiBackbone repositories. Use [GitHub Issues](https://github.com/AsiBackbone/Learning/issues) for: diff --git a/X_PUBLISHING.md b/X_PUBLISHING.md index 04d60bb..d996271 100644 --- a/X_PUBLISHING.md +++ b/X_PUBLISHING.md @@ -52,7 +52,7 @@ cannot be overridden by repository or workflow input. The post text is deterministic: ```text -New from ASI Backbone Learning: +New from AsiBackbone Learning: {title} diff --git a/community/article-backlog.md b/community/article-backlog.md index c8c9328..7c10e83 100644 --- a/community/article-backlog.md +++ b/community/article-backlog.md @@ -4,7 +4,7 @@ This backlog prioritizes candidate standalone technical articles for `AsiBackbon It is an editorial planning surface, not a publication quota and not a second curriculum roadmap. `ROADMAP.md` remains the strategic source of truth for Learning. [Requested Topics](requested-topics.md) remains the community intake surface for curriculum ideas. This backlog answers a narrower question: -> **Which existing Learning ideas are strong candidates for a standalone, problem-oriented article that can be useful before a reader knows ASI Backbone terminology?** +> **Which existing Learning ideas are strong candidates for a standalone, problem-oriented article that can be useful before a reader knows AsiBackbone terminology?** The current Articles archive demonstrates the intended shape with [Your Authorization Check Runs Too Late](../docs/articles/2026/authorization-check-runs-too-late.md) and [A Green CI Badge Does Not Prove Your .NET Package Is Trustworthy](../docs/articles/2026/ci-badge-does-not-prove-package-integrity.md). @@ -186,7 +186,7 @@ Teams often use `authorized`, `approved`, `confirmed`, and `acknowledged` as if #### Existing Learning support - [Human-in-the-Loop Governance Workflows](../docs/governance/human-in-the-loop-governance-workflows.md) -- [Acknowledgment and Audit Residue](../docs/tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../docs/tutorials/decision-receipts-and-acknowledgment.md) - [Workflow Engines, Human Approval Systems, and Governed Execution](../docs/architecture/workflow-engines-human-approval-and-governed-execution.md) - [When ASP.NET Core Authorization Is Enough](../docs/architecture/when-aspnet-core-authorization-is-enough.md) @@ -196,7 +196,7 @@ The deeper pages model complete review and workflow lifecycles. This article sho #### Natural deeper path -Lead to Human-in-the-Loop Governance Workflows for long-running review and to Acknowledgment and Audit Residue for the pause/resume evidence model. +Lead to Human-in-the-Loop Governance Workflows for long-running review and to Decision Receipts and Acknowledgment for the pause/resume evidence model. --- @@ -212,7 +212,7 @@ A team already records application or security logs and wants to know whether th #### Existing Learning support -- [Acknowledgment and Audit Residue](../docs/tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../docs/tutorials/decision-receipts-and-acknowledgment.md) - [Event Sourcing, Audit Trails, and Governance Decision Provenance](../docs/architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md) - [Secure Logging Across Trust Boundaries](../docs/security/secure-logging-across-trust-boundaries.md) - [Policy Versioning and Decision Provenance](../docs/governance/policy-versioning-and-decision-provenance.md) diff --git a/community/requested-topics.md b/community/requested-topics.md index 0787b59..e456add 100644 --- a/community/requested-topics.md +++ b/community/requested-topics.md @@ -14,7 +14,7 @@ Standalone article candidates are curated separately in the [Problem-Oriented St ## How to Request a Topic -For a new topic request, prefer opening an [ASI Backbone Organization Discussion](https://github.com/orgs/AsiBackbone/discussions) when the subject is exploratory, architectural, or likely to benefit from community input. +For a new topic request, prefer opening an [AsiBackbone Organization Discussion](https://github.com/orgs/AsiBackbone/discussions) when the subject is exploratory, architectural, or likely to benefit from community input. Use an Issue when the requested work is already concrete and well scoped. @@ -24,7 +24,7 @@ A useful request includes: - Why the topic matters in practice. - What level of detail would be most useful. - Whether you would prefer a tutorial, lab, diagram, comparison, or worked example. -- Any existing ASI Backbone or NetCoreApplicationTemplate implementation that appears relevant. +- Any existing AsiBackbone or NetCoreApplicationTemplate implementation that appears relevant. - Any specific tradeoff or failure mode you want examined. You do not need to know the solution before requesting a topic. @@ -57,7 +57,7 @@ A topic may be **Published** here while a narrower follow-up, alternative treatm These topics shaped the initial Learning roadmap and now have published coverage in the foundational tutorial/sample/test/lab path. Their original questions and suggested formats are retained below as historical planning context. -The published foundation consists of [Decision Before Execution](../docs/tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../docs/tutorials/policy-context-and-explicit-decision-outcomes.md), [Acknowledgment and Audit Residue](../docs/tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../docs/tutorials/scoped-capability-and-host-owned-execution.md), and [Governed AI Tool Gateway](../docs/tutorials/governed-ai-tool-gateway.md), with corresponding runnable samples under [`samples/`](../samples/README.md) and learner labs under [`docs/labs/`](../docs/labs/index.md). +The published foundation consists of [Decision Before Execution](../docs/tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../docs/tutorials/policy-context-and-explicit-decision-outcomes.md), [Decision Receipts and Acknowledgment](../docs/tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../docs/tutorials/scoped-capability-and-host-owned-execution.md), and [Governed AI Tool Gateway](../docs/tutorials/governed-ai-tool-gateway.md), with corresponding runnable samples under [`samples/`](../samples/README.md) and learner labs under [`docs/labs/`](../docs/labs/index.md). ### Decision Before Execution @@ -160,7 +160,7 @@ Suggested format: --- -### Audit Residue and Provenance +### Decision Receipt and Provenance **Status:** Published @@ -169,7 +169,7 @@ Explain the difference between normal application logs and durable governance ev Questions to address: - What should survive a decision? -- What is a useful audit receipt? +- What is a useful decision receipt? - How should reason codes, policy versions, hashes, correlation IDs, and timestamps be used? - What should not be placed in an audit record? - How should privacy and sensitive data affect audit design? @@ -752,7 +752,7 @@ Clarify when orchestration and governance overlap and when they should remain se ### Intermediate - [ ] Add acknowledgment to a sensitive operation. -- [ ] Generate an audit receipt. +- [ ] Generate an decision receipt. - [ ] Add a scoped capability. - [ ] Refactor scattered policy checks into a governance pipeline. - [ ] Add tests for policy edge cases. @@ -780,7 +780,7 @@ Requested diagrams include: - [ ] Capability issuance and validation. - [ ] Host-owned execution boundary. - [ ] AI tool gateway. -- [ ] Logging versus audit residue. +- [ ] Logging versus decision receipt. - [ ] Authentication/authorization/governance comparison. - [ ] Policy composition. - [ ] Regional policy overlay. diff --git a/community/tutorial-ideas.md b/community/tutorial-ideas.md index aa99156..9b0b6e1 100644 --- a/community/tutorial-ideas.md +++ b/community/tutorial-ideas.md @@ -4,7 +4,7 @@ This page collects tutorial concepts that may become future Learning material. -Unlike [requested-topics.md](requested-topics.md), which tracks subjects the community would like to see addressed, this page focuses on **possible tutorial shapes**: concrete lessons that could be written, demonstrated, tested, and connected to the working ASI Backbone repositories. +Unlike [requested-topics.md](requested-topics.md), which tracks subjects the community would like to see addressed, this page focuses on **possible tutorial shapes**: concrete lessons that could be written, demonstrated, tested, and connected to the working AsiBackbone repositories. These ideas are not release commitments. @@ -111,7 +111,7 @@ Scoped Authority ↓ Host-Owned Execution ↓ -Audit Residue +Decision Receipt ``` #### Teaching Opportunities @@ -290,7 +290,7 @@ Add acknowledgment to an already authenticated and authorized administrative wor --- -### 6. Designing an Acknowledgment Handshake +### 6. Designing an Acknowledgment Flow #### Working Title @@ -347,7 +347,7 @@ Review three approval dialogs and determine which one actually supports informed ## Audit and Provenance Tutorials -### 8. Logging Is Not an Audit Receipt +### 8. Logging Is Not an Decision Receipt #### Working Title @@ -355,7 +355,7 @@ Review three approval dialogs and determine which one actually supports informed #### Learning Objective -Understand why logs and audit residue serve different purposes. +Understand why logs and decision receipt serve different purposes. #### Comparison Areas @@ -379,13 +379,13 @@ Understand why logs and audit residue serve different purposes. #### Possible Lab -Given a set of application logs, design the smallest useful governance receipt. +Given a set of application logs, design the smallest useful decision receipt. -**Status:** Published — covered by Acknowledgment and Audit Residue +**Status:** Published — covered by Decision Receipts and Acknowledgment --- -### 9. Designing an Audit Receipt +### 9. Designing an Decision Receipt #### Working Title @@ -583,7 +583,7 @@ Host Tool Gateway ↓ Tool Execution ↓ -Audit Residue +Decision Receipt ``` #### Teaching Opportunities @@ -896,7 +896,7 @@ Understand the supply-chain value of immutable action references. #### Possible Working Reference -Use existing ASI Backbone workflow patterns as examples. +Use existing AsiBackbone workflow patterns as examples. **Status:** Candidate @@ -1286,7 +1286,7 @@ Identify missing boundaries: - Explicit decision. - Scoped authority. - Host-owned execution. -- Audit residue. +- Decision receipt. **Status:** High-value AI failure-mode tutorial @@ -1300,7 +1300,7 @@ Identify missing boundaries: 2. Policy Context 3. Explicit Decision Outcomes 4. Acknowledgment -5. Audit Residue +5. Decision Receipt 6. Scoped Capability 7. Host-Owned Execution @@ -1402,7 +1402,7 @@ Uses failing tests to reveal an architectural requirement. ## Ideas for Beginner-Friendly Tutorials -Potential beginner contributions should avoid requiring deep familiarity with the complete ASI Backbone architecture. +Potential beginner contributions should avoid requiring deep familiarity with the complete AsiBackbone architecture. Examples: @@ -1411,7 +1411,7 @@ Examples: - Why middleware order matters. - What is a reason code? - Authentication versus authorization. -- What is an audit receipt? +- What is an decision receipt? - Why validate configuration at startup? - Why avoid logging secrets? - What does a lock file do? @@ -1465,7 +1465,7 @@ Use AsiBackbone for: - Decision - Acknowledgment - Capability -- Audit residue +- Decision receipt #### Learning Goal @@ -1538,7 +1538,7 @@ What architectural pattern addresses the problem? ### Working Reference -Is there relevant code, documentation, an ADR, or a test in another ASI Backbone repository? +Is there relevant code, documentation, an ADR, or a test in another AsiBackbone repository? ### Suggested Format @@ -1643,7 +1643,7 @@ The list is retained to show how the original curriculum shaped the current repo 2. **Policy Context** 3. **Beyond `bool`: Explicit Decision Outcomes** 4. **Acknowledgment Is Not Authentication** -5. **Logging Is Not an Audit Receipt** +5. **Logging Is Not an Decision Receipt** 6. **Approval Is Not Permanent Authority** 7. **Host-Owned Execution** 8. **Building a Governed AI Tool Gateway in ASP.NET Core** diff --git a/docs/advanced/decision-explainability-for-human-operators.md b/docs/advanced/decision-explainability-for-human-operators.md index 40a43f8..ff4959e 100644 --- a/docs/advanced/decision-explainability-for-human-operators.md +++ b/docs/advanced/decision-explainability-for-human-operators.md @@ -12,11 +12,11 @@ description: Derive audience-appropriate explanations from structured governance **Difficulty:** Advanced -**Required prerequisites:** [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) and [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md). +**Required prerequisites:** [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) and [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md). **Recommended background:** [AI Governance Observability and End-to-End Decision Tracing](../ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md), [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md), and [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md). -**Glossary:** [Audit residue](../architecture/glossary.md#audit-residue), [decision provenance](../architecture/glossary.md#decision-provenance), [governed execution](../architecture/glossary.md#governed-execution), and [trust boundary](../architecture/glossary.md#trust-boundary). +**Glossary:** [Decision receipt](../architecture/glossary.md#decision-receipt), [decision provenance](../architecture/glossary.md#decision-provenance), [governed execution](../architecture/glossary.md#governed-execution), and [trust boundary](../architecture/glossary.md#trust-boundary). > **Scope:** This article treats explanation as a derived presentation layer over structured governance evidence. It does not define a legal right-to-explanation standard, a universal explanation schema, a localization framework, a production redaction engine, or a generative-AI product architecture. @@ -539,7 +539,7 @@ Audience CorrelationId ``` -The projection should not replace the evidence store with only those fields. They are lineage references, not a complete governance receipt. +The projection should not replace the evidence store with only those fields. They are lineage references, not a complete decision receipt. --- @@ -844,7 +844,7 @@ No downstream authorization or execution component should parse the explanation Use the structured decision object for machine behavior. -This keeps the familiar ASI Backbone boundary intact: +This keeps the familiar AsiBackbone boundary intact: > **Presentation may describe authority. Presentation does not create authority.** @@ -1001,7 +1001,7 @@ The companion tests make the presentation boundaries explicit. Continue with: - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) for policy identity, historical evidence, and drift. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for decision, acknowledgment, and evidence separation. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for decision, acknowledgment, and evidence separation. - [AI Governance Observability and End-to-End Decision Tracing](../ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md) for telemetry and end-to-end correlation. - [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md) for minimizing operational event data. - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) for provider, transport, storage, access, and retention boundaries around telemetry. diff --git a/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md b/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md index 0a28337..3bd56df 100644 --- a/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md +++ b/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md @@ -12,11 +12,11 @@ description: Learn how acknowledgment can cross process and system boundaries wi **Difficulty:** Advanced -**Required prerequisites:** [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). +**Required prerequisites:** [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). **Recommended background:** [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md), [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md), [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md), and [Cross-System Capability Exchange and Delegated Authority](cross-system-capability-exchange-and-delegated-authority.md). -**Glossary:** [Acknowledgment](../architecture/glossary.md#acknowledgment), [audit residue](../architecture/glossary.md#audit-residue), [decision provenance](../architecture/glossary.md#decision-provenance), [scoped capability](../architecture/glossary.md#scoped-capability), [execution authority](../architecture/glossary.md#execution-authority), and [trust boundary](../architecture/glossary.md#trust-boundary). +**Glossary:** [Acknowledgment](../architecture/glossary.md#acknowledgment), [decision receipt](../architecture/glossary.md#decision-receipt), [decision provenance](../architecture/glossary.md#decision-provenance), [scoped capability](../architecture/glossary.md#scoped-capability), [execution authority](../architecture/glossary.md#execution-authority), and [trust boundary](../architecture/glossary.md#trust-boundary). > **Framework-neutral scope:** This article teaches lifecycle, trust, replay, recovery, and authority boundaries. It does not define a messaging protocol, workflow product, identity federation scheme, signature format, durable-store technology, or exactly-once execution mechanism. @@ -991,7 +991,7 @@ Distributed continuation is not a maturity upgrade. It is justified only when th Continue with: -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for the foundational acknowledgment lifecycle. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for the foundational acknowledgment lifecycle. - [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) when an independent reviewer disposition, rather than acknowledgment, is the requirement. - [Human Acknowledgment Workflow](../case-studies/human-acknowledgment-workflow.md) for the detailed single-system persistence, race, evidence, and changed-state case study. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) for narrow continuation authority and executor ownership. diff --git a/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md b/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md index 81db8e2..a8cfe41 100644 --- a/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md +++ b/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md @@ -1,10 +1,10 @@ --- -description: Learn how governance receipts form verifiable, append-oriented evidence chains through canonicalization, links, signatures, checkpoints, and key lifecycle. +description: Learn how decision receipts form verifiable, append-oriented evidence chains through canonicalization, links, signatures, checkpoints, and key lifecycle. --- # Durable Decision Ledgers and Cryptographic Audit Chains -**Learning objective:** Understand how governance receipts can be preserved as a durable, append-oriented evidence chain whose integrity claims remain explicit across canonicalization, ordering, hash linkage, optional signatures, checkpoints, key rotation, retention, archival, migration, restore, and corruption handling. +**Learning objective:** Understand how decision receipts can be preserved as a durable, append-oriented evidence chain whose integrity claims remain explicit across canonicalization, ordering, hash linkage, optional signatures, checkpoints, key rotation, retention, archival, migration, restore, and corruption handling. **Pattern classification:** General learning material @@ -30,7 +30,7 @@ The central lesson is: This treatment assumes: -- A governance workflow already produces purpose-built receipts or residue for consequential decision events. +- A governance workflow already produces purpose-built receipts for consequential decision events. - The host can identify which evidence must survive process restarts and operational-log retention. - A ledger can define a stable ordering within an explicit ledger or partition identity. - Cryptographic algorithms and key providers are selected through an application-specific security process rather than invented inside the ledger code. @@ -38,7 +38,7 @@ This treatment assumes: This treatment does **not** assume: -- A governance receipt is an event-sourced domain event. +- A decision receipt is an event-sourced domain event. - A durable store is append-only merely because application code exposes only `Append`. - A hash proves who created a record. - A signature proves that a decision was correct or remains authorized. @@ -71,7 +71,7 @@ Remove one of those assumptions and the claim may narrow. The teaching threat model considers accidental corruption, privileged local modification/deletion, insertion/reordering, tail truncation/rollback, whole-chain replacement, split-view/equivocation, signing-key lifecycle problems, and migration/restore mistakes. It assumes standard cryptographic primitives are implemented by established libraries/providers rather than broken by the ledger itself. -It does **not** attempt to solve Byzantine consensus among mutually distrustful writers, prove the truthfulness of data before it enters the ledger, protect an already-compromised endpoint that fabricates governance receipts before canonicalization, or define a universal legal evidentiary standard. Those require different system boundaries. +It does **not** attempt to solve Byzantine consensus among mutually distrustful writers, prove the truthfulness of data before it enters the ledger, protect an already-compromised endpoint that fabricates decision receipts before canonicalization, or define a universal legal evidentiary standard. Those require different system boundaries. --- @@ -80,7 +80,7 @@ It does **not** attempt to solve Byzantine consensus among mutually distrustful A simple append lifecycle is: ```text -Governance receipt N +Decision receipt N ↓ Canonical representation ↓ @@ -147,7 +147,7 @@ A system can contain several historical artifacts at the same time. | Artifact | Primary job | What it is not automatically | | --- | --- | --- | | Operational log | Troubleshooting, observability, diagnostics | Durable governance evidence | -| Governance receipt | Explain one decision or lifecycle transition | Ordered ledger | +| Decision receipt | Explain one decision or lifecycle transition | Ordered ledger | | Decision ledger | Preserve ordered governance evidence across time | Domain-state source | | Event-sourced domain event | Reconstruct accepted domain state | Complete governance decision record | | Execution authority | Permit a narrowly bound side effect when currently valid | Historical evidence | @@ -157,7 +157,7 @@ The boundaries remain useful even if several artifacts share one physical databa ```text Operational log != -Governance receipt +Decision receipt != Decision ledger != @@ -166,9 +166,9 @@ Event-sourced domain state Execution authority ``` -### Governance receipt versus operational log +### Decision receipt versus operational log -A governance receipt may need to answer which intent was evaluated, which policy version participated, which outcome/reason codes resulted, whether acknowledgment was required, and which execution state followed. +A decision receipt may need to answer which intent was evaluated, which policy version participated, which outcome/reason codes resulted, whether acknowledgment was required, and which execution state followed. An operational log may instead answer which dependency timed out, how long the request took, and which exception path executed. @@ -267,7 +267,7 @@ A canonicalization contract should define at least: A safer lifecycle is: ```text -Typed governance receipt +Typed decision receipt ↓ Versioned canonical representation ↓ @@ -1347,10 +1347,10 @@ The current `AsiBackbone/AsiBackbone` repository contains working primitives tha | Learning concept | Source / test reference | What to inspect | | --- | --- | --- | -| Deterministic canonical payload construction | [`CanonicalPayloadBuilder.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/CanonicalPayloadBuilder.cs) and [`CanonicalPayloadBuilderBranchTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/CanonicalPayloadBuilderBranchTests.cs) | Stable field construction, canonicalization rules, branch coverage, and payload identity. | -| Signed-artifact construction | [`GovernanceArtifactSigner.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/GovernanceArtifactSigner.cs) and [`GovernanceArtifactSignerTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/GovernanceArtifactSignerTests.cs) | How canonical hashes become signing requests and provider-neutral signed-artifact metadata. | -| Verification as a policy outcome | [`GovernanceArtifactVerifier.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/GovernanceArtifactVerifier.cs) and [`VerificationPolicyHandlingTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/VerificationPolicyHandlingTests.cs) | Preflight checks, explicit verification categories, and host policy mapping instead of one trusted boolean. | -| Audit-ledger evidence model | [`AuditLedgerRecord.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`AuditLedgerRecordTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) | The current audit-ledger record shape and its limits; this is adjacent evidence plumbing, not proof of a complete chained ledger. | +| Deterministic canonical payload construction | [`CanonicalPayloadBuilder.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/CanonicalPayloadBuilder.cs) and [`CanonicalPayloadBuilderBranchTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/CanonicalPayloadBuilderBranchTests.cs) | Stable field construction, canonicalization rules, branch coverage, and payload identity. | +| Signed-artifact construction | [`GovernanceArtifactSigner.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/GovernanceArtifactSigner.cs) and [`GovernanceArtifactSignerTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/GovernanceArtifactSignerTests.cs) | How canonical hashes become signing requests and provider-neutral signed-artifact metadata. | +| Verification as a policy outcome | [`GovernanceArtifactVerifier.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/GovernanceArtifactVerifier.cs) and [`VerificationPolicyHandlingTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/VerificationPolicyHandlingTests.cs) | Preflight checks, explicit verification categories, and host policy mapping instead of one trusted boolean. | +| Audit-ledger evidence model | [`AuditLedgerRecord.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`AuditLedgerRecordTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) | The current audit-ledger record shape and its limits; this is adjacent evidence plumbing, not proof of a complete chained ledger. | For the broader implementation wording and lifecycle guidance, the existing AsiBackbone articles on signing-ready receipts, verification policy, key rotation, signed audit/outbox records, and cryptographic production posture remain useful context. The source/test links above demonstrate primitives; they still do not prove protected checkpoints, independent witnesses, trusted timestamping, or a production-grade append chain in any deployment. @@ -1436,7 +1436,7 @@ If they are implicit, "immutable audit ledger" is probably stronger language tha - [Advanced](index.md) — return to the Advanced learning-area overview. - [Event Sourcing, Audit Trails, and Governance Decision Provenance](../architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md) — distinguish domain state, operational logs, audit records, and governance provenance before adding a chain. - [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) — study the cryptographic primitives and wording boundaries that this lifecycle composes. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — identify the decision, acknowledgment, and execution residue that may require durable preservation. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — identify the decision receipt and correlated acknowledgment or execution evidence that may require durable preservation. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — preserve the policy identity needed to interpret historical decisions. - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) — keep operational telemetry, governance evidence, data minimization, retention, and evidence-failure semantics distinct. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — preserve the boundary between historical evidence and current execution authority. diff --git a/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md b/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md index a3a0192..03b5aa0 100644 --- a/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md +++ b/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md @@ -1912,11 +1912,11 @@ The working `AsiBackbone` repository provides useful governance primitives and e Useful implementation specimens include: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — establishes the single-agent boundary where the agent proposes and the host owns policy context, execution, and operational safeguards. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — provides provider-neutral capability metadata that can be studied for subject, operation, resource, audience, scope, policy, and time bindings. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — covers proof, binding, failure, time, and bounded-use concerns at the execution boundary. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — provides structured governance evidence that can participate in a larger host-owned decision chain. -- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — reinforces that governance artifacts do not themselves perform the protected side effect. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — establishes the single-agent boundary where the agent proposes and the host owns policy context, execution, and operational safeguards. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — provides provider-neutral capability metadata that can be studied for subject, operation, resource, audience, scope, policy, and time bindings. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — covers proof, binding, failure, time, and bounded-use concerns at the execution boundary. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provides structured governance evidence that can participate in a larger host-owned decision chain. +- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — reinforces that governance artifacts do not themselves perform the protected side effect. These references provide building blocks to inspect. @@ -2028,7 +2028,7 @@ If those answers are unclear, adding more agents may have increased orchestratio - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) — identify where agent and service hops change what the system is willing to trust. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — examine replay, atomic consumption, distributed use state, and idempotency boundaries. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — preserve policy identity and reason about stale decisions during long-running workflows. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — keep human responsibility and durable evidence distinct from agent-generated approval language. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — keep human responsibility and durable evidence distinct from agent-generated approval language. --- diff --git a/docs/advanced/governed-execution-in-regulated-systems.md b/docs/advanced/governed-execution-in-regulated-systems.md index 43076d8..477fb38 100644 --- a/docs/advanced/governed-execution-in-regulated-systems.md +++ b/docs/advanced/governed-execution-in-regulated-systems.md @@ -10,7 +10,7 @@ description: Learn how governed execution can contribute decision evidence in re **Difficulty:** Advanced -**Prerequisites:** [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md), [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), and [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) +**Prerequisites:** [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md), [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), and [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) Public-sector and regulated systems often need more than proof that an action happened. @@ -110,7 +110,7 @@ That crosswalk is product-owned because it maps named external references to act - [Regional Policy and Operational Gateways](regional-policy-and-operational-gateways.md) - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) - [Decision Explainability for Human Operators](decision-explainability-for-human-operators.md) diff --git a/docs/advanced/index.md b/docs/advanced/index.md index eac4b66..2d2c5d4 100644 --- a/docs/advanced/index.md +++ b/docs/advanced/index.md @@ -1,10 +1,10 @@ --- -description: Explore advanced ASI Backbone Learning topics requiring deeper reasoning about interacting boundaries, assumptions, failure modes, and tradeoffs. +description: Explore advanced AsiBackbone Learning topics requiring deeper reasoning about interacting boundaries, assumptions, failure modes, and tradeoffs. --- # Advanced -The Advanced section is reserved for topics that build on the foundational ASI Backbone Learning material and require deeper architectural reasoning, broader system context, or comparison among competing approaches. +The Advanced section is reserved for topics that build on the foundational AsiBackbone Learning material and require deeper architectural reasoning, broader system context, or comparison among competing approaches. Advanced does not mean that a pattern is automatically better. @@ -37,7 +37,7 @@ Readers should generally be familiar with the foundational tutorial sequence: 1. [Decision Before Execution](../tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) @@ -58,7 +58,7 @@ Scoped Authority ↓ Host-Owned Execution ↓ -Audit Residue +Decision Receipt ``` Advanced material may stretch, combine, distribute, or challenge these boundaries, but it should make those changes explicit. @@ -268,7 +268,7 @@ Advanced material should ask: * Is compensation possible? * Does the original capability remain valid? * Should a new governance decision be required? -* What audit residue should distinguish attempted, partial, failed, and completed execution? +* What correlated lifecycle evidence should distinguish attempted, partial, failed, and completed execution? Governance does not remove distributed-systems failure modes. @@ -422,7 +422,7 @@ The objective is to make the consequences of each design visible. ## Challenge the Canonical Pattern -Some Learning material reflects architectural patterns currently used by ASI Backbone organization repositories. +Some Learning material reflects architectural patterns currently used by AsiBackbone organization repositories. Those patterns should remain open to criticism. @@ -464,7 +464,7 @@ These scenarios help expose architectural assumptions that may remain hidden dur ## Working Repository References -Advanced Learning material may use both primary ASI Backbone organization repositories as implementation specimens. +Advanced Learning material may use both primary AsiBackbone organization repositories as implementation specimens. ### AsiBackbone @@ -474,7 +474,7 @@ Provides fuller governance and policy-control implementations that can be studie * Decision pipelines * Acknowledgment -* Audit residue +* Decision receipt * Capability boundaries * Host-owned execution * AI governance integration diff --git a/docs/advanced/regional-and-tenant-policy-overlays.md b/docs/advanced/regional-and-tenant-policy-overlays.md index 83ba048..4855bd5 100644 --- a/docs/advanced/regional-and-tenant-policy-overlays.md +++ b/docs/advanced/regional-and-tenant-policy-overlays.md @@ -1190,9 +1190,9 @@ then the protected operation should not execute through that path. --- -## Relationship to the Broader ASI Backbone Concept +## Relationship to the Broader AsiBackbone Concept -The broader ASI Backbone concept has used regional policy mediation as one architectural illustration: globally useful intent can be constrained by regional rules before consequential local execution. +The broader AsiBackbone concept has used regional policy mediation as one architectural illustration: globally useful intent can be constrained by regional rules before consequential local execution. This Learning article does not require an AGI or ASI system. @@ -1242,7 +1242,7 @@ The current `AsiBackbone` repository provides useful specimens for several piece ### Custom Decision Policy Examples -[Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) includes a regional overlay example that preserves an existing block and applies additional local restrictions or acknowledgment requirements. +[Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) includes a regional overlay example that preserves an existing block and applies additional local restrictions or acknowledgment requirements. That example demonstrates one **narrowing-overlay** model. @@ -1250,7 +1250,7 @@ It should not be read as a complete universal global/region/tenant hierarchy. ### Policy Evaluator Pipeline -[Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) shows the distinction between constraint evaluation, base composition, an optional decision policy, and host-owned execution. +[Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) shows the distinction between constraint evaluation, base composition, an optional decision policy, and host-owned execution. Those seams can participate in a host-defined overlay architecture, but the host still needs to define the authority relationship among independently versioned policy layers. diff --git a/docs/ai-integration/agent-memory-and-governance-boundaries.md b/docs/ai-integration/agent-memory-and-governance-boundaries.md index 5c2ad13..2522605 100644 --- a/docs/ai-integration/agent-memory-and-governance-boundaries.md +++ b/docs/ai-integration/agent-memory-and-governance-boundaries.md @@ -748,11 +748,11 @@ No privilege should accumulate merely because a sequence of earlier sessions con --- -## Memory, Audit Residue, and Governance Evidence Serve Different Purposes +## Memory, Decision Receipt, and Governance Evidence Serve Different Purposes Memory helps future work remember context. -Audit residue helps reconstruct what happened in a governed path. +Decision receipt helps reconstruct what happened in a governed path. Those goals overlap but are not identical. @@ -1229,10 +1229,10 @@ This article describes a host architecture boundary. It does not imply that `Asi Existing governance primitives remain useful reference points for preserving the distinction between remembered information and current authority: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured current governance outcomes should remain distinct from remembered historical decisions. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — governance evidence has a different lifecycle and purpose from model-visible memory. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — narrow authority should remain an explicit capability concern rather than being reconstructed from memory. -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — reinforces the boundary in which the model proposes and the host owns context, policy, and execution. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured current governance outcomes should remain distinct from remembered historical decisions. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — governance evidence has a different lifecycle and purpose from model-visible memory. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — narrow authority should remain an explicit capability concern rather than being reconstructed from memory. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — reinforces the boundary in which the model proposes and the host owns context, policy, and execution. The host remains responsible for the memory store, retention model, source validation, isolation strategy, retrieval policy, and any product-specific user controls. @@ -1279,7 +1279,7 @@ If the answer to the last question is unclear, memory has probably crossed an au - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — construct current authoritative policy context explicitly. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — preserve current policy identity and decision lineage without relying on remembered summaries. - [Deterministic and Probabilistic Inputs in Policy Evaluation](../governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md) — classify model-derived or uncertain information separately from authoritative deterministic facts. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — distinguish historical acknowledgment and durable governance evidence from memory. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — distinguish historical acknowledgment and durable governance evidence from memory. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — keep execution authority explicit, bounded, and validated at the execution boundary. - [Secret Handling Across Trust Boundaries](../security/secret-handling-across-trust-boundaries.md) — keep credentials and sensitive secret material out of general model-visible memory. - [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md) — model memory stores, retrieval, poisoning, isolation, and execution boundaries as part of the system threat model. diff --git a/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md b/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md index a8dc3b1..bea6833 100644 --- a/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md +++ b/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md @@ -10,13 +10,13 @@ description: Trace AI proposals through validation, governance, acknowledgment, **Difficulty:** Advanced -**Prerequisites:** [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md), [Typed AI Proposed Intent and Schema-Validation Boundaries](typed-ai-proposed-intent-and-schema-validation-boundaries.md), [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and familiarity with [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md). +**Prerequisites:** [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md), [Typed AI Proposed Intent and Schema-Validation Boundaries](typed-ai-proposed-intent-and-schema-validation-boundaries.md), [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and familiarity with [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md). ## Pattern Card > **Problem:** A governed AI system may preserve the execution boundary correctly while still be difficult to diagnose. After a model proposes an operation, developers and operators need to reconstruct what happened without treating telemetry as permission. > -> **Pattern:** Carry stable proposal and correlation identifiers through host-owned validation, context construction, governance, acknowledgment, scoped authority, execution, and evidence. Use trace/span relationships, structured events, stable reason codes, and separate audit residue to make the path inspectable. +> **Pattern:** Carry stable proposal and correlation identifiers through host-owned validation, context construction, governance, acknowledgment, scoped authority, execution, and evidence. Use trace/span relationships, structured events, stable reason codes, and separate decision receipt to make the path inspectable. > > **Use when:** AI-proposed tool execution, agent workflows, human acknowledgment, or scoped-capability execution need enough evidence to reconstruct decisions and verify important architectural invariants. > @@ -53,7 +53,7 @@ Execution-boundary validation ↓ Host-owned executor ↓ -Audit residue +Decision receipt ``` Observability adds a parallel evidence path: @@ -63,7 +63,7 @@ Governed workflow │ ├── trace/span relationships ├── structured operational events - └── audit residue / receipt + └── decision receipt ``` The evidence path should let a learner inspect a statement such as: @@ -99,7 +99,7 @@ A production trace often contains several identifiers. They are related, but the | **Reason code** | Stable machine-readable explanation for a governance outcome. | Decision evidence lifecycle. | | **Acknowledgment identity** | Binds a response to a particular acknowledgment requirement. | Acknowledgment lifecycle. | | **Capability ID** | Identifies narrow follow-on execution authority. | Capability lifetime. | -| **Audit receipt / residue ID** | Identifies retained governance evidence. | Evidence-retention period. | +| **Decision receipt ID** | Identifies the retained policy-decision record. | Evidence-retention period. | A useful mental model is: @@ -134,7 +134,7 @@ ai.governance.workflow │ ├── event: capability-consumption │ ├── executor.invoke │ └── event: execution -└── correlated audit residue +└── correlated decision receipt ``` For an acknowledgment-required path, the same logical workflow may contain two gateway passes: @@ -569,9 +569,9 @@ The working `AsiBackbone` repository contains an `AsiBackbone.OpenTelemetry` pac Useful implementation references include: -- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/README.md) -- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) -- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) +- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/README.md) +- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) +- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) The working package exposes activity events/tags, metrics, stable governance attributes, trace/span identifiers, decision metadata, lifecycle information, and emission outcomes. @@ -614,7 +614,7 @@ The observability tests verify the architectural outcomes rather than a particul ### 1. One Identifier for Everything -The proposal ID, workflow correlation ID, trace ID, and audit receipt are treated as interchangeable. +The proposal ID, workflow correlation ID, trace ID, and decision receipt are treated as interchangeable. That becomes fragile when retries, asynchronous work, or delayed acknowledgment appear. @@ -695,7 +695,7 @@ After completing this tutorial and running the sample, you should be able to: - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — the foundational end-to-end host-owned execution path. - [Typed AI Proposed Intent and Schema-Validation Boundaries](typed-ai-proposed-intent-and-schema-validation-boundaries.md) — the model-output acceptance boundary. - [Governed Multi-Tool Workflows and Recovery Boundaries](governed-multi-tool-workflows-and-recovery-boundaries.md) — extends the tracing problem into multiple governed steps, partial failure, replanning, and recovery. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — deeper treatment of responsibility and evidence stages. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — deeper treatment of responsibility and evidence stages. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — policy identity, drift, provenance, and freshness. - [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md) — operational event design and data minimization. - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) — provider, collector, storage, access, retention, and tenant boundaries. diff --git a/docs/ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md b/docs/ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md index 4346bb7..908a668 100644 --- a/docs/ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md +++ b/docs/ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md @@ -986,7 +986,7 @@ For operational data-minimization guidance, see [Secure Logging Across Trust Bou A minimized recovery record might include: ```csharp -public sealed record ProposalAttemptResidue( +public sealed record ProposalAttemptReceipt( string WorkflowId, string CorrelationId, string ProposalId, diff --git a/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md b/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md index 356415d..2f8d11b 100644 --- a/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md +++ b/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md @@ -1063,7 +1063,7 @@ what failed operationally what remains unattempted ``` -This distinction matters for both recovery and audit residue. +This distinction matters for both recovery and decision receipt. --- @@ -1192,7 +1192,7 @@ Some dependencies support cooperative cancellation before the side effect. Others may complete despite the host abandoning the request. -Audit residue should record that distinction. +Correlated lifecycle evidence should record that distinction without rewriting the original decision receipt. --- @@ -1230,7 +1230,7 @@ Human review changes the decision path only through explicit host-owned rules. --- -## Correlation and Audit Residue Should Preserve the Step History +## Correlated Lifecycle Evidence Should Preserve the Step History A useful audit chain can reconstruct the workflow without pretending that every event had the same outcome. @@ -1372,8 +1372,8 @@ foreach (ProposedWorkflowStep step in workflow.Steps) > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to keep the execution-boundary concept distinct from the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). This sketch intentionally leaves out acknowledgment, escalation, retries, durable persistence, and distributed coordination details. @@ -1677,14 +1677,14 @@ This tutorial focuses on execution and recovery across steps. This tutorial is framework-neutral. -The working `AsiBackbone` repository provides governance artifacts that can participate in a per-step design, including structured governance decisions, acknowledgment/handshake requests, audit residue, and capability-token grants. +The working `AsiBackbone` repository provides governance artifacts that can participate in a per-step design, including structured governance decisions, acknowledgment/handshake requests, decision receipt, and capability-token grants. Useful references include: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) Those abstractions do not make `AsiBackbone` a model runtime or workflow engine. diff --git a/docs/ai-integration/index.md b/docs/ai-integration/index.md index 162b4b6..a8614fe 100644 --- a/docs/ai-integration/index.md +++ b/docs/ai-integration/index.md @@ -43,7 +43,7 @@ Execution-Boundary Validation ↓ Host-Owned Tool Execution ↓ -Audit Residue +Decision Receipt ``` The model may help determine what operation should be proposed. @@ -66,9 +66,9 @@ Introduces the separation between proposed intent, governance evaluation, and re Explores authoritative context, constraints, explicit governance outcomes, reason codes, and policy identity. -### 3. Acknowledgment and Audit Residue +### 3. Decision Receipts and Acknowledgment -[Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +[Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) Examines workflows that pause for acknowledgment and preserve evidence of the governed decision path. @@ -102,7 +102,7 @@ This advanced tutorial distinguishes host-authoritative deterministic facts from [AI Governance Observability and End-to-End Decision Tracing](ai-governance-observability-and-end-to-end-decision-tracing.md) -This advanced tutorial shows how correlation IDs, proposal IDs, trace/span relationships, structured events, decision reason codes, policy provenance, acknowledgment, scoped authority, executor invocation, and audit residue can be connected without allowing telemetry to become authorization or execution authority. The companion Governed AI Tool Gateway sample includes deterministic allowed, denied, and acknowledgment-required traces that can be inspected locally without a real AI service or telemetry backend. +This advanced tutorial shows how correlation IDs, proposal IDs, trace/span relationships, structured events, decision reason codes, policy provenance, acknowledgment, scoped authority, executor invocation, and decision receipt can be connected without allowing telemetry to become authorization or execution authority. The companion Governed AI Tool Gateway sample includes deterministic allowed, denied, and acknowledgment-required traces that can be inspected locally without a real AI service or telemetry backend. ### Multi-Step AI Composition: Governed Multi-Tool Workflows and Recovery Boundaries @@ -346,7 +346,7 @@ Execution Authority See: -[Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +[Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) ## Dry-Run First @@ -373,7 +373,7 @@ This allows developers to observe: * Which policy decisions occur. * Whether acknowledgment is triggered. * Which execution authority would be issued. -* What audit residue would be preserved. +* What decision receipt would be preserved. Real external execution can be introduced after the boundaries are understood and tested. diff --git a/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md b/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md index 7e56ed4..556829d 100644 --- a/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md +++ b/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md @@ -1780,7 +1780,7 @@ Execution-boundary validation ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` This tutorial zooms into the first transition: @@ -1824,8 +1824,8 @@ The Learning repository already contains an executable capstone that demonstrate The `AsiBackbone/AsiBackbone` repository provides fuller governance references: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — keeps AI-proposed action separate from host-owned execution. -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — demonstrates acknowledgment as a separate boundary before consequential tool execution. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — keeps AI-proposed action separate from host-owned execution. +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — demonstrates acknowledgment as a separate boundary before consequential tool execution. These working references do not make raw model output authoritative. diff --git a/docs/architecture/agent-and-tool-authorization-models-and-host-owned-execution.md b/docs/architecture/agent-and-tool-authorization-models-and-host-owned-execution.md index 162b358..e52b10b 100644 --- a/docs/architecture/agent-and-tool-authorization-models-and-host-owned-execution.md +++ b/docs/architecture/agent-and-tool-authorization-models-and-host-owned-execution.md @@ -19,7 +19,7 @@ feed: true > **Industry anchors:** Frameworks and ecosystems such as LangChain, Semantic Kernel, AutoGen, and Model Context Protocol (MCP) servers/registries expose different ways to register, discover, or provide tools and functions. They are orientation points for searchability, not endorsements or definitions of the authorization boundary. In particular, tool discovery or registration through one of these mechanisms does not by itself establish resource-level permission or execution authority. -> **Standalone-reader note:** In this article, **Learning** means the ASI Backbone Learning repository and tutorial series. Its recurring rule is: **The model may propose. The host retains execution authority.** The host may be a conventional application, an agent runtime that is deliberately trusted as the execution boundary, a background worker, a tool gateway, or another component that owns the real side effect. +> **Standalone-reader note:** In this article, **Learning** means the AsiBackbone Learning repository and tutorial series. Its recurring rule is: **The model may propose. The host retains execution authority.** The host may be a conventional application, an agent runtime that is deliberately trusted as the execution boundary, a background worker, a tool gateway, or another component that owns the real side effect. Use this page as the **detailed reference comparison** across tool visibility, framework registration, agent permissions, authorization, capabilities, credential custody, and host-owned execution. If you want the shorter standalone argument that isolates the proposal-versus-authority boundary around one minimal `case.add-note` loop, start with [Why an AI Tool Call Is a Proposal, Not Authority](../articles/2026/why-ai-tool-call-is-only-a-proposal.md). @@ -1378,7 +1378,7 @@ Use these pages for deeper treatment of specific boundaries: - [Governed Multi-Tool Workflows and Recovery Boundaries](../ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md) — step-scoped execution, replanning, retry, and recovery. - [AI Proposal Rejection, Uncertainty, and Recovery Patterns](../ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md) — bounded retry and proposal rejection without weakening the host boundary. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — authoritative context and explicit decision semantics. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — acknowledgment as a distinct governance boundary. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — acknowledgment as a distinct governance boundary. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — narrow delegated execution authority. - [Role-Based, Claims-Based, and Capability-Based Authorization](role-based-claims-based-and-capability-based-authorization.md) — standing identity/claims authority compared with bounded capabilities. - [Workflow Engines, Human Approval Systems, and Governed Execution](workflow-engines-human-approval-and-governed-execution.md) — approval, workflow state, policy, and execution authority as separate or composable concerns. diff --git a/docs/architecture/api-gateways-service-meshes-zero-trust-and-governed-execution.md b/docs/architecture/api-gateways-service-meshes-zero-trust-and-governed-execution.md index 426e182..bd4560e 100644 --- a/docs/architecture/api-gateways-service-meshes-zero-trust-and-governed-execution.md +++ b/docs/architecture/api-gateways-service-meshes-zero-trust-and-governed-execution.md @@ -447,7 +447,7 @@ Scoped authority when required ↓ Host-owned execution ↓ -Audit residue / decision evidence +Decision receipt / decision evidence ``` This model is useful when the application must preserve distinctions that ordinary request admission does not express cleanly. @@ -614,7 +614,7 @@ They should not be substituted for one another. A `200` at an API gateway does not explain why a production deployment was approved. -A governance receipt does not prove that the service-to-service channel used mTLS. +A decision receipt does not prove that the service-to-service channel used mTLS. The strongest architecture preserves the evidence needed for each boundary and correlates it without pretending that one log is every kind of proof. diff --git a/docs/architecture/accountable-systems-infrastructure-and-governed-execution.md b/docs/architecture/asibackbone-and-governed-execution.md similarity index 82% rename from docs/architecture/accountable-systems-infrastructure-and-governed-execution.md rename to docs/architecture/asibackbone-and-governed-execution.md index 8bbce41..9c19982 100644 --- a/docs/architecture/accountable-systems-infrastructure-and-governed-execution.md +++ b/docs/architecture/asibackbone-and-governed-execution.md @@ -1,10 +1,10 @@ --- -description: Learn the Accountable Systems Infrastructure framing and how governed execution separates proposed intent from consequential side effects. +description: Learn how AsiBackbone frames governed execution by separating proposed intent from consequential side effects. --- -# Accountable Systems Infrastructure and Governed Execution +# AsiBackbone and Governed Execution -**Learning objective:** Understand the Accountable Systems Infrastructure framing and how it separates intent, context, decision, acknowledgment, authority, execution, and evidence without assuming every application needs the pattern. +**Learning objective:** Understand how AsiBackbone separates intent, context, decision, acknowledgment, authority, execution, and evidence without assuming every application needs the pattern. **Pattern classification:** General learning material @@ -12,7 +12,7 @@ description: Learn the Accountable Systems Infrastructure framing and how govern **Prerequisites:** None. [Decision Before Execution](../tutorials/decision-before-execution.md) is a useful next step for applying the framing. -Within the ASI Backbone organization, **ASI** means **Accountable Systems Infrastructure**. +`AsiBackbone` is the product name. Historically, **ASI** expanded to **Accountable Systems Infrastructure**; that project-history detail is not a separate runtime concept and is not required vocabulary for using the architecture. The phrase describes an architectural concern rather than a specific package: consequential software actions should pass through an explicit, reviewable decision boundary before a trusted host performs the real-world side effect. @@ -31,21 +31,22 @@ A third question becomes important when actions are consequential, delayed, dele > **Why was this exact action permitted, under which policy and context, with what acknowledgment or scoped authority, before execution occurred?** -Accountable Systems Infrastructure focuses on that gap. +AsiBackbone focuses on that gap. -## A reusable governance spine +## A reusable policy decision pipeline -A stack-neutral governance spine can be expressed as: +A stack-neutral policy decision pipeline can be expressed as: ~~~text Intent or proposed action -> Authoritative policy context -> Constraint evaluation -> Explicit decision outcome + -> Decision receipt -> Acknowledgment or escalation when required -> Scoped continuation authority when required -> Host-owned execution - -> Audit residue and reconciliation + -> Correlated lifecycle evidence and reconciliation ~~~ The stages are logical responsibilities. They may live in one process, several services, a workflow engine, or a gateway architecture. @@ -63,7 +64,7 @@ The important separation is between **proposal**, **decision**, **authority**, a | Acknowledgment | Record a required human or system responsibility checkpoint without treating it as execution authority by itself. | | Scoped authority | Carry narrow, short-lived authority across a delay, process boundary, or executor boundary when that is justified. | | Host-owned execution | Let the component with the real credentials and side-effect capability make the final enforcement decision. | -| Audit residue | Preserve enough structured evidence to reconstruct why the path was taken. | +| Decision receipt | Preserve enough structured evidence to reconstruct why the path was taken. | ## Why host-owned execution matters @@ -81,7 +82,7 @@ The trusted host or executor still owns concerns such as: - physical or external-system safety controls; - legal and compliance interpretation. -The governance spine can inform, constrain, record, and sometimes issue narrow continuation authority. It does not remove those responsibilities. +The policy decision pipeline can inform, constrain, record, and sometimes issue narrow continuation authority. It does not remove those responsibilities. At an architectural level, the complete end-to-end arrangement may be described as a governance spine. ## When the pattern is useful @@ -97,7 +98,7 @@ The pattern becomes more valuable when one or more of these conditions exist: ## When a simpler design is better -Do not introduce a governance spine merely because the pattern exists. +Do not introduce a broader governance pipeline merely because the pattern exists. A simpler authorization handler or application service is often better when: diff --git a/docs/architecture/constraint-conditioned-decision-model.md b/docs/architecture/constraint-conditioned-decision-model.md index 6b66222..5430a45 100644 --- a/docs/architecture/constraint-conditioned-decision-model.md +++ b/docs/architecture/constraint-conditioned-decision-model.md @@ -12,7 +12,7 @@ description: Use a constraint-conditioned decision model to reason about how act **Prerequisites:** [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) and [Constraint Composition and Policy Precedence](../governance/constraint-composition-and-policy-precedence.md) -A recurring ASI Backbone teaching idea is that open intent should not become arbitrary action. +A recurring AsiBackbone teaching idea is that open intent should not become arbitrary action. In software architecture terms: @@ -111,7 +111,7 @@ The point is that the decision vocabulary should be explicit and bounded. A poli | `ΛS(x, τ)` | Conceptual measure of how strongly the current state and structure narrow the proposal | | Residual openness | Ability to defer, revise, acknowledge, escalate, or re-evaluate | | Collapse boundary | Point where proposal becomes an explicit decision, not where a side effect automatically occurs | -| Residue | Structured evidence describing the decision path | +| Receipt | Structured evidence describing the decision path | ## Toy model: time-window change @@ -181,7 +181,7 @@ The architectural value is the structure-conditioned reasoning pattern. ## Continue learning -- [Accountable Systems Infrastructure and Governed Execution](accountable-systems-infrastructure-and-governed-execution.md) +- [AsiBackbone and Governed Execution](asibackbone-and-governed-execution.md) - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) - [Constraint Composition and Policy Precedence](../governance/constraint-composition-and-policy-precedence.md) - [Regional and Tenant Policy Overlays](../advanced/regional-and-tenant-policy-overlays.md) diff --git a/docs/architecture/cqrs-command-query-separation-and-governed-execution.md b/docs/architecture/cqrs-command-query-separation-and-governed-execution.md index e9beae3..0747e7d 100644 --- a/docs/architecture/cqrs-command-query-separation-and-governed-execution.md +++ b/docs/architecture/cqrs-command-query-separation-and-governed-execution.md @@ -19,7 +19,7 @@ feed: true > **Industry anchors:** .NET teams often encounter MediatR, Wolverine, message buses, mediator pipelines, and separate read/write models while implementing command/query separation. These are orientation points for searchability, not definitions of CQRS and not evidence that a governance boundary exists. A request/handler library can support CQRS-style organization without providing authorization, policy provenance, approval, or scoped continuation authority by itself. -> **Standalone-reader note:** In this article, **Learning** means the ASI Backbone Learning repository and tutorial series. Its governed-execution model separates proposed intent, authoritative context, policy decision, optional acknowledgment or escalation, scoped authority when needed, host-owned execution, and audit residue. Those responsibilities may live in one application or be split across components. +> **Standalone-reader note:** In this article, **Learning** means the AsiBackbone Learning repository and tutorial series. Its governed-execution model separates proposed intent, authoritative context, policy decision, optional acknowledgment or escalation, scoped authority when needed, host-owned execution, and decision receipt. Those responsibilities may live in one application or be split across components. ## Executive Summary @@ -322,8 +322,8 @@ A compact teaching shape might separate the original command from the later exec > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to show the architectural boundary without reproducing the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). ```csharp public sealed record ExecuteDeployment( diff --git a/docs/architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md b/docs/architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md index 929da1d..4e179a7 100644 --- a/docs/architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md +++ b/docs/architecture/event-sourcing-audit-trails-and-governance-decision-provenance.md @@ -1,5 +1,5 @@ --- -description: Compare logs, audit trails, governance receipts, and event sourcing across diagnostics, accountability, authority provenance, and state reconstruction. +description: Compare logs, audit trails, decision receipts, and event sourcing across diagnostics, accountability, authority provenance, and state reconstruction. title: Event Sourcing, Audit Trails, and Governance Decision Provenance author: Christopher D. Cavell published: "2026-08-24" @@ -13,13 +13,13 @@ feed: true **Difficulty:** Advanced -**Prerequisites:** Recommended — [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md). [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) is useful when comparing operational telemetry with evidence-oriented records. +**Prerequisites:** Recommended — [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md). [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) is useful when comparing operational telemetry with evidence-oriented records. -> **Terminology note:** This comparison uses `operational log`, `audit trail`, `decision receipt`, `audit residue`, `domain event`, `event stream`, `projection`, `replay`, and `event sourcing` as architectural terms. Products and organizations use these words differently. The comparison is about what record owns which responsibility, not about prescribing one storage product or event framework. +> **Terminology note:** This comparison uses `operational log`, `audit trail`, `decision receipt`, `decision receipt`, `domain event`, `event stream`, `projection`, `replay`, and `event sourcing` as architectural terms. Products and organizations use these words differently. The comparison is about what record owns which responsibility, not about prescribing one storage product or event framework. > **Industry anchors:** EventStoreDB and Axon Framework are commonly associated with event-sourced architectures. Apache Kafka, Amazon SNS, and Amazon EventBridge are commonly used for event transport or event-driven integration, but using one of them does not by itself make domain events the source of application state. These names are included only for orientation and searchability. -> **Standalone-reader note:** In this article, **Learning** means the ASI Backbone Learning repository and tutorial series. `Audit residue` means structured evidence left by a governed lifecycle; it does not imply that a log line, database row, event stream, or hash is automatically immutable, tamper-evident, legally sufficient, or complete. +> **Standalone-reader note:** In this article, **Learning** means the AsiBackbone Learning repository and tutorial series. `Decision receipt` means structured evidence left by a governed lifecycle; it does not imply that a log line, database row, event stream, or hash is automatically immutable, tamper-evident, legally sufficient, or complete. ## Executive Summary @@ -27,7 +27,7 @@ History serves different purposes: - **Operational logs** explain runtime behavior. - **Audit trails** explain who changed what and when. -- **Governance receipts / audit residue** explain why authority proceeded, stopped, paused, or transferred. +- **Decision receipts / decision receipt** explain why authority proceeded, stopped, paused, or transferred. - **Event sourcing** makes domain events the source used to reconstruct application state. A system may use several of these at once. None automatically implies the others. @@ -62,7 +62,7 @@ A full event-sourced architecture is unnecessary when durable governance evidenc | --- | --- | --- | --- | --- | | Operational logging | What happened inside the running system? | No | Diagnostics, telemetry, debugging, service health, incident investigation | Complete business history, decision provenance, append-only retention, tamper evidence | | Traditional audit trail | Who changed what, when, and sometimes from what to what? | Usually no | Accountability, change history, user/resource attribution | Policy identity, reason codes, acknowledgment lineage, execution authority, replayable domain state | -| Governance decision receipt / audit residue | Why did authority proceed, stop, pause, or transfer? | No | Intent identity, context provenance, outcome, reasons, policy evidence, acknowledgment/capability/execution linkage | Complete domain history or automatic reconstruction of current domain state | +| Governance decision receipt / decision receipt | Why did authority proceed, stop, pause, or transfer? | No | Intent identity, context provenance, outcome, reasons, policy evidence, acknowledgment/capability/execution linkage | Complete domain history or automatic reconstruction of current domain state | | Event sourcing | What domain facts occurred, and what state results from replaying them? | Yes, by design | Full domain history, temporal state reconstruction, projections, event-driven integration | Decision reasons, denied attempts, policy evidence, privacy handling, tamper evidence, or safe replay of side effects | A mature architecture can combine these records deliberately. @@ -72,7 +72,7 @@ For example: ```text Operational logs + -Governance receipts +Decision receipts + Event-sourced domain stream + @@ -91,7 +91,7 @@ A governed event-sourced operation may produce two distinct historical facts: flowchart TD A["Intent"] --> B["Authoritative context + policy"] B --> C["Governance decision"] - C --> D["Decision receipt / audit residue"] + C --> D["Decision receipt / decision receipt"] C -->|"Denied / deferred / acknowledgment required"| E["No protected domain side effect"] C -->|"Allowed + valid execution authority"| F["Host-owned executor"] F --> G["Domain event appended"] @@ -293,7 +293,7 @@ That is a valid design. The name of the table matters less than the semantics pr --- -## 3. Governance Decision Receipts and Audit Residue +## 3. Governance Decision Receipts and Decision Receipt Governance evidence exists to reconstruct the governed path around consequential authority. @@ -361,12 +361,12 @@ creates evidence requirements that are not identical to domain-state requirement | --- | --- | | Operational logging | A rejection log may exist, but it can be filtered, sampled, or expired unless retention is deliberately stronger | | Traditional audit trail | Often no resource-change record exists because no resource changed; an application may add an attempt audit separately | -| Governance decision receipt / audit residue | A durable `Denied` decision can preserve intent, reasons, policy evidence, correlation, and `execution = none` | +| Governance decision receipt / decision receipt | A durable `Denied` decision can preserve intent, reasons, policy evidence, correlation, and `execution = none` | | Event-sourced domain stream | Usually no accepted domain event is appended because the protected state transition never occurred | The comparison is intentionally asymmetric. A denied attempt can be important governance evidence while correctly being absent from the domain event stream and ordinary change history. -### Audit Residue Is a Lifecycle, Not One Mandatory Storage Technology +### Decision Receipt Is a Lifecycle, Not One Mandatory Storage Technology Governance evidence may be stored in: @@ -377,7 +377,7 @@ Governance evidence may be stored in: - An event-sourced governance subsystem. - Another storage model that meets the application's reconstruction and integrity requirements. -Learning does not require event sourcing for audit residue. +Learning does not require event sourcing for decision receipt. It requires that the architecture preserve the distinctions it claims to preserve. @@ -603,7 +603,7 @@ A system may use either, both, or neither. ### Event-Store and Evidence-Store Retention May Diverge -Even when domain events and governance receipts are correlated, their retention responsibilities may differ. +Even when domain events and decision receipts are correlated, their retention responsibilities may differ. For example: @@ -903,7 +903,7 @@ Actor/workload identity PolicyVersion or policy evidence reference ``` -A denied freeze request produces a governance receipt but no `AccountFrozen` event. +A denied freeze request produces a decision receipt but no `AccountFrozen` event. This architecture uses event sourcing where it is valuable—the domain state—and governance evidence where it is valuable—the authority lifecycle. @@ -974,7 +974,7 @@ Operational logs may generate the highest raw volume because they record technic Traditional audit trails usually record selected business changes. -Governance receipts record decision lifecycle evidence and may be relatively compact but long-lived. +Decision receipts record decision lifecycle evidence and may be relatively compact but long-lived. Event sourcing records the domain transitions needed to reconstruct state, potentially indefinitely. @@ -1010,7 +1010,7 @@ Common strategies include: - Upcasters/adapters at read time. - Explicit migration of historical events under controlled rules. -The same principle applies to governance receipts: version the evidence schema deliberately if historical readers must survive application evolution. +The same principle applies to decision receipts: version the evidence schema deliberately if historical readers must survive application evolution. ### Replay @@ -1286,7 +1286,7 @@ Use the simplest record model that answers the required historical question. | --- | --- | | Debug requests, failures, latency, service health | Operational structured logging / telemetry | | Know who changed ordinary CRUD data and when | Traditional audit fields or history table | -| Reconstruct why a consequential decision allowed, denied, deferred, acknowledged, or escalated | Durable governance decision receipt / audit residue | +| Reconstruct why a consequential decision allowed, denied, deferred, acknowledged, or escalated | Durable governance decision receipt / decision receipt | | Bind later execution to earlier policy, acknowledgment, or capability evidence | Decision receipt plus explicit correlation and execution receipt | | Reconstruct aggregate/domain state from its complete history | Event sourcing | | Build multiple read models from domain history | Event sourcing + projections | @@ -1408,7 +1408,7 @@ If those questions have explicit answers, the architecture is much easier to rea Continue with: -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for the distinction between acknowledgment, decision evidence, and execution evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for the distinction between acknowledgment, decision evidence, and execution evidence. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) for policy identity, historical evidence, fingerprints, and drift. - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) for the operational-logging boundary, minimization, retention, and the limits of ordinary telemetry. - [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) when the threat model requires integrity properties beyond ordinary durable persistence. @@ -1420,13 +1420,13 @@ Continue with: ## Scope and Boundaries -This comparison does not claim that event sourcing is inherently stronger or weaker than CRUD persistence, audit tables, or governance receipts. +This comparison does not claim that event sourcing is inherently stronger or weaker than CRUD persistence, audit tables, or decision receipts. It also does not claim that: - Event sourcing guarantees tamper evidence. - Event stores are legally immutable records. -- Governance receipts establish regulatory compliance. +- Decision receipts establish regulatory compliance. - A policy fingerprint proves authorship or authorization. - Append-only storage prevents every privileged rewrite or truncation attack. - Permanent retention is appropriate for every event. diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md index 7c3de9b..e6a9a73 100644 --- a/docs/architecture/glossary.md +++ b/docs/architecture/glossary.md @@ -1,12 +1,12 @@ --- -description: Canonical quick-reference definitions for ASI Backbone Learning architecture terminology across governance, security, AI integration, and host-owned execution. +description: Canonical quick-reference definitions for AsiBackbone Learning architecture terminology across governance, security, AI integration, and host-owned execution. --- # Architecture Glossary -This glossary is the canonical vocabulary reference for ASI Backbone Learning. +This glossary is the canonical vocabulary reference for AsiBackbone Learning. -It defines how recurring architecture terms are used across tutorials, labs, samples, governance material, security material, and AI-integration material. It does not claim that the underlying architecture or security concepts originated with ASI Backbone, and it does not redefine established industry terminology when an established meaning is already sufficient. +It defines how recurring architecture terms are used across tutorials, labs, samples, governance material, security material, and AI-integration material. It does not claim that the underlying architecture or security concepts originated with AsiBackbone, and it does not redefine established industry terminology when an established meaning is already sufficient. > **Canonical here means canonical within the Learning repository.** It does not mean standardized by an external body, universally correct for every system, or permanently coupled to one implementation API. @@ -17,11 +17,28 @@ Use [Terminology and Established Architecture Concepts](terminology-and-establis Each definition is labeled with one or more scopes: - **General architecture** — an established or broadly recognizable software architecture, security, workflow, or provenance concept. -- **Learning usage** — a term whose meaning is narrowed, composed, or emphasized in a specific way by ASI Backbone Learning. +- **Learning usage** — a term whose meaning is narrowed, composed, or emphasized in a specific way by AsiBackbone Learning. - **Implementation correspondence** — a current `AsiBackbone/AsiBackbone` API or type that embodies the term. Implementation mappings can evolve without changing the architectural definition. The glossary deliberately separates architectural meaning from product-specific type names. A tutorial may use framework-neutral sample types while the `AsiBackbone` package uses different concrete names. +## Canonical 6.0 Vocabulary + +Use ordinary engineering language first. Reserve specialized wording for distinctions that affect architecture, security, or runtime behavior. + +| Canonical term | Short educational definition | Usage rule | +| --- | --- | --- | +| AsiBackbone | A governance framework for accountable software execution. | Treat `AsiBackbone` as the product name. Keep the historical expansion of `ASI` in project-history context rather than ordinary onboarding. | +| Policy decision pipeline | Rules evaluate request facts and produce a structured decision before execution. | Lead with this familiar description. Use **governance spine** only for high-level architectural positioning. | +| Decision receipt | A record of a policy decision, its outcome, and its reasons. | A receipt proves what evaluation produced; it does not prove that the host performed the operation. | +| Acknowledgment | An actor responds to a defined challenge or responsibility statement before continuation. | Use **handshake** only for the actual multi-step request/response protocol or an exact retained API name. | +| Capability grant | Short-lived, scoped authority for a bounded continuation. | Keep this term because it identifies a real delegated-authority boundary. | +| Outbox | Durable local records awaiting reliable delivery. | Use **outbox** in educational prose. Use **governance outbox** only for an exact API, schema, artifact, or specialized stream identity. | +| Host-owned execution | The host application performs or refuses the protected operation after inspecting the decision and current authority. | Keep this term because it distinguishes evaluation from the real side effect. | +| Context, constraint, decision, evaluator | Familiar inputs, rules, results, and composition services. | Prefer these established engineering terms without extra branding. | + +Introduce the vocabulary progressively: context, constraint, decision, and decision receipt first; acknowledgment next; then capability scope and expiration; outbox delivery; signing, verification, and trust policy; and finally advanced DLP, classification, and metadata controls. + ## Request, Policy, and Decision Vocabulary ### Intent @@ -114,13 +131,13 @@ A recorded response showing that a defined challenge, condition, warning, or res Acknowledgment is distinct from authentication, authorization, approval by another authority, and execution authority. -### Audit Residue +### Decision Receipt -The structured evidence left by a governed lifecycle so that the path from proposal to decision and execution can be reconstructed. +A record of a policy decision, its outcome, and its reasons. **Scope:** Learning usage; implementation correspondence. -Audit residue may include correlation identifiers, policy identity, policy version or fingerprint, decision outcomes, reason codes, acknowledgment evidence, capability events, and execution results. The term does not prescribe one storage technology and does not by itself claim durability, immutability, cryptographic signing, or tamper evidence. +A decision receipt may include correlation identifiers, policy identity, a policy version or fingerprint, the outcome, and reason codes. Later acknowledgment, capability, and execution evidence may be correlated with it, but those later events do not turn the original receipt into proof that execution occurred. The term does not prescribe one storage technology and does not by itself claim durability, immutability, cryptographic signing, or tamper evidence. ### Decision Provenance @@ -240,16 +257,16 @@ An allowlist blocks unknown or unapproved tool names from reaching handlers. Mem ## Current AsiBackbone Implementation Correspondence -The Learning glossary is architectural first. The current [`AsiBackbone/AsiBackbone` implementation glossary](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/glossary.md) provides the implementation-side vocabulary and API cross-references. +The Learning glossary is architectural first. The current [`AsiBackbone/AsiBackbone` implementation glossary](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/glossary.md) provides the implementation-side vocabulary and API cross-references. The most direct correspondences are: | Learning term | Current AsiBackbone correspondence | | --- | --- | -| Intent / request | `AsiBackboneConstraintEvaluationContext` carries proposed operation data; there is not one universal `Intent` base type. | -| Policy context | `IAsiBackboneConstraintEvaluationContext`, `AsiBackboneConstraintEvaluationContext` | -| Constraint | `IAsiBackboneConstraint`, `ConstraintEvaluationResult` | -| Policy evaluation | `IAsiBackbonePolicyEvaluator`, `DefaultAsiBackbonePolicyEvaluator` | +| Intent / request | `GovernanceEvaluationContext` carries proposed operation data; there is not one universal `Intent` base type. | +| Policy context | `IGovernanceEvaluationContext`, `GovernanceEvaluationContext` | +| Constraint | `IGovernanceConstraint`, `ConstraintEvaluationResult` | +| Policy evaluation | `IGovernancePolicyEvaluator`, `DefaultGovernancePolicyEvaluator` | | Decision outcome | `GovernanceDecision`, `GovernanceDecisionOutcome` | | Allow | `GovernanceDecisionOutcome.Allowed` | | Deny | `GovernanceDecisionOutcome.Denied` | @@ -257,7 +274,7 @@ The most direct correspondences are: | Require acknowledgment | `GovernanceDecisionOutcome.AcknowledgmentRequired` | | Escalate | `GovernanceDecisionOutcome.EscalationRecommended` | | Acknowledgment | `LiabilityHandshakeAcknowledgment`; ASP.NET Core challenge support also exposes acknowledgment challenge types and services. | -| Audit residue | `AuditResidue`; durable ledger support includes `AuditLedgerRecord` and `IAsiBackboneAuditLedgerStore`. | +| Decision receipt | `DecisionReceipt`; durable ledger support includes `AuditLedgerRecord` and `IGovernanceAuditLedgerStore`. | | Policy version | `GovernanceDecision.PolicyVersion` | | Policy fingerprint | `GovernanceDecision.PolicyHash` | | Scoped capability / capability token | `CapabilityTokenGrant`, `CapabilityGrantValidator` | @@ -278,7 +295,7 @@ Not every Learning term has, or should have, a one-to-one concrete type. Terms s | Policy version ≠ policy fingerprint | A version is a label; a fingerprint is content-derived identity. | | Tool proposal ≠ tool invocation | Model output remains proposal data until the host validates and authorizes execution. | | Tool allowlist ≠ permission to invoke | Eligibility is only one gate in a governed execution path. | -| Audit residue ≠ tamper-proof evidence | Storage, durability, signing, integrity, and retention are separate implementation concerns. | +| Decision receipt ≠ tamper-proof evidence | Storage, durability, signing, integrity, and retention are separate implementation concerns. | | Decision outcome ≠ operation result | Governance may block execution entirely, while an allowed operation can still fail when executed. | ## Related Learning Material @@ -287,7 +304,7 @@ Foundational tutorials introduce the terms in context: 1. [Decision Before Execution](../tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) diff --git a/docs/architecture/governance-spine-and-capability-validation-diagrams.md b/docs/architecture/governance-spine-and-capability-validation-diagrams.md index 32670e5..b2d4056 100644 --- a/docs/architecture/governance-spine-and-capability-validation-diagrams.md +++ b/docs/architecture/governance-spine-and-capability-validation-diagrams.md @@ -87,7 +87,7 @@ Use the diagrams as orientation, then follow the corresponding lessons for reaso - [Getting Started](../getting-started/index.md) - [Decision Before Execution](../tutorials/decision-before-execution.md) - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) @@ -96,9 +96,9 @@ Use the diagrams as orientation, then follow the corresponding lessons for reaso The Learning diagrams are intentionally framework-neutral. The current AsiBackbone implementation repository contains fuller implementation-facing references: -- [Core Governance Flow Diagrams](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/core-governance-flow-diagrams.md) -- [Core Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +- [Core Governance Flow Diagrams](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/core-governance-flow-diagrams.md) +- [Core Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) Those implementation references may use concrete package types and validation profiles. This Learning page keeps the architectural lesson independent of any one API surface. diff --git a/docs/architecture/governance-tool-selection-and-composition.md b/docs/architecture/governance-tool-selection-and-composition.md index 5dd2757..fc9ecf2 100644 --- a/docs/architecture/governance-tool-selection-and-composition.md +++ b/docs/architecture/governance-tool-selection-and-composition.md @@ -29,7 +29,7 @@ It is: | Cloud/resource governance | Resource configuration and platform compliance | Resource inventory, policy assignment, remediation, platform controls | Application-specific acknowledgment or execution provenance | | Policy/rules engines | Structured decision evaluation | Reusable policy logic, language-neutral decisions, policy-as-code | Owning side effects, human workflow, durable runtime accountability by default | | Agent/tool governance | What automated agents may propose, delegate, or invoke | Tool registration, agent identity, delegation rules, sandboxing, agent operations | Universal application authorization or business-process evidence | -| Governed execution | Consequential application intent before side effects | Explicit decisions, acknowledgment, scoped continuation authority, audit residue, host-owned execution | Cloud configuration, network policy, model hosting, or generic rules evaluation by itself | +| Governed execution | Consequential application intent before side effects | Explicit decisions, acknowledgment, scoped continuation authority, decision receipt, host-owned execution | Cloud configuration, network policy, model hosting, or generic rules evaluation by itself | These families frequently compose. diff --git a/docs/architecture/index.md b/docs/architecture/index.md index c094e0d..20f31d0 100644 --- a/docs/architecture/index.md +++ b/docs/architecture/index.md @@ -16,7 +16,7 @@ The goal is not to prescribe one universal design. The goal is to make important | --- | --- | | Learning terminology | [Architecture Glossary](glossary.md) | | How Learning terms relate to established concepts | [Terminology and Established Architecture Concepts](terminology-and-established-concepts.md) | -| The overall governance-spine concept | [Accountable Systems Infrastructure and Governed Execution](accountable-systems-infrastructure-and-governed-execution.md) | +| The overall governance-spine concept | [AsiBackbone and Governed Execution](asibackbone-and-governed-execution.md) | | Why proposal and side effect should be separated | [Intent to Execution: An Accountability Pattern](intent-to-execution-accountability-pattern.md) | | How active constraints shape decisions | [Constraint-Conditioned Decision Model](constraint-conditioned-decision-model.md) | | How adjacent governance mechanisms compose | [Governance Tool Selection and Composition](governance-tool-selection-and-composition.md) | @@ -42,7 +42,7 @@ Scoped Authority ↓ Host-Owned Execution ↓ -Audit Residue +Decision Receipt ``` This makes it easier to answer six questions: @@ -62,7 +62,7 @@ Substantive pages may use a visible `Pattern classification` when architectural | Status | Meaning | | --- | --- | -| **Canonical Pattern** | Aligns with the current architecture of one or more ASI Backbone organization repositories. | +| **Canonical Pattern** | Aligns with the current architecture of one or more AsiBackbone organization repositories. | | **Alternative Pattern** | Presents a viable different approach or intentionally departs from the canonical organization pattern. | | **Experimental** | Explores architecture that is not presented as an established organization pattern or production-ready design. | | **General learning material** | Teaches useful architecture without making a stronger canonical, alternative, or experimental claim. | @@ -73,7 +73,7 @@ These are descriptive labels, not rankings. Canonical does not mean universally | Concept | What it helps you reason about | | --- | --- | -| [Accountable Systems Infrastructure and Governed Execution](accountable-systems-infrastructure-and-governed-execution.md) | The stack-neutral meaning of the governance-spine idea | +| [AsiBackbone and Governed Execution](asibackbone-and-governed-execution.md) | The stack-neutral meaning of the governance-spine idea | | [Intent to Execution: An Accountability Pattern](intent-to-execution-accountability-pattern.md) | The accountability gap between proposal and side effect | | [Constraint-Conditioned Decision Model](constraint-conditioned-decision-model.md) | How active constraints narrow an intent toward an outcome | | [Governance Tool Selection and Composition](governance-tool-selection-and-composition.md) | How adjacent governance mechanisms protect different boundaries without becoming substitutes | @@ -86,7 +86,7 @@ If these boundaries are new, use the five tutorials in order: 1. [Decision Before Execution](../tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) @@ -118,7 +118,7 @@ For general layering guidance, see [Growing Beyond a Simple Application Structur Learning uses the organization's implementation repositories as architectural specimens: -- [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) — a .NET governance and policy-control framework demonstrating structured decisions, acknowledgment workflows, audit residue, scoped capabilities, and host-owned execution boundaries. +- [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) — a .NET governance and policy-control framework demonstrating structured decisions, acknowledgment workflows, decision receipt, scoped capabilities, and host-owned execution boundaries. - [AsiBackbone/NetCoreApplicationTemplate](https://github.com/AsiBackbone/NetCoreApplicationTemplate) — an ASP.NET Core reference architecture demonstrating middleware organization, secure defaults, logging, error handling, rate limiting, authentication-ready design, and production-oriented application structure. For the current learning path, continue with the [Foundational Tutorials](../tutorials/index.md). diff --git a/docs/architecture/intent-to-execution-accountability-pattern.md b/docs/architecture/intent-to-execution-accountability-pattern.md index 58b123c..8e8f3bc 100644 --- a/docs/architecture/intent-to-execution-accountability-pattern.md +++ b/docs/architecture/intent-to-execution-accountability-pattern.md @@ -10,7 +10,7 @@ description: Follow a stack-neutral accountability pattern from proposed intent **Difficulty:** Intermediate -**Prerequisites:** [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), and [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +**Prerequisites:** [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), and [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) Most systems can answer two questions well: @@ -36,7 +36,7 @@ Explicit decision | Acknowledgment when required | -Audit residue +Decision receipt | Scoped continuation authority when required | @@ -95,7 +95,7 @@ This is difficult when execution is delayed, retried, delegated, or performed by ### Trustworthiness of the record -Structured audit residue is not automatically tamper-evident. +Structured decision receipt is not automatically tamper-evident. Signing, key custody, append-only persistence, integrity chaining, independent storage, and external anchoring are separate design choices. @@ -139,9 +139,9 @@ Its own documentation remains authoritative for public types, supported outcomes ## Continue learning -- [Accountable Systems Infrastructure and Governed Execution](accountable-systems-infrastructure-and-governed-execution.md) +- [AsiBackbone and Governed Execution](asibackbone-and-governed-execution.md) - [Decision Before Execution](../tutorials/decision-before-execution.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) - [Event Sourcing, Audit Trails, and Governance Decision Provenance](event-sourcing-audit-trails-and-governance-decision-provenance.md) diff --git a/docs/architecture/policy-engines-rules-engines-and-distributed-policy-enforcement.md b/docs/architecture/policy-engines-rules-engines-and-distributed-policy-enforcement.md index 8949552..e4138f8 100644 --- a/docs/architecture/policy-engines-rules-engines-and-distributed-policy-enforcement.md +++ b/docs/architecture/policy-engines-rules-engines-and-distributed-policy-enforcement.md @@ -19,7 +19,7 @@ feed: true > **Industry anchors:** Technologies commonly encountered in these spaces include Drools for rule evaluation and OPA/Rego, Cedar, or XACML-based engines for policy evaluation. They are examples for orientation and searchability, not definitions of the categories. -> **Standalone-reader note:** In this article, **Learning** means the ASI Backbone Learning repository and tutorial series. Its recurring governance pipeline is a responsibility model for `Intent -> Authoritative Context -> Policy / Constraints -> Decision -> Acknowledgment or Escalation when required -> Scoped Authority when needed -> Host-Owned Execution -> Audit Residue`. Those responsibilities may be implemented in one application or distributed across several components. +> **Standalone-reader note:** In this article, **Learning** means the AsiBackbone Learning repository and tutorial series. Its recurring governance pipeline is a responsibility model for `Intent -> Authoritative Context -> Policy / Constraints -> Decision -> Acknowledgment or Escalation when required -> Scoped Authority when needed -> Host-Owned Execution -> Decision Receipt`. Those responsibilities may be implemented in one application or distributed across several components. ## Executive Summary @@ -43,7 +43,7 @@ These are composable responsibilities, not maturity levels. A remote PDP is not | Approach | Primary responsibility | Natural strength | Not automatically provided | | --- | --- | --- | --- | | Rules engine | Evaluate a body of domain rules against facts | Centralized, declarative business logic, decision tables, chaining, rule reuse | A distributed policy lifecycle, authoritative context, execution authority, or enforcement topology | -| Policy engine / PDP | Evaluate externalized authorization or governance policy | Consistent policy evaluation, policy-as-code, versioned policy, reusable decisions across heterogeneous callers | Trustworthy input construction, acknowledgment, escalation workflow, capability issuance, execution, or complete audit residue | +| Policy engine / PDP | Evaluate externalized authorization or governance policy | Consistent policy evaluation, policy-as-code, versioned policy, reusable decisions across heterogeneous callers | Trustworthy input construction, acknowledgment, escalation workflow, capability issuance, execution, or complete decision receipt | | Distributed policy enforcement | Apply policy decisions at one or more PEPs | Enforcement close to the protected resource or side effect | A single universal consistency, freshness, partition, or degraded-mode strategy | | Learning governance pipeline | Coordinate consequential-action lifecycle boundaries | Explicit context, outcomes, acknowledgment/escalation, scoped authority, host-owned execution, provenance | A requirement that every application use a separate framework or remote policy service | @@ -74,7 +74,7 @@ Intent -> acknowledgment / escalation when required -> scoped continuation authority when needed -> PEP / host-owned execution - -> audit residue + -> decision receipt ``` ### One Policy Decision, Many Possible Placements @@ -829,7 +829,7 @@ Scoped Authority when needed ↓ Host-Owned Execution ↓ -Audit Residue +Decision Receipt ``` A policy engine can occupy the evaluation step: @@ -971,7 +971,7 @@ A policy engine returning `Allow` should not obscure which host: This is the same reason the Learning material preserves **host-owned execution**. -### Audit Residue +### Decision Receipt A policy engine may emit decision logs. @@ -1646,7 +1646,7 @@ Which PEP enforced the final result? ## 18. Relationship to the Learning Governance Pipeline -As defined near the beginning of this article, the ASI Backbone Learning governance pipeline should be read as a responsibility model, not as a requirement that every responsibility be a different product or service. +As defined near the beginning of this article, the AsiBackbone Learning governance pipeline should be read as a responsibility model, not as a requirement that every responsibility be a different product or service. One implementation may look like: diff --git a/docs/architecture/terminology-and-established-concepts.md b/docs/architecture/terminology-and-established-concepts.md index 27ee029..d8195f9 100644 --- a/docs/architecture/terminology-and-established-concepts.md +++ b/docs/architecture/terminology-and-established-concepts.md @@ -1,27 +1,27 @@ --- -description: Map ASI Backbone Learning terminology to established software architecture, authorization, security, workflow, provenance, and AI-governance concepts. +description: Map AsiBackbone Learning terminology to established software architecture, authorization, security, workflow, provenance, and AI-governance concepts. --- # Terminology and Established Architecture Concepts -ASI Backbone Learning uses a consistent vocabulary to make recurring architectural boundaries easier to teach, test, and compare. +AsiBackbone Learning uses a consistent vocabulary to make recurring architectural boundaries easier to teach, test, and compare. For concise canonical definitions, start with the [Architecture Glossary](glossary.md). This page focuses on terminology lineage, established concept anchors, and the distinctions between Learning composition terms and broader industry vocabulary. -That vocabulary is **not** a claim that the underlying software architecture, security, authorization, workflow, provenance, or AI-governance ideas originated with ASI Backbone. +That vocabulary is **not** a claim that the underlying software architecture, security, authorization, workflow, provenance, or AI-governance ideas originated with AsiBackbone. Many of the related concepts predate this repository by years or decades. -Some labels, including `Governed Execution`, `Audit Residue`, `Host-Owned Execution`, and `Governed AI Tool Gateway`, are repository-local teaching or composition terms rather than external standards terminology. They are signposts for boundaries that the tutorials want to keep visible. +Some labels, including `Governed Execution`, `Host-Owned Execution`, and `Governed AI Tool Gateway`, are repository-local teaching or composition terms rather than external standards terminology. They are signposts for boundaries that the tutorials want to keep visible. `Decision receipt` is the canonical name for the concrete record produced by policy evaluation. -> **ASI Backbone Learning often gives a consistent name to a boundary or composition of established architectural ideas. The terminology is intended to make those boundaries teachable and reusable, not to erase their technical lineage.** +> **AsiBackbone Learning often gives a consistent name to a boundary or composition of established architectural ideas. The terminology is intended to make those boundaries teachable and reusable, not to erase their technical lineage.** The intended relationship is: ```text Established concept ↓ -ASI Backbone Learning terminology +AsiBackbone Learning terminology ↓ Specific teaching boundary or composition ``` @@ -43,12 +43,12 @@ Renamed as something new | **Policy Context** | ABAC subject/object/action/environment attributes, authorization context, request/resource context | Decision-relevant facts are assembled explicitly and preferably from authoritative sources rather than discovered implicitly throughout execution. | | **Explicit Decision Outcomes** | Result types, workflow states, policy decisions, state-machine transitions | The decision communicates what should happen next instead of compressing all non-success states into `false` or an authorization failure. | | **Acknowledgment Boundary** | Consent flows, attestation, approval workflows, human-in-the-loop controls | Acknowledgment records that a condition was presented and accepted. It remains distinct from authentication, authorization, approval by another authority, and execution authority. | -| **Audit Residue** | Audit trails, decision logs, event records, provenance | The term describes structured evidence left by the governed lifecycle, including correlation, policy identity, reasons, acknowledgment, authority, and execution evidence. It does not prescribe one logging or storage technology. | +| **Decision Receipt** | Audit trails, decision logs, event records, provenance | The receipt records a decision, its outcome, and its reasons. Related acknowledgment, authority, and execution events can be correlated without implying that the decision record itself proves execution. | | **Capability-Scoped Authority** | Capability-based security, least privilege, scoped credentials, short-lived access tokens | Authority is narrowly bound to the actor, operation, resource, audience, state, lifetime, and when needed use count or acknowledgment. Merely using a short-lived token does not by itself create the full boundary. | | **Host-Owned Execution** | Reference monitor, complete mediation, trusted execution boundary, application service boundary | A policy evaluator or model may recommend or permit an action, but the trusted host retains control of the component that performs the real side effect. | | **Governed AI Tool Gateway** | Tool mediation, agent/tool gateways, reference-monitor patterns, human oversight, application authorization | Model output is treated as a proposal, not authority. The host owns the tool registry, reconstructs authoritative context, evaluates policy, validates execution authority, and invokes the tool. | -| **Governance Spine** | Policy pipeline, orchestration pipeline, control plane, workflow state machine | Learning uses the term for the end-to-end sequence that preserves the boundaries among intent, context, decision, acknowledgment, scoped authority, execution, and evidence. | -| **Canonical Pattern** | Reference architecture, preferred implementation, repository convention | `Canonical` means aligned with the current ASI Backbone reference implementations and teaching path. It does **not** mean an industry standard, universally correct architecture, or requirement for adopters. | +| **Governance Spine** | Policy pipeline, orchestration pipeline, control plane, workflow state machine | Use this as high-level architectural positioning for the end-to-end sequence. Use familiar terms such as policy decision pipeline when explaining low-level behavior. | +| **Canonical Pattern** | Reference architecture, preferred implementation, repository convention | `Canonical` means aligned with the current AsiBackbone reference implementations and teaching path. It does **not** mean an industry standard, universally correct architecture, or requirement for adopters. | The established concepts in the middle column are conceptual anchors, not declarations of exact equivalence. @@ -184,15 +184,15 @@ OAuth access tokens provide a familiar example of credentials with scope and lif The key lesson is to validate the authority **where the side effect is about to occur**, not merely when the artifact is created. -## Audit Residue, Logging, and Provenance +## Decision Receipts, Logging, and Provenance -`Audit residue` is a Learning term for evidence that remains from the governed lifecycle. +A decision receipt records a policy decision, its outcome, and its reasons. It may be stored in logs, events, a database, append-only storage, or another audit system. -The term is intentionally broader than a single log message. +It is more structured than a single log message, but it does not by itself prove that the host executed the operation. -Useful residue may connect: +A useful receipt may identify: ```text proposal @@ -200,12 +200,11 @@ policy context identity policy version or hash decision outcome reason codes -acknowledgment -capability issuance and validation -execution result correlation identifiers ``` +Acknowledgment, capability, and execution events may be stored separately and correlated with the decision receipt as the governed lifecycle continues. + A structured log can carry some or all of this information. But: @@ -216,7 +215,7 @@ logging technology ≠ decision provenance model The architecture still has to decide which events exist, how they correlate, which identifiers are stable, and which records require durable or integrity-protected storage. -W3C PROV is one established vocabulary for representing provenance relationships. Learning does not attempt to replace it; `audit residue` is a smaller teaching label for the evidence left by the repository's governed-execution lifecycle. +W3C PROV is one established vocabulary for representing provenance relationships. Learning does not attempt to replace it; `decision receipt` is a smaller label for the evaluation record within the repository's governed-execution lifecycle. ## Policy Decision Versus Execution Authority @@ -280,7 +279,7 @@ NIST's AI Risk Management Framework provides a broader governance and human-over ## What `Canonical` Means Here -Within ASI Backbone Learning, **Canonical Pattern** means: +Within AsiBackbone Learning, **Canonical Pattern** means: > The pattern currently aligned with the organization's reference implementations and foundational teaching sequence. @@ -319,7 +318,7 @@ Foundational tutorials: 1. [Decision Before Execution](../tutorials/decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) 5. [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) @@ -346,7 +345,7 @@ These references are intentionally selective. They provide established terminolo The useful question is not: -> Which familiar idea has ASI Backbone renamed? +> Which familiar idea has AsiBackbone renamed? It is: diff --git a/docs/architecture/toc.yml b/docs/architecture/toc.yml index 227ec69..8828d20 100644 --- a/docs/architecture/toc.yml +++ b/docs/architecture/toc.yml @@ -7,8 +7,8 @@ - name: Terminology and Established Architecture Concepts href: terminology-and-established-concepts.md -- name: Accountable Systems Infrastructure and Governed Execution - href: accountable-systems-infrastructure-and-governed-execution.md +- name: AsiBackbone and Governed Execution + href: asibackbone-and-governed-execution.md - name: Intent to Execution Accountability Pattern href: intent-to-execution-accountability-pattern.md diff --git a/docs/architecture/when-a-simple-application-service-is-enough.md b/docs/architecture/when-a-simple-application-service-is-enough.md index fbadf65..72ef600 100644 --- a/docs/architecture/when-a-simple-application-service-is-enough.md +++ b/docs/architecture/when-a-simple-application-service-is-enough.md @@ -15,7 +15,7 @@ feed: true **Prerequisites:** [When ASP.NET Core Authorization Is Enough](when-aspnet-core-authorization-is-enough.md) and [Decision Before Execution](../tutorials/decision-before-execution.md). Familiarity with [Data Access Boundaries and Transaction Reasoning](../aspnetcore/data-access-boundaries-and-transaction-reasoning.md) is helpful. -> **Terminology note:** Learning uses terms such as governed execution, host-owned execution, policy context, scoped authority, and audit residue as teaching labels for architectural boundaries. See [Terminology and Established Architecture Concepts](terminology-and-established-concepts.md) for their relationship to established authorization, application-service, workflow, capability, provenance, and mediation concepts. +> **Terminology note:** Learning uses terms such as governed execution, host-owned execution, policy context, scoped authority, and decision receipt as teaching labels for architectural boundaries. See [Terminology and Established Architecture Concepts](terminology-and-established-concepts.md) for their relationship to established authorization, application-service, workflow, capability, provenance, and mediation concepts. A broader governed-execution pipeline is not automatically the best architecture for every mutation. @@ -1087,7 +1087,7 @@ Use these comparisons in sequence when useful: 2. **When a Simple Application Service Is Enough** — asks whether the authorized use case can remain an immediate application workflow. 3. [Decision Before Execution](../tutorials/decision-before-execution.md) — introduces an explicit decision/execution boundary when the operation needs one. 4. [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — expands decisions into reviewable facts and outcomes. -5. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — adds interrupted lifecycle and evidence. +5. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — adds interrupted lifecycle and evidence. 6. [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — adds narrow post-decision authority. 7. [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — controls reuse when authority becomes a reusable artifact. diff --git a/docs/architecture/workflow-engines-human-approval-and-governed-execution.md b/docs/architecture/workflow-engines-human-approval-and-governed-execution.md index 53ed171..78dfd8e 100644 --- a/docs/architecture/workflow-engines-human-approval-and-governed-execution.md +++ b/docs/architecture/workflow-engines-human-approval-and-governed-execution.md @@ -13,7 +13,7 @@ feed: true **Difficulty:** Intermediate -**Prerequisites:** Recommended — [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) is useful follow-on reading for a deeper review lifecycle. +**Prerequisites:** Recommended — [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) is useful follow-on reading for a deeper review lifecycle. > **Terminology note:** This comparison uses `workflow engine`, `human approval`, `governance decision`, `scoped authority`, and `host-owned execution` as architectural terms. Products differ widely. A workflow product may include authorization, rules, approvals, policy evaluation, audit history, or task assignment. The comparison is about responsibilities and trust boundaries rather than product categories or vendor features. @@ -976,7 +976,7 @@ A workflow engine can persist an acknowledgment task without making acknowledgme Show warning -> wait for actor acknowledgment -> continue ``` -The record should remain bound to the actor, exact condition, relevant intent, and applicable decision context. Afterward, the host may still need current policy evaluation or narrow continuation authority. See [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md). +The record should remain bound to the actor, exact condition, relevant intent, and applicable decision context. Afterward, the host may still need current policy evaluation or narrow continuation authority. See [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md). --- @@ -1179,7 +1179,7 @@ Do not add a layer merely because the diagram looks more sophisticated with it. ## Related Learning Material - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) - [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) diff --git a/docs/articles/2026/a-passing-agent-diff-is-not-project-authority.md b/docs/articles/2026/a-passing-agent-diff-is-not-project-authority.md index 6a15fb5..ff542b4 100644 --- a/docs/articles/2026/a-passing-agent-diff-is-not-project-authority.md +++ b/docs/articles/2026/a-passing-agent-diff-is-not-project-authority.md @@ -30,7 +30,7 @@ That distinction matters because a fluent patch can make several different claim Each claim needs different evidence, and the last two may require decisions or observations that do not exist in a pull-request environment. -This article examines one bounded episode in the [Learning repository](https://github.com/AsiBackbone/Learning), the education and documentation repository for **Accountable Systems Infrastructure (ASI) Backbone**. It describes one maintainer, one repository, and two pull requests in September 2026. It does not claim that every AsiBackbone repository or every AI-assisted project follows the same process. +This article examines one bounded episode in the [Learning repository](https://github.com/AsiBackbone/Learning), the education and documentation repository for **AsiBackbone**. It describes one maintainer, one repository, and two pull requests in September 2026. It does not claim that every AsiBackbone repository or every AI-assisted project follows the same process. The episode has a recursive quality. AsiBackbone teaches that a proposed operation should not become an executed operation merely because the proposal is well formed. The development process benefited from the same separation of concerns. That is an explanatory analogy, not a claim that GitHub workflows formally implement or validate the AsiBackbone architecture. diff --git a/docs/articles/2026/authorization-check-runs-too-late.md b/docs/articles/2026/authorization-check-runs-too-late.md index 542f2c1..1a7167d 100644 --- a/docs/articles/2026/authorization-check-runs-too-late.md +++ b/docs/articles/2026/authorization-check-runs-too-late.md @@ -528,7 +528,7 @@ The separation has clear relatives in established software and security architec - command validation and application-service boundaries; - workflow state machines and explicit result types. -ASI Backbone Learning uses terms such as **Decision Before Execution**, **Governed Execution**, and **Host-Owned Execution** to keep the composed boundary visible while teaching it. Those labels are not claims that the underlying ideas originated in this repository. +AsiBackbone Learning uses terms such as **Decision Before Execution**, **Governed Execution**, and **Host-Owned Execution** to keep the composed boundary visible while teaching it. Those labels are not claims that the underlying ideas originated in this repository. The reusable lesson is independent of the vocabulary: diff --git a/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md b/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md index 82cc91b..0007443 100644 --- a/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md +++ b/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md @@ -13,7 +13,7 @@ feed: true **Difficulty:** Intermediate -**Prerequisites:** Basic familiarity with .NET builds, NuGet packages, and CI terminology. No ASI Backbone knowledge is required. +**Prerequisites:** Basic familiarity with .NET builds, NuGet packages, and CI terminology. No AsiBackbone knowledge is required. A repository looks healthy: build passing, tests passing, dependency updates automated, release published. @@ -229,6 +229,6 @@ When the unresolved question is what a hash, signature, or attestation actually If publication authority depends on CI/CD credentials or federated identities, [Secret Handling Across Trust Boundaries](../../security/secret-handling-across-trust-boundaries.md) addresses scope, exposure, rotation, revocation, and compromise response at that boundary. -To compare those ideas with a working package pipeline, inspect the [AsiBackbone package repository workflows](https://github.com/AsiBackbone/AsiBackbone/tree/main/.github/workflows). They are an optional specimen for package validation, artifact handoff, SBOM, provenance, and publication-boundary patterns; they are not a specimen for NuGet author signing. +To compare those ideas with a working package pipeline, inspect the [AsiBackbone package repository workflows](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/.github/workflows). They are an optional specimen for package validation, artifact handoff, SBOM, provenance, and publication-boundary patterns; they are not a specimen for NuGet author signing. The point is not to copy one repository's release stack. The point is to explain, narrowly and verifiably, how reviewed source became the artifact a consumer received. diff --git a/docs/articles/index.md b/docs/articles/index.md index b67f41c..ba9dfce 100644 --- a/docs/articles/index.md +++ b/docs/articles/index.md @@ -1,10 +1,10 @@ --- -description: Browse standalone ASI Backbone Learning technical articles published at stable year-and-slug URLs for direct external discovery and citation. +description: Browse standalone AsiBackbone Learning technical articles published at stable year-and-slug URLs for direct external discovery and citation. --- # Articles -ASI Backbone Learning articles are standalone technical arguments written for direct discovery, sharing, and citation. A reader can arrive from a search engine, newsletter, social link, conference resource list, or external reference without completing the Learning curriculum first. +AsiBackbone Learning articles are standalone technical arguments written for direct discovery, sharing, and citation. A reader can arrive from a search engine, newsletter, social link, conference resource list, or external reference without completing the Learning curriculum first. ## Start by Topic diff --git a/docs/aspnetcore/centralized-error-handling-and-problem-details.md b/docs/aspnetcore/centralized-error-handling-and-problem-details.md index 34a34c4..8fd5a63 100644 --- a/docs/aspnetcore/centralized-error-handling-and-problem-details.md +++ b/docs/aspnetcore/centralized-error-handling-and-problem-details.md @@ -929,7 +929,7 @@ trace ID That does not make it the durable record of why a consequential governance decision occurred. -A governance receipt may need different evidence such as: +A decision receipt may need different evidence such as: ```text Decision ID @@ -944,7 +944,7 @@ Correlation ID The relationship can be: ```text -Governance receipt +Decision receipt ↓ Purpose-built evidence store @@ -957,9 +957,9 @@ Shared correlation / decision reference Links the two when appropriate ``` -Do not copy the entire governance receipt into the public response merely because both are structured JSON. +Do not copy the entire decision receipt into the public response merely because both are structured JSON. -See [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for the evidence boundary. +See [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for the evidence boundary. --- @@ -1177,7 +1177,7 @@ Before moving on, you should be able to answer: 14. Why can an already-started response prevent normal Problem Details replacement? 15. What should happen to an exception that has no deliberate mapping? 16. Why does cancellation need its own host policy rather than automatic `500` mapping? -17. Why is a Problem Details response not a governance audit receipt? +17. Why is a Problem Details response not a decision receipt? 18. Which integration tests protect the public disclosure and mapping contract? 19. When would framework defaults or a smaller result-mapping function be enough? @@ -1192,7 +1192,7 @@ If these answers are unclear, the application may have error responses, but it d - [Secure-by-Default ASP.NET Core Configuration](secure-by-default-configuration.md) - [Structured Logging Without Sensitive-Data Sprawl](structured-logging-without-sensitive-data-sprawl.md) - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) - [Centralized Error Handling and Problem Details sample](https://github.com/AsiBackbone/Learning/blob/main/samples/centralized-error-handling-and-problem-details/README.md) - [NetCoreApplicationTemplate](https://github.com/AsiBackbone/NetCoreApplicationTemplate) diff --git a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md b/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md index 515d376..4861b09 100644 --- a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md +++ b/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md @@ -8,7 +8,7 @@ description: Learn how to place EF Core behind clear boundaries, choose transact **Difficulty:** Intermediate -**Prerequisites:** Basic familiarity with ASP.NET Core dependency injection and EF Core. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) provide useful governance context. +**Prerequisites:** Basic familiarity with ASP.NET Core dependency injection and EF Core. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) provide useful governance context. **Learning objective:** Decide where EF Core belongs in an application, distinguish persistence abstractions from unnecessary wrappers, choose transaction boundaries deliberately, use interceptors only where their lifecycle fits the concern, test relational behavior with an appropriate provider, and preserve the boundary between a local database transaction and an external side effect. @@ -18,7 +18,7 @@ description: Learn how to place EF Core behind clear boundaries, choose transact > > **Pattern:** Keep persistence at an application/infrastructure boundary. Use `DbContext` directly when it already expresses the required unit of work; introduce a repository or store interface when it creates a meaningful domain, testing, provider, or ownership boundary. Use the smallest transaction that makes related **local** state atomic, and model remote effects with separate idempotency, messaging, or recovery semantics. > -> **Use when:** An ASP.NET Core application must persist governance decisions, audit residue, capability-use state, workflow state, or other durable data and the correctness of those writes matters to later execution. +> **Use when:** An ASP.NET Core application must persist governance decisions, decision receipt, capability-use state, workflow state, or other durable data and the correctness of those writes matters to later execution. > > **Prefer something simpler when:** The application has trivial persistence, one request-scoped `DbContext`, one `SaveChangesAsync` call, and no requirement to abstract the store or coordinate several local writes. Do not add repositories, explicit transactions, or interceptors merely to match a pattern catalog. > @@ -49,7 +49,7 @@ Capability ↓ Execution ↓ -Audit residue +Decision receipt ``` But process memory has obvious limits. @@ -315,7 +315,7 @@ Prefer methods that expose the operation the caller needs when the repository is ```csharp Task FindForDisableAsync(...) ValueTask TryConsumeAsync(...) -Task AppendAsync(AuditResidue residue, ...) +Task AppendAsync(DecisionReceipt receipt, ...) ``` Do not create one method per `DbSet` operation simply to avoid naming `DbContext`. @@ -350,10 +350,10 @@ Example: ```csharp CapabilityUseRecord use = ...; -ExecutionResidueRecord residue = ...; +ExecutionReceiptRecord receipt = ...; _dbContext.CapabilityUses.Add(use); -_dbContext.ExecutionResidues.Add(residue); +_dbContext.ExecutionReceipts.Add(receipt); await _dbContext.SaveChangesAsync( cancellationToken); @@ -399,8 +399,8 @@ try dbContext.Operations.Add(operation); await dbContext.SaveChangesAsync(cancellationToken); - dbContext.ExecutionResidues.Add( - CreateResidue(operation.Id)); + dbContext.ExecutionReceipts.Add( + CreateReceipt(operation.Id)); await dbContext.SaveChangesAsync(cancellationToken); @@ -441,7 +441,7 @@ For one-time capability consumption: For local audit pairing: -> **If capability consumption is committed, the execution-start residue must also be committed.** +> **If capability consumption is committed, the execution-start receipt must also be committed.** For an account update plus local outbox message: @@ -525,7 +525,7 @@ Suppose the same application database owns both: ```text Capability-use state -Execution-start residue +Execution-start receipt ``` The host may require: @@ -533,7 +533,7 @@ The host may require: ```text Consume capability + -Write execution-start residue +Write execution-start receipt ↓ Commit together ``` @@ -547,7 +547,7 @@ Begin transaction ↓ Claim permitted capability use ↓ -Write execution-start residue +Write execution-start receipt ↓ Commit ``` @@ -575,7 +575,7 @@ Begin database transaction ↓ Consume capability ↓ -Write execution-start residue +Write execution-start receipt ↓ Call external service ↓ @@ -613,7 +613,7 @@ Consider: ```text Capability marked consumed ↓ -Execution-start residue written +Execution-start receipt written ↓ Database transaction commits ↓ @@ -814,8 +814,8 @@ Trying to infer them from modified entities can turn the interceptor into hidden Prefer explicit code when the operation is meaningful because of the workflow: ```csharp -await auditResidueStore.AppendAsync( - AuditResidue.ExecutionStarted(...), +await decisionReceiptStore.AppendAsync( + DecisionReceipt.ExecutionStarted(...), cancellationToken); ``` @@ -839,7 +839,7 @@ Prefer explicit application behavior --- -## Generic Database Auditing Is Not Governance Audit Residue +## Generic Database Auditing Is Not Decision Receipt A database audit record may say: @@ -853,7 +853,7 @@ New: true That can be useful. -Governance audit residue may say: +Governance decision receipt may say: ```text DecisionId: dec-42 @@ -870,7 +870,7 @@ Database auditing asks: > What persisted data changed? -Governance residue asks: +Decision receipt asks: > What happened in the governed decision and execution lifecycle? @@ -1165,14 +1165,14 @@ Begin local unit of work ↓ Claim capability use ↓ -Write execution-start residue +Write execution-start receipt ↓ Force second write to fail ↓ Rollback ↓ Capability use absent -Execution residue absent +Execution receipt absent ``` Another useful test: @@ -1235,7 +1235,7 @@ Governance decision Execution-boundary service ↓ ICapabilityUseStore -IAuditResidueStore +IDecisionReceiptStore ↓ EF Core implementations ↓ @@ -1256,7 +1256,7 @@ That is the boundary this tutorial is trying to preserve. --- -## Example: Local Transaction Around Capability Consumption and Residue +## Example: Local Transaction Around Capability Consumption and Receipt A coordinator can make the intended local transaction explicit: @@ -1265,11 +1265,11 @@ public sealed class ExecutionPersistenceCoordinator { private readonly ApplicationDbContext _dbContext; private readonly EfCoreCapabilityUseStore _useStore; - private readonly EfCoreAuditResidueStore _auditStore; + private readonly EfCoreDecisionReceiptStore _auditStore; public async Task TryStartAsync( string capabilityId, - AuditResidue executionStart, + DecisionReceipt executionStart, CancellationToken cancellationToken) { await using var transaction = @@ -1491,9 +1491,9 @@ The `AsiBackbone` repository provides the governance-side abstractions that make Relevant references include: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — carries policy identity and structured outcomes without owning persistence. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — provider-neutral governance evidence that can be persisted by a host-selected durable store. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — carries scoped authority metadata while leaving storage and execution ownership to the host. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — carries policy identity and structured outcomes without owning persistence. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provider-neutral governance evidence that can be persisted by a host-selected durable store. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — carries scoped authority metadata while leaving storage and execution ownership to the host. The architectural bridge is: @@ -1543,7 +1543,7 @@ Before calling a persistence design complete, ask: 9. Are transaction boundaries short-lived? 10. Is one-time or bounded-use capability state enforced atomically under concurrency? 11. Are database constraints/concurrency mechanisms part of the guarantee rather than only application-level checks? -12. Are governance audit residue and generic database-change auditing modeled separately? +12. Are governance decision receipt and generic database-change auditing modeled separately? 13. Does an interceptor contain hidden workflow/business logic? 14. Is interceptor ordering deliberate when several save concerns interact? 15. What happens when the database is unavailable? @@ -1585,8 +1585,8 @@ The purpose is narrower: ## Related Content - [Centralized Error Handling and Problem Details](centralized-error-handling-and-problem-details.md) — keep expected persistence outcomes distinct from unexpected application failures and map safe public errors at the host boundary. -- [Build a Governed API Operation lab](../labs/build-a-governed-api-operation.md) — assemble authorization, governance, scoped authority, host-owned execution, and audit residue inside an ASP.NET Core operation. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — review why governance evidence may need durable storage beyond ordinary logs. +- [Build a Governed API Operation lab](../labs/build-a-governed-api-operation.md) — assemble authorization, governance, scoped authority, host-owned execution, and decision receipt inside an ASP.NET Core operation. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — review why governance evidence may need durable storage beyond ordinary logs. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — review the execution-boundary authority that durable use state may need to protect. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — examine atomic capability consumption, durable replay state, idempotency, outbox/inbox reasoning, and exactly-once boundaries in more depth. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — preserve the policy evidence that produced a durable decision without rewriting historical identity later. diff --git a/docs/aspnetcore/index.md b/docs/aspnetcore/index.md index 1fcc2ec..c6f0a1f 100644 --- a/docs/aspnetcore/index.md +++ b/docs/aspnetcore/index.md @@ -4,7 +4,7 @@ description: Explore practical ASP.NET Core architecture for middleware, secure # ASP.NET Core -The ASP.NET Core section connects the architectural ideas in ASI Backbone Learning to practical application structure in modern .NET web applications. +The ASP.NET Core section connects the architectural ideas in AsiBackbone Learning to practical application structure in modern .NET web applications. The focus is not on teaching every ASP.NET Core feature. @@ -26,7 +26,7 @@ Continue with the [Identify Middleware Ordering Problems lab](../labs/identify-m [Centralized Error Handling and Problem Details](centralized-error-handling-and-problem-details.md) then establishes one application-level exception boundary for unexpected failures, safe RFC 9457 Problem Details responses, deliberate status mapping, correlation with operational logs, and explicit HTTP translation of expected governance outcomes without converting those outcomes into exceptions. Its [companion sample](https://github.com/AsiBackbone/Learning/blob/main/samples/centralized-error-handling-and-problem-details/README.md) includes focused integration tests for safe `500` responses, known failure mapping, governance-result translation, correlation, and status-code Problem Details. -[Data-Access Boundaries and Transaction Reasoning with EF Core](data-access-boundaries-and-transaction-reasoning.md) continues from application behavior into durable state. It compares direct `DbContext` usage with meaningful persistence abstractions, explains default and explicit transaction boundaries, distinguishes generic database auditing from governance audit residue, examines `SaveChanges` interceptors, and keeps local relational atomicity separate from external side effects, idempotency, outbox/inbox patterns, and recovery. +[Data-Access Boundaries and Transaction Reasoning with EF Core](data-access-boundaries-and-transaction-reasoning.md) continues from application behavior into durable state. It compares direct `DbContext` usage with meaningful persistence abstractions, explains default and explicit transaction boundaries, distinguishes generic database auditing from governance decision receipt, examines `SaveChanges` interceptors, and keeps local relational atomicity separate from external side effects, idempotency, outbox/inbox patterns, and recovery. [Architecture Decision Records Preserve Architectural Reasoning](architecture-decision-records-preserve-architectural-reasoning.md) then shifts from runtime structure to architectural memory. It explains when a decision deserves an ADR, what belongs in the record, how ADRs differ from other documentation, and how context, alternatives, consequences, and review conditions preserve reasoning that code alone cannot show. @@ -95,7 +95,7 @@ Scoped Authority ↓ Host-Owned Execution ↓ -Response + Audit Residue +Response + Decision Receipt ``` The appropriate amount of structure depends on the application. diff --git a/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md b/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md index 2d4c818..4f2ff9d 100644 --- a/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md +++ b/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md @@ -8,7 +8,7 @@ description: Design structured ASP.NET Core logging with stable event identity, **Difficulty:** Intermediate -**Prerequisites:** Basic familiarity with ASP.NET Core, dependency injection, and `ILogger`. The [ASP.NET Core learning area](index.md) provides the broader application-architecture context. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) is useful when comparing operational telemetry with governance evidence. +**Prerequisites:** Basic familiarity with ASP.NET Core, dependency injection, and `ILogger`. The [ASP.NET Core learning area](index.md) provides the broader application-architecture context. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) is useful when comparing operational telemetry with governance evidence. **Learning objective:** Design structured operational events that answer specific diagnostic questions without turning logging into uncontrolled data collection. Choose stable event identity, useful low-risk properties, correlation context, exception boundaries, log levels, and retention intentionally; distinguish logs from metrics and traces; and preserve a hard boundary between operational logging and governance audit evidence. @@ -804,7 +804,7 @@ Long retention increases cost and the impact of accidental sensitive-data collec ## Operational Logs Are Not Governance Audit Evidence -This is the central boundary for ASI Backbone Learning. +This is the central boundary for AsiBackbone Learning. Operational logging answers questions such as: @@ -839,7 +839,7 @@ May be filtered, sampled, rotated, or short-retained versus: ```text -Governance Receipt +Decision Receipt ↓ Decision Reconstruction / Evidence ↓ @@ -866,7 +866,7 @@ ElapsedMilliseconds = 12 ↓ Troubleshooting -Governance receipt +Decision receipt Outcome = Denied ReasonCodes = ["resource.protected"] PolicyVersion = 4.1 @@ -946,8 +946,8 @@ Learning keeps the examples provider-neutral and intentionally small. | Logging levels, enrichment, and bounded local retention | [`appsettings.json`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/appsettings.json) | Provider-level minimums, correlation/trace properties, file rolling, retention limits, file-size limits, and request-logging options. Treat the concrete values as one implementation choice, not universal defaults. | | Repository decision behind the current logging provider | [ADR-0001: Use Structured Serilog Logging](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/docs/adr/0001-use-structured-serilog-logging.md) | Review why the template chose Serilog for its own structured-logging baseline, including the alternatives and tradeoffs it recorded. The Learning guidance remains provider-neutral. | | Tracing and metrics as separate observability concerns | [`OpenTelemetryServiceExtensions.cs`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/Extensions/OpenTelemetryServiceExtensions.cs) | Independent tracing/metrics enablement, ASP.NET Core and `HttpClient` instrumentation, service resource identity, and optional OTLP export. | -| Governance evidence rather than ordinary telemetry | [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) | The Learning boundary between operational logs and structured decision/acknowledgment/execution evidence. | -| Production-oriented audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | How the governance implementation discusses safe metadata handling across audit and telemetry surfaces without collapsing them into one store. | +| Governance evidence rather than ordinary telemetry | [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) | The Learning boundary between operational logs and structured decision/acknowledgment/execution evidence. | +| Production-oriented audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | How the governance implementation discusses safe metadata handling across audit and telemetry surfaces without collapsing them into one store. | Use these repositories as working specimens rather than as package requirements for the tutorial. @@ -961,7 +961,7 @@ Before adding a new event, ask: 1. What exact operational question will this event answer? 2. Is there already another event at the correct architectural boundary? -3. Should this be a log, metric, trace attribute/span, health signal, or governance receipt instead? +3. Should this be a log, metric, trace attribute/span, health signal, or decision receipt instead? 4. Does the event have a stable operation/event identity? 5. Are the property names stable and meaningful? 6. Can any property contain a password, key, token, cookie, authorization header, verification code, or secret? @@ -1035,7 +1035,7 @@ Before moving on, you should be able to answer: 13. How can high-cardinality properties affect observability cost? 14. Why should environment-specific logging change verbosity without relaxing secret-handling rules? 15. Why is retention part of logging architecture? -16. Why is a structured operational log not automatically a governance audit receipt? +16. Why is a structured operational log not automatically a decision receipt? 17. How can one correlation ID connect operational telemetry and governance evidence while preserving separate purposes? ## Related Content @@ -1043,7 +1043,7 @@ Before moving on, you should be able to answer: - [ASP.NET Core learning area](index.md) - [Middleware Ordering Changes Behavior](middleware-ordering-changes-behavior.md) - [Secure-by-Default ASP.NET Core Configuration](secure-by-default-configuration.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) - [NetCoreApplicationTemplate](https://github.com/AsiBackbone/NetCoreApplicationTemplate) diff --git a/docs/case-studies/deployment-approval-and-infrastructure-change-gates.md b/docs/case-studies/deployment-approval-and-infrastructure-change-gates.md index faea23e..a2b82f4 100644 --- a/docs/case-studies/deployment-approval-and-infrastructure-change-gates.md +++ b/docs/case-studies/deployment-approval-and-infrastructure-change-gates.md @@ -720,7 +720,7 @@ BaseStateVersion ProviderAccountRef ``` -Do **not** use governance receipts as a convenient place to retain: +Do **not** use decision receipts as a convenient place to retain: - deployment credentials; - cloud access tokens; diff --git a/docs/case-studies/governed-administrative-operation.md b/docs/case-studies/governed-administrative-operation.md index 316d7ee..8bf7344 100644 --- a/docs/case-studies/governed-administrative-operation.md +++ b/docs/case-studies/governed-administrative-operation.md @@ -10,7 +10,7 @@ description: Follow an account-disable request through authorization, trusted co **Difficulty:** Intermediate -**Prerequisites:** Recommended — [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) is useful for the paused branch. +**Prerequisites:** Recommended — [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) is useful for the paused branch. **Estimated study time:** 30–45 minutes for the full case. The five-minute path below is enough to understand the composition before deciding whether the deeper implementation and operational sections are useful. @@ -488,7 +488,7 @@ Allowed now? └── yes → issue scoped execution authority ``` -That prevents acknowledgment from becoming a policy bypass. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) covers challenge binding and evidence in detail. +That prevents acknowledgment from becoming a policy bypass. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) covers challenge binding and evidence in detail. --- @@ -1190,7 +1190,7 @@ For the individual boundaries behind this composition: - [Decision Before Execution](../tutorials/decision-before-execution.md) explains the foundational zero-execution invariant. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) develops authoritative context and richer outcomes. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) covers bound interruption and evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) covers bound interruption and evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) covers narrow continuation authority and execution-boundary validation. - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) covers policy identity, drift, and historical evidence. diff --git a/docs/case-studies/human-acknowledgment-workflow.md b/docs/case-studies/human-acknowledgment-workflow.md index 1bd6a50..3609de4 100644 --- a/docs/case-studies/human-acknowledgment-workflow.md +++ b/docs/case-studies/human-acknowledgment-workflow.md @@ -10,7 +10,7 @@ description: Follow a bulk change through an acknowledgment-required decision, d **Difficulty:** Intermediate -**Prerequisites:** Recommended — [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) is useful when the requirement is independent review rather than acknowledgment. +**Prerequisites:** Recommended — [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) is useful when the requirement is independent review rather than acknowledgment. **Estimated study time:** 35–50 minutes for the guided path or approximately 75–95 minutes for a careful full read including the persistence, race, evidence, and failure sections. @@ -1749,7 +1749,7 @@ It demonstrates the boundaries and the questions an implementation needs to answ Continue with: -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — foundational challenge, response, and audit-residue concepts. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — foundational challenge, response, and decision-receipt concepts. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — narrow authority after a current allowed decision. - [Human-in-the-Loop Governance Workflows](../governance/human-in-the-loop-governance-workflows.md) — approval/review lifecycles and reviewer eligibility. - [Escalation Patterns in Governed Systems](../governance/escalation-patterns-in-governed-systems.md) — when policy routes to additional authority rather than acknowledgment. diff --git a/docs/docfx.json b/docs/docfx.json index 6a018b6..9bcb094 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -36,21 +36,21 @@ ], "globalMetadata": { "_lang": "en", - "_appName": "ASI Backbone Learning", - "_appTitle": "ASI Backbone Learning", + "_appName": "AsiBackbone Learning", + "_appTitle": "AsiBackbone Learning", "_appLogoPath": "images/asibackbone-icon-50.png", "_appFaviconPath": "images/favicon.ico", "_enableSearch": true, "_deferSearch": true, "_canonicalBaseUrl": "https://asibackbone.github.io/Learning/", - "_structuredDataSiteName": "ASI Backbone Learning", - "_structuredDataSiteAlternateName": "Accountable Systems Infrastructure (ASI) Backbone Learning", + "_structuredDataSiteName": "AsiBackbone Learning", + "_structuredDataSiteAlternateName": "AsiBackbone Learning", "_structuredDataSiteDescription": "Practical .NET architecture tutorials, labs, and reference patterns for governed execution, secure applications, AI integration, and policy-driven systems.", - "_structuredDataPublisherName": "ASI Backbone", - "_structuredDataPublisherAlternateName": "Accountable Systems Infrastructure (ASI) Backbone", + "_structuredDataPublisherName": "AsiBackbone", + "_structuredDataPublisherAlternateName": "AsiBackbone", "_structuredDataPublisherUrl": "https://github.com/AsiBackbone", "_socialImageUrl": "https://asibackbone.github.io/Learning/images/asibackbone-social.png", - "_socialImageAlt": "ASI Backbone Learning — practical .NET architecture, security, and governed execution" + "_socialImageAlt": "AsiBackbone Learning — practical .NET architecture, security, and governed execution" } } } diff --git a/docs/getting-started/adoption-personas-and-entry-points.md b/docs/getting-started/adoption-personas-and-entry-points.md index 8185fe9..61c685b 100644 --- a/docs/getting-started/adoption-personas-and-entry-points.md +++ b/docs/getting-started/adoption-personas-and-entry-points.md @@ -4,7 +4,7 @@ description: Choose a Learning path based on whether you are a developer, system # Adoption Personas and Entry Points -ASI Backbone Learning supports several kinds of readers. You do not need to read every topic in sequence before deciding whether the architecture is relevant to your work. +AsiBackbone Learning supports several kinds of readers. You do not need to read every topic in sequence before deciding whether the architecture is relevant to your work. Start with the responsibility you own, follow the shortest useful path, and evaluate the boundaries rather than assuming the framework is the answer. @@ -80,7 +80,7 @@ The goal is to determine whether that separation improves your system enough to **Start with:** -1. [Accountable Systems Infrastructure and Governed Execution](../architecture/accountable-systems-infrastructure-and-governed-execution.md) +1. [AsiBackbone and Governed Execution](../architecture/asibackbone-and-governed-execution.md) 2. [Governance Tool Selection and Composition](../architecture/governance-tool-selection-and-composition.md) 3. [Policy Engines, Rules Engines, and Distributed Policy Enforcement](../architecture/policy-engines-rules-engines-and-distributed-policy-enforcement.md) 4. [Federated Governance and Independent Authority Coordination](../advanced/federated-governance-and-independent-authority-coordination.md) @@ -120,7 +120,7 @@ The goal is to determine whether that separation improves your system enough to **Start with:** 1. [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) -2. [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +2. [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) 3. [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) 4. [Governed Execution in Regulated Systems](../advanced/governed-execution-in-regulated-systems.md) diff --git a/docs/getting-started/find-your-path.md b/docs/getting-started/find-your-path.md index a88774b..39533a1 100644 --- a/docs/getting-started/find-your-path.md +++ b/docs/getting-started/find-your-path.md @@ -1,10 +1,10 @@ --- -description: Choose a short, problem-oriented route through ASI Backbone Learning based on common ASP.NET Core, governance, AI, security, and architecture goals. +description: Choose a short, problem-oriented route through AsiBackbone Learning based on common ASP.NET Core, governance, AI, security, and architecture goals. --- # Find Your Path -ASI Backbone Learning can be used as a sequential course, but you do not need to read it that way. +AsiBackbone Learning can be used as a sequential course, but you do not need to read it that way. If you already know the problem you are trying to solve, start with the shortest route that makes the relevant boundary visible. Stop when the simpler design preserves the behavior, evidence, and control you need; go deeper only when it does not. @@ -79,7 +79,7 @@ The goal is not to maximize framework adoption. The goal is to make the architec **Start:** [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md). -**Build the lifecycle:** Continue with [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), then [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). +**Build the lifecycle:** Continue with [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), then [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). ```text Administrative intent @@ -92,7 +92,7 @@ Scoped capability ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` **See the composition:** [Governed Administrative Operation](../case-studies/governed-administrative-operation.md) follows one fictional `account.disable` request through standing authorization, authoritative context, policy evaluation, acknowledgment or escalation, scoped authority, executor invocation, and correlated evidence. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 75cda39..e0a4d07 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,10 +1,10 @@ --- -description: Start ASI Backbone Learning with core governed-execution concepts, the recommended learning path, practical examples, labs, and pattern-evaluation guidance. +description: Start AsiBackbone Learning with core governed-execution concepts, the recommended learning path, practical examples, labs, and pattern-evaluation guidance. --- # Getting Started -Welcome to **ASI Backbone Learning**. +Welcome to **AsiBackbone Learning**. This repository teaches governance and controlled-execution architecture through small explanations, runnable examples, invariant tests, and hands-on labs. You do not need to adopt the `AsiBackbone` package or any specific framework to use the material. @@ -74,7 +74,7 @@ The foundation is deliberately progressive. Each topic adds one boundary to the |---|---|---|---| | 1 | [**Decision Before Execution**](../tutorials/decision-before-execution.md) | Denied decision → no execution | [Lab](../labs/decision-before-execution.md) | | 2 | [**Policy Context and Explicit Decision Outcomes**](../tutorials/policy-context-and-explicit-decision-outcomes.md) | Decisions are explicit, not boolean-only | [Lab](../labs/policy-context-and-explicit-decision-outcomes.md) | -| 3 | [**Acknowledgment and Audit Residue**](../tutorials/acknowledgment-and-audit-residue.md) | Acknowledgment does not grant execution authority | [Lab](../labs/acknowledgment-and-audit-residue.md) | +| 3 | [**Decision Receipts and Acknowledgment**](../tutorials/decision-receipts-and-acknowledgment.md) | Acknowledgment does not grant execution authority | [Lab](../labs/decision-receipts-and-acknowledgment.md) | | 4 | [**Scoped Capability and Host-Owned Execution**](../tutorials/scoped-capability-and-host-owned-execution.md) | Expired or stale authority blocks execution | [Lab](../labs/scoped-capability-and-host-owned-execution.md) | | 5 | [**Governed AI Tool Gateway**](../tutorials/governed-ai-tool-gateway.md) | Unknown or unauthorized AI tool proposal → no execution | [Lab](../labs/governed-ai-tool-gateway.md) | @@ -139,7 +139,7 @@ Use the smallest architecture that preserves the boundaries you actually need. I ## Working Repository References -ASI Backbone Learning is the educational layer of the organization. The working repositories provide fuller implementation examples: +AsiBackbone Learning is the educational layer of the organization. The working repositories provide fuller implementation examples: - [`AsiBackbone/AsiBackbone`](https://github.com/AsiBackbone/AsiBackbone) — a .NET governance and policy-control framework covering policy evaluation, structured decisions, acknowledgment workflows, audit/provenance, capability-scoped authority, host-owned execution, and AI/application governance. - [`AsiBackbone/NetCoreApplicationTemplate`](https://github.com/AsiBackbone/NetCoreApplicationTemplate) — an enterprise-oriented ASP.NET Core reference implementation demonstrating middleware organization, structured logging, security defaults, error handling, rate limiting, authentication-ready architecture, data access, and Architecture Decision Records. @@ -158,7 +158,7 @@ For a concrete comparison, see [**When ASP.NET Core Authorization Is Enough**](. ## Scope and Boundaries -ASI Backbone Learning is an educational and architectural resource. It is **not** a compliance certification, legal standard, security guarantee, AI model, AGI/ASI implementation, robotics controller, or substitute for application-specific security review. +AsiBackbone Learning is an educational and architectural resource. It is **not** a compliance certification, legal standard, security guarantee, AI model, AGI/ASI implementation, robotics controller, or substitute for application-specific security review. Production systems remain responsible for their own authentication, authorization, infrastructure, persistence, safety controls, regulatory requirements, threat modeling, and operational execution. diff --git a/docs/getting-started/learning-model.md b/docs/getting-started/learning-model.md index 7198434..7c8b3e7 100644 --- a/docs/getting-started/learning-model.md +++ b/docs/getting-started/learning-model.md @@ -4,7 +4,7 @@ description: Understand Learning's problem-first model, the roles of tutorials, # Learning Model -ASI Backbone Learning is a living architecture-learning resource, not a product manual or framework adoption funnel. +AsiBackbone Learning is a living architecture-learning resource, not a product manual or framework adoption funnel. Its purpose is to help a reader understand an architectural boundary, observe it in a small implementation, verify the claimed invariant, challenge the design, and adapt only what is useful. @@ -167,7 +167,7 @@ Material may therefore distinguish between two pattern types. | Pattern type | What it means | What it does not mean | | --- | --- | --- | -| **Canonical** | Aligned with the current architecture of one or more ASI Backbone organization projects | Universal, mandatory, or superior in every context | +| **Canonical** | Aligned with the current architecture of one or more AsiBackbone organization projects | Universal, mandatory, or superior in every context | | **Alternative** | A technically grounded approach that solves the same problem differently | Incorrect merely because it differs from the working repositories | A canonical pattern answers: diff --git a/docs/getting-started/learning-path-map.md b/docs/getting-started/learning-path-map.md index 92d99fb..28d6d45 100644 --- a/docs/getting-started/learning-path-map.md +++ b/docs/getting-started/learning-path-map.md @@ -4,7 +4,7 @@ description: Visualize the recommended Learning progression, problem-first entry # Learning Path Map -ASI Backbone Learning is a curriculum, but it is not one mandatory linear course. +AsiBackbone Learning is a curriculum, but it is not one mandatory linear course. New readers can build the governed-execution vocabulary through the five foundational topics in order. Experienced readers can enter through [Find Your Path](find-your-path.md), choose the subject area that matches the problem, and return to earlier material only when a missing concept becomes relevant. @@ -31,7 +31,7 @@ flowchart TD subgraph FOUNDATION["Recommended foundation for new readers"] direction TB D --> P["2. Policy Context + Explicit Decision Outcomes"] - P --> A["3. Acknowledgment + Audit Residue"] + P --> A["3. Decision Receipts + Acknowledgment"] A --> C["4. Scoped Capability + Host-Owned Execution"] C --> G["5. Governed AI Tool Gateway"] end @@ -62,7 +62,7 @@ flowchart TD click FP "https://asibackbone.github.io/Learning/getting-started/find-your-path.html" "Open Find Your Path" click D "https://asibackbone.github.io/Learning/tutorials/decision-before-execution.html" "Open Decision Before Execution" click P "https://asibackbone.github.io/Learning/tutorials/policy-context-and-explicit-decision-outcomes.html" "Open Policy Context and Explicit Decision Outcomes" - click A "https://asibackbone.github.io/Learning/tutorials/acknowledgment-and-audit-residue.html" "Open Acknowledgment and Audit Residue" + click A "https://asibackbone.github.io/Learning/tutorials/decision-receipts-and-acknowledgment.html" "Open Decision Receipts and Acknowledgment" click C "https://asibackbone.github.io/Learning/tutorials/scoped-capability-and-host-owned-execution.html" "Open Scoped Capability and Host-Owned Execution" click G "https://asibackbone.github.io/Learning/tutorials/governed-ai-tool-gateway.html" "Open Governed AI Tool Gateway" click ARCH "https://asibackbone.github.io/Learning/architecture/" "Open Architecture" @@ -93,7 +93,7 @@ For readers who cannot use the diagram, the same foundation is listed below. | --- | --- | --- | | 1 | [Decision Before Execution](../tutorials/decision-before-execution.md) | Evaluation and protected execution become separate responsibilities | | 2 | [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) | Decision inputs, outcomes, reason codes, and policy identity become explicit | -| 3 | [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) | Acknowledgment becomes distinct and governed-path evidence is preserved | +| 3 | [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) | Acknowledgment becomes distinct and governed-path evidence is preserved | | 4 | [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) | Execution authority becomes narrow while the host retains the final side effect | | 5 | [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) | Earlier boundaries are composed around AI-proposed tool execution | diff --git a/docs/governance/constraint-composition-and-policy-precedence.md b/docs/governance/constraint-composition-and-policy-precedence.md index 207a3c9..bbed2c0 100644 --- a/docs/governance/constraint-composition-and-policy-precedence.md +++ b/docs/governance/constraint-composition-and-policy-precedence.md @@ -1024,7 +1024,7 @@ Preserve the distinction through: * Stable reason codes. * Operational logging. * Metrics or alerts where useful. -* Audit residue. +* Decision receipt. * Exception telemetry that does not leak sensitive data. A reviewer should be able to tell the difference between: @@ -1229,12 +1229,12 @@ The `AsiBackbone/AsiBackbone` repository provides a fuller implementation of the | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Core policy vocabulary | [Core Domain Language](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/core-domain-language.md) | Context, constraints, active policy structure, decisions, and host boundary | -| Constraint evaluation and base composition | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) | Deny/warning/allow composition, empty-policy behavior, short-circuiting, exception posture, and reason handling | -| Post-composition policy | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Warning preservation, regional overlays, acknowledgment, escalation, and host-owned execution | -| Concrete evaluator | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | Source-level evaluation and composition behavior | -| Decision-policy contract | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | Boundary between base composition and host/domain decision transformation | -| End-to-end behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable policy-evaluator invariants | +| Core policy vocabulary | [Core Domain Language](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/core-domain-language.md) | Context, constraints, active policy structure, decisions, and host boundary | +| Constraint evaluation and base composition | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) | Deny/warning/allow composition, empty-policy behavior, short-circuiting, exception posture, and reason handling | +| Post-composition policy | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Warning preservation, regional overlays, acknowledgment, escalation, and host-owned execution | +| Concrete evaluator | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Source-level evaluation and composition behavior | +| Decision-policy contract | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | Boundary between base composition and host/domain decision transformation | +| End-to-end behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable policy-evaluator invariants | The Learning article remains framework-neutral on purpose. @@ -1271,7 +1271,7 @@ If several answers are unclear, the system may have policy logic, but it does no - [Risk-Based Decisions in Governed Systems](risk-based-decisions-in-governed-systems.md) — add risk assessment as an explicit, reviewable input without allowing risk scoring to bypass deterministic constraints or host-owned execution. - [Regional and Tenant Policy Overlays](../advanced/regional-and-tenant-policy-overlays.md) — extend composition from multiple constraints inside one policy boundary to multiple policy authorities with explicit narrowing, override, conflict, and provenance rules. - [Decision Before Execution](../tutorials/decision-before-execution.md) — revisit the boundary between a governance decision and the protected side effect. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — continue from final decisions into acknowledgment and governance evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — continue from final decisions into acknowledgment and governance evidence. - [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) — compare the richer governance model with a simpler built-in authorization approach. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — see composition participate in an end-to-end AI-assisted workflow while the host retains execution authority. diff --git a/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md b/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md index f817c8f..010bf6d 100644 --- a/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md +++ b/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md @@ -2214,13 +2214,13 @@ The `AsiBackbone/AsiBackbone` repository provides useful implementation surfaces | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Policy-context contract | [`IAsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IAsiBackboneConstraintEvaluationContext.cs) | The minimal context boundary consumed by constraints. | -| Concrete host-provided context | [`AsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/AsiBackboneConstraintEvaluationContext.cs) | Correlation, policy identity, and normalized metadata supplied by the host. | -| Policy evaluation | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | Constraint evaluation and base decision composition. | -| Post-composition decision policy | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | A host/domain boundary where broader policy can interpret composed results and context. | -| Structured governance result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity returned to the host. | -| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Examples of host-provided risk metadata influencing a final decision while execution remains host-owned. | -| Execution enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | The boundary that keeps decisions and context separate from the protected side effect. | +| Policy-context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimal context boundary consumed by constraints. | +| Concrete host-provided context | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation, policy identity, and normalized metadata supplied by the host. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation and base decision composition. | +| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A host/domain boundary where broader policy can interpret composed results and context. | +| Structured governance result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity returned to the host. | +| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Examples of host-provided risk metadata influencing a final decision while execution remains host-owned. | +| Execution enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | The boundary that keeps decisions and context separate from the protected side effect. | The implementation does not require a particular ML platform, scoring service, probability representation, or calibration method. diff --git a/docs/governance/escalation-patterns-in-governed-systems.md b/docs/governance/escalation-patterns-in-governed-systems.md index e47b472..ed33dc7 100644 --- a/docs/governance/escalation-patterns-in-governed-systems.md +++ b/docs/governance/escalation-patterns-in-governed-systems.md @@ -94,7 +94,7 @@ Escalation can route to a human reviewer, a specialized policy service, or an ex Use the canonical material for the downstream boundary that actually applies: -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for acknowledgment semantics. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for acknowledgment semantics. - [Human-in-the-Loop Governance Workflows](human-in-the-loop-governance-workflows.md) for reviewer approval, rejection, and bounded override behavior. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) for execution authority and host-owned side effects. @@ -1474,7 +1474,7 @@ That timeline is more informative than one mutable row called `approval_status`. --- -## Audit Residue +## Decision Receipt Useful lifecycle events can include: @@ -2031,13 +2031,13 @@ The `AsiBackbone/AsiBackbone` repository already exposes the structured outcome | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Escalation outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework outcome that includes `EscalationRecommended`. | -| Structured decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reason codes, correlation/trace identifiers, and policy identity that a host can preserve before routing. | -| Post-composition decision policy | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | The host/domain boundary where broader policy can refine a composed result. | -| Escalation example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | A gateway-readiness example that can return escalation without performing the protected action. | -| Audit evidence | [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) | Structured evidence that can preserve decision outcome, reasons, policy identity, and correlation. | -| Host execution boundary | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why a governance result still requires explicit host enforcement before side effects. | -| High-consequence scenario | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | A scenario where escalation-recommended outcomes remain non-executable and host-controlled. | +| Escalation outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework outcome that includes `EscalationRecommended`. | +| Structured decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reason codes, correlation/trace identifiers, and policy identity that a host can preserve before routing. | +| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The host/domain boundary where broader policy can refine a composed result. | +| Escalation example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | A gateway-readiness example that can return escalation without performing the protected action. | +| Audit evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | Structured evidence that can preserve decision outcome, reasons, policy identity, and correlation. | +| Host execution boundary | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why a governance result still requires explicit host enforcement before side effects. | +| High-consequence scenario | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | A scenario where escalation-recommended outcomes remain non-executable and host-controlled. | A host may implement escalation persistence and routing using: @@ -2112,7 +2112,7 @@ If several answers are unclear, the system may have an escalation label, but it - [Risk-Based Decisions in Governed Systems](risk-based-decisions-in-governed-systems.md) — map high consequence or uncertainty into escalation without turning risk itself into authority. - [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) — preserve initial and later policy identities across a multi-stage decision path. - [Practical Policy Testing and Decision-Table Strategies](practical-policy-testing-and-decision-table-strategies.md) — make routing, timeout, depth, degraded behavior, and execution invariants regression-testable. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — distinguish escalation from acknowledgment and preserve correlated lifecycle evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — distinguish escalation from acknowledgment and preserve correlated lifecycle evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — keep later executable authority narrow even after an escalation resolves favorably. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — apply escalation to AI-proposed actions without giving the model routing or execution authority. - [Regional and Tenant Policy Overlays](../advanced/regional-and-tenant-policy-overlays.md) — align escalation routing with regional, tenant, and policy-authority boundaries. diff --git a/docs/governance/human-in-the-loop-governance-workflows.md b/docs/governance/human-in-the-loop-governance-workflows.md index 4086694..b413a12 100644 --- a/docs/governance/human-in-the-loop-governance-workflows.md +++ b/docs/governance/human-in-the-loop-governance-workflows.md @@ -10,7 +10,7 @@ description: Learn to model human review as an explicit governed workflow state **Difficulty:** Intermediate -**Prerequisites:** [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) +**Prerequisites:** [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) ## At a Glance @@ -110,7 +110,7 @@ Human review can involve several different acts, but the workflow should not col | Override | A specifically delegated authority supersedes a policy result within defined limits | Not by itself | | Execution authority | Narrow authority accepted at the protected execution boundary | Only when the host validates and uses it | -The foundational meanings of authorization and governance outcomes are already covered in [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md). The acknowledgment boundary is covered in [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), and execution authority in [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). +The foundational meanings of authorization and governance outcomes are already covered in [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md). The acknowledgment boundary is covered in [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), and execution authority in [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). The distinction that matters here is specific to human review: a reviewer can acknowledge that a request is high risk and still reject it, while a requester can acknowledge a warning without having authority to approve the operation. @@ -393,7 +393,7 @@ Reviewer identity may then participate in: - Eligibility. - Separation-of-duty checks. - Delegation. -- Audit residue. +- Decision receipt. - Quorum. - Conflict-of-interest rules. - Policy revalidation. @@ -1210,7 +1210,7 @@ See [Policy Versioning and Decision Provenance](policy-versioning-and-decision-p --- -## Audit Residue Should Preserve Lifecycle Events +## Lifecycle Evidence Should Preserve Later Events Human review creates more than one meaningful event. @@ -1246,7 +1246,7 @@ does not explain: - Whether execution actually happened. - Whether approval was policy-compliant or an override. -Keep governance residue distinct from ordinary operational logging, following [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md). +Keep the decision receipt and its correlated lifecycle events distinct from ordinary operational logging, following [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md). --- @@ -1741,12 +1741,12 @@ The `AsiBackbone/AsiBackbone` repository contains implementation material that s | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Decision policy boundary | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | How host-owned decision policy can require acknowledgment or escalation without performing the protected action. | -| High-consequence administrative flow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | Host ownership of identity, authorization, UI, persistence, decision handling, acknowledgment, audit, and execution. | -| Audit lifecycle evidence | [Audit Residue Observability Schema](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/audit-residue-observability-schema.md) | Structured decision and execution evidence suitable for correlation across lifecycle stages. | -| Host enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why decisions and policy results do not themselves perform the protected operation. | -| Governance decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The structured outcome consumed by a host-controlled workflow. | -| Audit lifecycle vocabulary | [`AuditResidueLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidueLifecycleStage.cs) | Lifecycle-oriented audit stages that can participate in broader host-owned workflow evidence. | +| Decision policy boundary | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | How host-owned decision policy can require acknowledgment or escalation without performing the protected action. | +| High-consequence administrative flow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | Host ownership of identity, authorization, UI, persistence, decision handling, acknowledgment, audit, and execution. | +| Audit lifecycle evidence | [Decision Receipt Observability Schema](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/decision-receipt-observability-schema.md) | Structured decision and execution evidence suitable for correlation across lifecycle stages. | +| Host enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why decisions and policy results do not themselves perform the protected operation. | +| Governance decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The structured outcome consumed by a host-controlled workflow. | +| Audit lifecycle vocabulary | [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | Lifecycle-oriented audit stages that can participate in broader host-owned workflow evidence. | The implementation references do not require a particular human-review UI, queue, workflow engine, or persistence product. @@ -1763,7 +1763,7 @@ Scoped continuation authority ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` --- @@ -1804,7 +1804,7 @@ If several answers are unclear, the system may have an approval screen, but it d ## Related Content -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — distinguish acknowledgment from approval and preserve decision, acknowledgment, re-evaluation, and execution evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — distinguish acknowledgment from approval and preserve decision, acknowledgment, re-evaluation, and execution evidence. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — build the authoritative facts and structured outcomes that can lead into a human-review state. - [Risk-Based Decisions in Governed Systems](risk-based-decisions-in-governed-systems.md) — see how changing consequence, likelihood, uncertainty, and environmental context can change whether human review is required. - [Escalation Patterns in Governed Systems](escalation-patterns-in-governed-systems.md) — place human review inside a broader escalation lifecycle when another authority must receive and resolve the decision problem. diff --git a/docs/governance/index.md b/docs/governance/index.md index 9598f66..559d3d1 100644 --- a/docs/governance/index.md +++ b/docs/governance/index.md @@ -41,7 +41,7 @@ Scoped Authority ↓ Host-Owned Execution ↓ -Audit Residue +Decision Receipt ``` The individual stages may be implemented differently across systems. @@ -62,9 +62,9 @@ Introduces the separation between proposed intent, governance evaluation, and re Explores explicit policy facts, constraints, reason codes, policy identity, and structured outcomes. -### Acknowledgment and Audit Residue +### Decision Receipts and Acknowledgment -[Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +[Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) Examines workflows that pause for acknowledgment and preserve evidence of the decision path. diff --git a/docs/governance/policy-versioning-and-decision-provenance.md b/docs/governance/policy-versioning-and-decision-provenance.md index 450bc56..b97cd9f 100644 --- a/docs/governance/policy-versioning-and-decision-provenance.md +++ b/docs/governance/policy-versioning-and-decision-provenance.md @@ -10,7 +10,7 @@ description: Learn to preserve policy identity and decision provenance, detect p **Difficulty:** Intermediate -**Prerequisites:** [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) and [Constraint Composition and Policy Precedence](constraint-composition-and-policy-precedence.md). Familiarity with [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) is helpful for the continuation examples. +**Prerequisites:** [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) and [Constraint Composition and Policy Precedence](constraint-composition-and-policy-precedence.md). Familiarity with [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) is helpful for the continuation examples. ## At a Glance @@ -1100,7 +1100,7 @@ Do not make the second claim unless the required artifacts are actually retained --- -## Preserve Provenance Across Audit Residue +## Preserve Provenance Across Decision Receipt A useful audit timeline can retain both historical and current policy identity without overwriting either. @@ -1121,7 +1121,7 @@ Decision B created under 4.3 An evidence record for the freshness check could contain: ```csharp -public sealed record PolicyFreshnessResidue( +public sealed record PolicyFreshnessReceipt( string EventId, string CorrelationId, string DecisionId, @@ -1385,25 +1385,25 @@ The current `AsiBackbone` implementation provides several useful working referen ### GovernanceDecision -[`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) carries optional `PolicyVersion` and `PolicyHash` values on the decision itself. +[`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) carries optional `PolicyVersion` and `PolicyHash` values on the decision itself. That demonstrates the important boundary that policy evidence can travel with the result rather than remaining only in transient evaluation context. The current type does not define a dedicated `PolicyId` property. A host that needs a stable logical policy-family identifier should model that requirement explicitly rather than pretending `PolicyVersion` means both identity and revision. -### AuditResidue +### DecisionReceipt -[`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) carries optional policy version/hash evidence and preserves those values when residue is created from a `GovernanceDecision`. +[`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) carries optional policy version/hash evidence and preserves those values when receipt is created from a `GovernanceDecision`. That is an example of policy evidence propagating into later governance evidence. ### CapabilityTokenGrant -[`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) can carry optional `PolicyVersion` and `PolicyHash` bindings into short-lived execution authority. +[`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) can carry optional `PolicyVersion` and `PolicyHash` bindings into short-lived execution authority. ### CapabilityGrantValidationOptions -[`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) allows an execution boundary to state expected policy version/hash values during capability validation. +[`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) allows an execution boundary to state expected policy version/hash values during capability validation. These references show concrete implementation seams. @@ -1482,7 +1482,7 @@ The lab starts from the existing Policy Context sample and asks you to: - Simulate policy drift. - Choose an execution-freshness rule. - Carry policy evidence through acknowledgment and capability issuance. -- Correlate historical and current policy identity in audit residue. +- Correlate historical and current policy identity in decision receipt. - Add a policy fingerprint without overclaiming what it proves. After that exercise, continue with [Policy Simulation and Change-Impact Analysis](../labs/policy-simulation-and-change-impact-analysis.md) to replay identical contexts against a baseline and candidate policy before rollout. @@ -1510,7 +1510,7 @@ AsiBackbone working implementation references - [Constraint Composition and Policy Precedence](constraint-composition-and-policy-precedence.md) — examine how several rule results and composition behavior become one final governance decision. - [Practical Policy Testing and Decision-Table Strategies](practical-policy-testing-and-decision-table-strategies.md) — test policy versions, drift, structured outcomes, and non-execution invariants as a coherent decision system. - [Regional and Tenant Policy Overlays](../advanced/regional-and-tenant-policy-overlays.md) — preserve multiple contributor identities and reason about precedence, override authority, regional or tenant drift, and composite execution freshness. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — connect decision provenance to acknowledgment, re-evaluation, and durable governance evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — connect decision provenance to acknowledgment, re-evaluation, and durable governance evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — see policy identity carried into narrow execution authority. - [Policy-Version Evidence in Governance Decisions lab](../labs/policy-version-evidence-in-governance-decisions.md) — practice preserving provenance and detecting policy drift. - [Policy Simulation and Change-Impact Analysis lab](../labs/policy-simulation-and-change-impact-analysis.md) — compare baseline and candidate behavior using identical contexts while keeping simulation non-executable. diff --git a/docs/governance/practical-policy-testing-and-decision-table-strategies.md b/docs/governance/practical-policy-testing-and-decision-table-strategies.md index 648a3df..0e9f41b 100644 --- a/docs/governance/practical-policy-testing-and-decision-table-strategies.md +++ b/docs/governance/practical-policy-testing-and-decision-table-strategies.md @@ -1563,8 +1563,8 @@ The Learning repository and the `AsiBackbone` implementation repository contain | --- | --- | --- | | Explicit outcome assertions | [`DecisionOutcomeTests`](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/Tests/DecisionOutcomeTests.cs) | Direct assertions for `Denied`, `Deferred`, `AcknowledgmentRequired`, and `Allowed` | | Table-like scenario coverage | [Policy Context sample program](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/Sample/Program.cs) | Named policy scenarios covering all major disable-account outcomes | -| Composition invariants | [`DefaultAsiBackbonePolicyEvaluatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/DefaultAsiBackbonePolicyEvaluatorTests.cs) | Empty-policy behavior, warning/denial composition, exception posture, short-circuiting, and decision-policy interaction | -| End-to-end evaluator behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Policy-evaluator invariants across the real implementation pipeline | +| Composition invariants | [`DefaultAsiBackbonePolicyEvaluatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/DefaultAsiBackbonePolicyEvaluatorTests.cs) | Compatibility-retained test fixture covering the 6.0 `DefaultGovernancePolicyEvaluator`: empty-policy behavior, warning/denial composition, exception posture, short-circuiting, and decision-policy interaction | +| End-to-end evaluator behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Policy-evaluator invariants across the real implementation pipeline | | Policy provenance | [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) | Historical identity, drift, freshness, and version/hash boundaries | | Bounded execution authority | [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) | Replay/use-state validation at the execution boundary | @@ -1622,7 +1622,7 @@ Repeatable automated test - [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) — extend regression cases across historical policy identity and drift. - [Policy Simulation and Change-Impact Analysis lab](../labs/policy-simulation-and-change-impact-analysis.md) — replay identical contexts against baseline and candidate policy versions, compare changed outcomes and reasons, and preserve a strict no-execution simulation boundary. - [Decision Before Execution](../tutorials/decision-before-execution.md) — revisit the boundary between a decision and a protected side effect. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — test delayed continuation without turning acknowledgment into authorization. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — test delayed continuation without turning acknowledgment into authorization. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — test capability issuance and host-owned execution boundaries. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — test replay, expiry, revocation, and bounded-use authority separately from policy approval. - [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) — compare the richer governance test surface with ordinary authorization requirements. diff --git a/docs/governance/risk-based-decisions-in-governed-systems.md b/docs/governance/risk-based-decisions-in-governed-systems.md index 6d68a41..fbaea09 100644 --- a/docs/governance/risk-based-decisions-in-governed-systems.md +++ b/docs/governance/risk-based-decisions-in-governed-systems.md @@ -1567,11 +1567,11 @@ This tutorial is framework-neutral, but the `AsiBackbone/AsiBackbone` repository | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Host/domain decision policy | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | The post-composition boundary where host policy can refine a decision without executing the protected action. | -| Risk-aware policy example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | The regional overlay example reads host-provided `risk` metadata and can require acknowledgment while preserving host-owned execution. | -| High-risk workflow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | A concrete scenario where actor, target, risk, policy metadata, acknowledgment, audit residue, and host execution remain separate responsibilities. | -| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The outcome and reason structure consumed by the host. | -| Policy evaluation | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | Constraint evaluation, base composition, and the optional decision-policy boundary. | +| Host/domain decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary where host policy can refine a decision without executing the protected action. | +| Risk-aware policy example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | The regional overlay example reads host-provided `risk` metadata and can require acknowledgment while preserving host-owned execution. | +| High-risk workflow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | A concrete scenario where actor, target, risk, policy metadata, acknowledgment, decision receipt, and host execution remain separate responsibilities. | +| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The outcome and reason structure consumed by the host. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation, base composition, and the optional decision-policy boundary. | The implementation repository does not require every host to adopt the qualitative model used in this tutorial. @@ -1627,7 +1627,7 @@ If several answers are unclear, the system may have a risk score, but it does no - [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) — preserve policy identity, drift, freshness, and reconstructable decision evidence. - [Practical Policy Testing and Decision-Table Strategies](practical-policy-testing-and-decision-table-strategies.md) — test risk thresholds, equivalence classes, failure posture, and decision boundaries systematically. - [Regional and Tenant Policy Overlays](../advanced/regional-and-tenant-policy-overlays.md) — model how multiple policy authorities may narrow, override, or otherwise influence the final decision through an explicit overlay contract. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — continue from `AcknowledgmentRequired` into a governed acknowledgment lifecycle and durable evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — continue from `AcknowledgmentRequired` into a governed acknowledgment lifecycle and durable evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — keep approval and risk posture separate from the authority used at the execution boundary. - [Safe Degraded Mode and Fail-Safe Governance lab](../labs/safe-degraded-mode-and-fail-safe-governance.md) — decide deliberately how unavailable dependencies affect governed execution. - [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md) — examine source-of-authority, bypass, tampering, stale-input, and dependency-failure threats around risk signals. diff --git a/docs/images/architecture/governance-spine.svg b/docs/images/architecture/governance-spine.svg index 039b662..a494c69 100644 --- a/docs/images/architecture/governance-spine.svg +++ b/docs/images/architecture/governance-spine.svg @@ -73,5 +73,5 @@ Audit / Lifecycle Evidence - decision, acknowledgment, authority, and outcome residue + decision, acknowledgment, authority, and outcome receipt diff --git a/docs/index.md b/docs/index.md index abbdd5e..ca14158 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ _disableBreadcrumb: true _disableToc: true --- -# ASI Backbone Learning +# AsiBackbone Learning

Practical .NET architecture for accountable systems

@@ -19,7 +19,7 @@ _disableToc: true

A proposed action should become a governed decision before it becomes real-world execution.

-ASI Backbone Learning explains architectural ideas, demonstrates them with focused examples, examines their tradeoffs, and connects the lessons to fuller working implementations. **ASI** means **Accountable Systems Infrastructure**. +AsiBackbone Learning explains architectural ideas, demonstrates them with focused examples, examines their tradeoffs, and connects the lessons to fuller working implementations. `AsiBackbone` is the product name; no acronym expansion is required to follow the material. > **Read it. Run it. Question it. Improve it.** @@ -59,10 +59,10 @@ The material uses a recurring separation of responsibilities:
  • Context
  • Constraints
  • Decision
    • +
  • Decision receipt
  • Acknowledgment when required
  • Scoped authority
  • Host-owned execution
    • -
  • Audit residue
    • ## Choose a learning path @@ -164,9 +164,9 @@ This is a living project under active development. Recent publications include:

    Canonical patterns document what the working repositories currently do; alternative patterns create room for comparison, criticism, and improvement. Canonical does not mean universal.

    -

    ASI Backbone Learning is an educational architecture resource—not a compliance certification, legal standard, security guarantee, AI model, AGI or ASI implementation, robotics controller, replacement for application-specific security review, or requirement to use the AsiBackbone package. Examples are teaching artifacts; production systems remain responsible for their own security, infrastructure, persistence, regulatory requirements, safety controls, and execution.

    +

    AsiBackbone Learning is an educational architecture resource—not a compliance certification, legal standard, security guarantee, AI model, AGI or ASI implementation, robotics controller, replacement for application-specific security review, or requirement to use the AsiBackbone package. Examples are teaching artifacts; production systems remain responsible for their own security, infrastructure, persistence, regulatory requirements, safety controls, and execution.

    -

    ASI Backbone Learning is not affiliated with the Artificial Superintelligence Alliance.

    +

    AsiBackbone Learning is not affiliated with the Artificial Superintelligence Alliance.

    --- diff --git a/docs/labs/analyze-flawed-high-consequence-workflow.md b/docs/labs/analyze-flawed-high-consequence-workflow.md index 9772274..8241a20 100644 --- a/docs/labs/analyze-flawed-high-consequence-workflow.md +++ b/docs/labs/analyze-flawed-high-consequence-workflow.md @@ -10,7 +10,7 @@ description: Diagnose a flawed account-disable workflow across trust, authority, **Pattern classification:** General learning material -**Prerequisites:** Recommended — [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md), [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md), and [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md). +**Prerequisites:** Recommended — [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md), [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md), and [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md). This lab is intentionally different from the earlier single-pattern exercises. @@ -1644,7 +1644,7 @@ What evidence survives? - [Decision Before Execution](../tutorials/decision-before-execution.md) — separate the decision from the side effect. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — rebuild policy context from explicit authoritative facts and preserve meaningful outcomes. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — distinguish acknowledgment from authorization and preserve lifecycle evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — distinguish acknowledgment from authorization and preserve lifecycle evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — keep later execution authority narrow, current, and host-enforced. - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) — identify where crossing a boundary changes what the host should believe. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — reason about replay state, atomic consumption, concurrency, and execution failure windows. diff --git a/docs/labs/build-a-governed-api-operation.md b/docs/labs/build-a-governed-api-operation.md index 5667951..59e343a 100644 --- a/docs/labs/build-a-governed-api-operation.md +++ b/docs/labs/build-a-governed-api-operation.md @@ -10,7 +10,7 @@ description: Extend an ASP.NET Core API into governed execution with explicit in **Pattern classification:** Canonical Pattern -**Prerequisites:** Complete [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). Read [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) before starting so that the authorization/governance boundary is explicit. +**Prerequisites:** Complete [Decision Before Execution](../tutorials/decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md). Read [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) before starting so that the authorization/governance boundary is explicit. This lab bridges the foundational governance sequence into an ASP.NET Core API operation. @@ -51,7 +51,7 @@ Scoped authority ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` The primary invariant for the lab is: @@ -247,7 +247,7 @@ GovernedApiLab/ │ ├── DisableAccountPolicy.cs │ ├── AcknowledgmentChallenge.cs │ ├── ExecutionCapability.cs -│ └── GovernanceResidue.cs +│ └── DecisionReceipt.cs ├── Accounts/ │ ├── Account.cs │ ├── IAccountRepository.cs @@ -943,7 +943,7 @@ The acknowledgment is not the account service. ## Part 11 — Record Decision and Execution as Different Evidence -Create a small residue model or recording sink for the exercise. +Create a small receipt model or recording sink for the exercise. You need to distinguish at least: @@ -959,7 +959,7 @@ execution-blocked A small event shape might include: ```csharp -public sealed record GovernanceResidue( +public sealed record DecisionReceipt( string EventId, string CorrelationId, string ActorId, @@ -1006,9 +1006,9 @@ Add a test in which the recording account service throws after incrementing its The test should confirm: ```text -Decision residue outcome = Allowed +Decision receipt outcome = Allowed Account service calls = 1 -Execution residue outcome = Failed +Execution receipt outcome = Failed ``` If your application has centralized exception handling, the HTTP result may become a safe `500` Problem Details response. @@ -1160,7 +1160,7 @@ Governance decision ↓ Host-owned account service ↓ - Execution residue + Execution receipt ``` Answer these questions: @@ -1256,12 +1256,12 @@ A useful architecture makes the intermediate boundaries observable and testable - [Decision Before Execution](../tutorials/decision-before-execution.md) — revisit the boundary between proposed intent, governance decision, and side effect. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — review authoritative decision-time facts, explicit outcomes, and reason codes. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — review bound acknowledgment, re-evaluation, correlation, and separate decision/execution evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — review bound acknowledgment, re-evaluation, correlation, and separate decision/execution evidence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — review narrow authority and execution-boundary validation. - [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) — compare the governed flow with the simpler authorization-only architecture and the hybrid pattern. - [Centralized Error Handling and Problem Details](../aspnetcore/centralized-error-handling-and-problem-details.md) — optionally reuse the repository's safe host-side response convention for expected governance mapping and unexpected failures. - [ASP.NET Core learning area](../aspnetcore/index.md) — connect the exercise to middleware, configuration, logging, and error-handling architecture. -- [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) — inspect fuller governance decision, audit-residue, capability, and host-integration concepts after completing the teaching exercise. +- [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) — inspect fuller governance decision, decision-receipt, capability, and host-integration concepts after completing the teaching exercise. - [AsiBackbone/NetCoreApplicationTemplate](https://github.com/AsiBackbone/NetCoreApplicationTemplate) — compare the disposable lab with a broader ASP.NET Core reference architecture. --- diff --git a/docs/labs/compare-competing-policy-architectures.md b/docs/labs/compare-competing-policy-architectures.md index fc4c94c..3786094 100644 --- a/docs/labs/compare-competing-policy-architectures.md +++ b/docs/labs/compare-competing-policy-architectures.md @@ -215,7 +215,7 @@ Scoped execution authority when needed ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` Natural strengths include: @@ -455,7 +455,7 @@ Treat these as facts: 8. Policy changes may ship with the application. 9. The team wants to minimize new infrastructure and keep debugging local. 10. A policy failure in Harbor Admin must not become a shared dependency outage for unrelated applications; no shared policy runtime exists today. -11. Current compliance needs are satisfied by normal security and operational logs. If you introduce a separate durable governance receipt, justify the reconstruction question that requires it. +11. Current compliance needs are satisfied by normal security and operational logs. If you introduce a separate durable decision receipt, justify the reconstruction question that requires it. ### Your Task diff --git a/docs/labs/critique-ai-owned-proposal-and-execution-authority.md b/docs/labs/critique-ai-owned-proposal-and-execution-authority.md index 8b1c175..2c0033d 100644 --- a/docs/labs/critique-ai-owned-proposal-and-execution-authority.md +++ b/docs/labs/critique-ai-owned-proposal-and-execution-authority.md @@ -1196,7 +1196,7 @@ Classify each control. | Scoped authority | | | | | | Replay protection | | | | | | Retry budget | | | | | -| Audit residue | | | | | +| Decision receipt | | | | | Many controls legitimately span more than one category. diff --git a/docs/labs/decision-before-execution.md b/docs/labs/decision-before-execution.md index 6eae1c3..530df89 100644 --- a/docs/labs/decision-before-execution.md +++ b/docs/labs/decision-before-execution.md @@ -346,10 +346,10 @@ Use `git status` before restoring anything so that you understand which local ch - [Decision Before Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-before-execution/README.md) — return to the known executable baseline. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — continue into richer policy facts and structured outcomes. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) - compare your lab behavior with fuller evaluator tests. -- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) - follow the complete documented lifecycle from proposal toward execution. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) - examine the fuller execution-authority boundary. -- [`AsiBackboneEndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Endpoints/AsiBackboneEndpointGovernanceMiddleware.cs) - inspect a concrete ASP.NET Core enforcement layer. +- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) - compare your lab behavior with fuller evaluator tests. +- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) - follow the complete documented lifecycle from proposal toward execution. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) - examine the fuller execution-authority boundary. +- [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) - inspect a concrete ASP.NET Core enforcement layer. --- diff --git a/docs/labs/acknowledgment-and-audit-residue.md b/docs/labs/decision-receipts-and-acknowledgment.md similarity index 83% rename from docs/labs/acknowledgment-and-audit-residue.md rename to docs/labs/decision-receipts-and-acknowledgment.md index ceb6c77..8c6dd89 100644 --- a/docs/labs/acknowledgment-and-audit-residue.md +++ b/docs/labs/decision-receipts-and-acknowledgment.md @@ -2,17 +2,17 @@ description: Practice acknowledgment as a narrowly bound governance event, re-evaluate policy afterward, and preserve correlated evidence across decisions and execution. --- -# Lab — Acknowledgment and Audit Residue +# Lab — Decision Receipts and Acknowledgment **Learning objective:** Practice treating acknowledgment as a narrowly bound governance event rather than permission, preserving re-evaluation after acknowledgment, and maintaining a correlated audit timeline that distinguishes decisions, acknowledgments, and execution outcomes. **Difficulty:** Intermediate -**Prerequisites:** Complete the [Acknowledgment and Audit Residue tutorial](../tutorials/acknowledgment-and-audit-residue.md) and run the [Acknowledgment and Audit Residue sample](https://github.com/AsiBackbone/Learning/blob/main/samples/acknowledgment-and-audit-residue/README.md). +**Prerequisites:** Complete the [Decision Receipts and Acknowledgment tutorial](../tutorials/decision-receipts-and-acknowledgment.md) and run the [Decision Receipts and Acknowledgment sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md). This lab builds directly on the third foundational tutorial and its executable companion sample. -The tutorial explains the acknowledgment boundary and the purpose of structured audit residue. +The tutorial explains the acknowledgment boundary and the purpose of structured decision receipt. The sample demonstrates five deterministic workflows, including rejected, mismatched, expired, successful, and context-drift paths. @@ -45,7 +45,7 @@ Policy re-evaluated ↓ Host-owned execution or stop ↓ -Audit residue +Decision receipt ``` The important invariants are: @@ -85,13 +85,13 @@ Work on a temporary branch or disposable copy of the repository so you can modif For example: ```bash -git switch -c lab/acknowledgment-audit-residue +git switch -c lab/acknowledgment-decision-receipt ``` From the repository root, run the companion sample before making changes: ```bash -dotnet run --project samples/acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj +dotnet run --project samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj ``` Before continuing, locate these elements in `Program.cs`: @@ -102,9 +102,9 @@ Before continuing, locate these elements in `Program.cs`: 4. `AcknowledgmentValidator` 5. `DisableAccountPolicyContext` 6. `DisableAccountPolicy` -7. `AuditResidue` -8. `AddDecisionResidue` -9. `AddResidue` +7. `DecisionReceipt` +8. `AddDecisionReceipt` +9. `AddReceipt` 10. `RecordingExecutor` 11. `WorkflowScenario` 12. `VerifyScenario` @@ -286,9 +286,9 @@ You do not need a database for this lab. The objective is to identify where pers --- -## Part 4 — Preserve Audit Residue Behind a Store Boundary +## Part 4 — Preserve Decision Receipt Behind a Store Boundary -The sample currently builds a local `List` inside each workflow. +The sample currently builds a local `List` inside each workflow. Decision-derived events reference a separate `DecisionReceipt`. That makes the lifecycle easy to observe, but the list disappears with the process. @@ -297,18 +297,22 @@ Introduce a small evidence-store abstraction. For example: ```csharp -public interface IAuditResidueStore +public interface IGovernanceEvidenceStore { - void Append(AuditResidue residue); + void Append(DecisionReceipt receipt); + void Append(DecisionReceiptLifecycleEvent lifecycleEvent); - IReadOnlyList ReadByCorrelationId( + IReadOnlyList ReadReceiptsByCorrelationId( + string correlationId); + + IReadOnlyList ReadLifecycleByCorrelationId( string correlationId); } ``` Implement it in memory for the lab. -Refactor the sample so every residue is appended through the store rather than existing only as a local implementation detail. +Refactor the sample so every decision receipt and lifecycle event is appended through the store rather than existing only as a local implementation detail. Preserve these properties: @@ -345,7 +349,7 @@ For the context-drift scenario, confirm the timeline ends at: re-evaluation ``` -and contains no `execution-completed` residue. +and contains no `execution-completed` lifecycle event. ### Do Not Overclaim the Store @@ -402,7 +406,7 @@ and: Execution outcome = Failed ``` -Add a final residue such as: +Add a final lifecycle event such as: ```text Stage: execution-failed @@ -490,7 +494,7 @@ A single mutable `PolicyVersion` field may no longer be enough if those identiti ## Part 7 — Review the Evidence Surface -Inspect the final `AuditResidue` model and your in-memory store. +Inspect the final `DecisionReceipt` and `GovernanceLifecycleEvent` models and your in-memory store. For each field, classify it as one of: @@ -503,7 +507,7 @@ Policy provenance Operational detail ``` -Then identify information that should **not** be copied into residue merely because it is available. +Then identify information that should **not** be copied into a receipt or lifecycle event merely because it is available. Examples include: @@ -534,7 +538,7 @@ Run the modified sample and confirm all of the following: - Wrong correlation is rejected with a stable reason code. - Replaying an already consumed acknowledgment is blocked while consumption state exists. - Recreating the in-memory consumption store demonstrates why durable replay protection is a separate concern. -- Audit residue is appended through an explicit store boundary. +- Decision receipts and lifecycle events are appended through an explicit store boundary. - Stored records can be read back by correlation identifier in lifecycle order. - A failed executor produces `execution-failed` evidence without changing the earlier policy decision into a denial. - Policy identity drift is handled according to a documented rule. @@ -585,7 +589,7 @@ Host-owned execution attempt ↓ Distinct execution result ↓ -Correlated audit residue +Correlated decision receipt ``` You should also be able to explain why each of these statements is different: @@ -606,7 +610,7 @@ Create three separate in-memory stores: ```text Challenge store Consumption store -Audit residue store +Decision receipt store ``` Run a workflow through challenge issuance, then construct new workflow objects while selectively preserving or replacing each store. @@ -633,7 +637,7 @@ git diff To restore the companion sample: ```bash -git restore samples/acknowledgment-and-audit-residue/Sample/Program.cs +git restore samples/decision-receipts-and-acknowledgment/Sample/Program.cs ``` Use `git status` first so you understand which local work will be affected. @@ -642,16 +646,16 @@ Use `git status` first so you understand which local work will be affected. ### Related Content -- [Acknowledgment and Audit Residue tutorial](../tutorials/acknowledgment-and-audit-residue.md) — review the architectural reasoning behind the lab. -- [Acknowledgment and Audit Residue sample](https://github.com/AsiBackbone/Learning/blob/main/samples/acknowledgment-and-audit-residue/README.md) — return to the executable baseline used by this exercise. +- [Decision Receipts and Acknowledgment tutorial](../tutorials/decision-receipts-and-acknowledgment.md) — review the architectural reasoning behind the lab. +- [Decision Receipts and Acknowledgment sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md) — return to the executable baseline used by this exercise. - [Policy Context and Explicit Decision Outcomes lab](policy-context-and-explicit-decision-outcomes.md) — revisit explicit decision inputs, reason codes, and precedence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — continue from acknowledged governance requirements into narrow execution authority. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — compare the teaching challenge with the fuller framework handshake request. -- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the working accepted/rejected acknowledgment model. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — compare the lab's small evidence model with the framework's richer governance residue. -- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) — review the fuller handshake lifecycle. -- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) — study production-oriented durability and delivery concerns after completing the in-memory exercise. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — compare the teaching challenge with the fuller framework handshake request. +- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the working accepted/rejected acknowledgment model. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — compare the lab's small evidence model with the framework's richer decision receipt. +- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) — review the fuller handshake lifecycle. +- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) — study production-oriented durability and delivery concerns after completing the in-memory exercise. --- diff --git a/docs/labs/governed-ai-tool-gateway.md b/docs/labs/governed-ai-tool-gateway.md index 91fac31..f028794 100644 --- a/docs/labs/governed-ai-tool-gateway.md +++ b/docs/labs/governed-ai-tool-gateway.md @@ -10,7 +10,7 @@ description: Practice governing AI-proposed tool actions while preserving host-o **Prerequisites:** Complete the [Governed AI Tool Gateway tutorial](../tutorials/governed-ai-tool-gateway.md), run the [Governed AI Tool Gateway sample](https://github.com/AsiBackbone/Learning/blob/main/samples/governed-ai-tool-gateway/README.md), and be comfortable with the first four foundational patterns. -This is the capstone lab for the foundational ASI Backbone Learning path. +This is the capstone lab for the foundational AsiBackbone Learning path. The baseline sample uses a simulated proposal generator and a dry-run `notification.send` handler. @@ -51,7 +51,7 @@ Single-use consumption ↓ Host-owned dry-run handler ↓ -Audit residue +Decision receipt ``` Important baseline invariants include: @@ -781,7 +781,7 @@ A useful comparison might be: | Scoped capability | Usually unnecessary | Useful for consequential action | | Replay state | Usually unnecessary | Potentially important | | External credential | None | Host-owned | -| Audit residue | Lightweight | Potentially important | +| Decision receipt | Lightweight | Potentially important | The objective is to avoid turning governance into ceremony detached from consequence. @@ -949,10 +949,10 @@ git restore samples/governed-ai-tool-gateway - [Scoped Capability and Host-Owned Execution lab](scoped-capability-and-host-owned-execution.md) — revisit capability binding, expiration, stale authority, and replay concepts in isolation. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — distinguish capability replay protection from request idempotency, external retry semantics, and exactly-once execution claims. - [Safe Degraded Mode and Fail-Safe Governance](safe-degraded-mode-and-fail-safe-governance.md) — continue from the gateway's single fail-open exercise into explicit policy, replay, verification, acknowledgment, evidence, and executor failure behavior. -- [Acknowledgment and Audit Residue lab](acknowledgment-and-audit-residue.md) — revisit responsibility and evidence boundaries before they are composed into AI tool execution. -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — compare the teaching gateway with the working framework's scenario documentation. -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — compare acknowledgment handling with the implementation-oriented guidance. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — examine production-oriented proof, replay, time, binding, and failure considerations. +- [Decision Receipts and Acknowledgment lab](decision-receipts-and-acknowledgment.md) — revisit responsibility and evidence boundaries before they are composed into AI tool execution. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — compare the teaching gateway with the working framework's scenario documentation. +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — compare acknowledgment handling with the implementation-oriented guidance. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — examine production-oriented proof, replay, time, binding, and failure considerations. - [Foundational Tutorial Index](../tutorials/index.md) — revisit the complete five-tutorial sequence. --- diff --git a/docs/labs/hidden-execution-side-effect.md b/docs/labs/hidden-execution-side-effect.md index 88fd58c..a85ab63 100644 --- a/docs/labs/hidden-execution-side-effect.md +++ b/docs/labs/hidden-execution-side-effect.md @@ -507,7 +507,7 @@ Performs consequential operation Operational logging and metrics are also technically side effects, but they are not the same thing as executing the governed business operation. They should still be designed deliberately, especially when they can leak sensitive data or trigger downstream automation. -Audit residue is another distinct concern. Recording that a decision occurred should not silently become the requested external operation itself. +Decision receipt is another distinct concern. Recording that a decision occurred should not silently become the requested external operation itself. The invariant in this beginner lab is intentionally narrower and easier to observe: @@ -574,9 +574,9 @@ Then answer: - [Decision Before Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-before-execution/README.md) — compare the corrected sample flow with the flawed starter code in this exercise. - [Decision Before Execution lab](decision-before-execution.md) — practice deliberately breaking and repairing the host execution guard. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — continue into richer context and non-boolean outcomes. -- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — inspect the fuller lifecycle from proposal through execution. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) — compare the teaching boundary with the fuller implementation guidance. -- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) — inspect tests that make policy/execution behavior observable in the implementation repository. +- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — inspect the fuller lifecycle from proposal through execution. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) — compare the teaching boundary with the fuller implementation guidance. +- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) — inspect tests that make policy/execution behavior observable in the implementation repository. --- diff --git a/docs/labs/index.md b/docs/labs/index.md index 79aab45..9b697c9 100644 --- a/docs/labs/index.md +++ b/docs/labs/index.md @@ -1,10 +1,10 @@ --- -description: Browse hands-on ASI Backbone Learning labs for diagnosing, modifying, testing, and explaining architectural and governed-execution boundaries. +description: Browse hands-on AsiBackbone Learning labs for diagnosing, modifying, testing, and explaining architectural and governed-execution boundaries. --- # Labs -Labs are the **practice and reasoning layer** of ASI Backbone Learning. +Labs are the **practice and reasoning layer** of AsiBackbone Learning. Tutorials explain architectural boundaries. @@ -113,9 +113,9 @@ Related material: - [Middleware Ordering Changes Behavior sample](https://github.com/AsiBackbone/Learning/blob/main/samples/middleware-ordering-changes-behavior/README.md) - [ASP.NET Core learning area](../aspnetcore/index.md) -### Acknowledgment and Audit Residue +### Decision Receipts and Acknowledgment -[Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) +[Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) **Difficulty:** Intermediate @@ -123,8 +123,8 @@ Break the acknowledgment boundary deliberately, add another response-binding fai Related material: -- [Acknowledgment and Audit Residue tutorial](../tutorials/acknowledgment-and-audit-residue.md) -- [Acknowledgment and Audit Residue sample](https://github.com/AsiBackbone/Learning/blob/main/samples/acknowledgment-and-audit-residue/README.md) +- [Decision Receipts and Acknowledgment tutorial](../tutorials/decision-receipts-and-acknowledgment.md) +- [Decision Receipts and Acknowledgment sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md) ### Scoped Capability and Host-Owned Execution @@ -164,7 +164,7 @@ Preserve the policy identity that produced a decision, detect policy drift acros Related material: - [Policy Context and Explicit Decision Outcomes sample](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/README.md) -- [Acknowledgment and Audit Residue lab](acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment lab](decision-receipts-and-acknowledgment.md) - [Scoped Capability and Host-Owned Execution lab](scoped-capability-and-host-owned-execution.md) ### Policy Simulation and Change-Impact Analysis @@ -188,13 +188,13 @@ Related material: **Difficulty:** Intermediate -Extend an authorized ASP.NET Core account-disable endpoint into a governed operation with explicit intent, authoritative context, structured outcomes, acknowledgment, scoped authority, host-owned execution, audit residue, and integration tests that prove blocked paths never invoke the underlying account service. +Extend an authorized ASP.NET Core account-disable endpoint into a governed operation with explicit intent, authoritative context, structured outcomes, acknowledgment, scoped authority, host-owned execution, decision receipt, and integration tests that prove blocked paths never invoke the underlying account service. Related material: - [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) - [ASP.NET Core learning area](../aspnetcore/index.md) @@ -329,7 +329,7 @@ Topics include: * Decision before execution * Explicit policy context and decision outcomes -* Acknowledgment and audit residue +* Acknowledgment and decision receipt * Scoped capability and host-owned execution * Governed AI tool gateways @@ -351,7 +351,7 @@ After working through a teaching example or lab, compare the smaller architectur [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) -A .NET governance and policy-control framework providing fuller implementations of policy evaluation, structured decisions, acknowledgment workflows, audit residue, scoped capability, and host-owned execution. +A .NET governance and policy-control framework providing fuller implementations of policy evaluation, structured decisions, acknowledgment workflows, decision receipt, scoped capability, and host-owned execution. ## NetCoreApplicationTemplate diff --git a/docs/labs/policy-context-and-explicit-decision-outcomes.md b/docs/labs/policy-context-and-explicit-decision-outcomes.md index 4241bb7..e7f0475 100644 --- a/docs/labs/policy-context-and-explicit-decision-outcomes.md +++ b/docs/labs/policy-context-and-explicit-decision-outcomes.md @@ -440,7 +440,7 @@ Discuss: - Why is a version or hash useful for later audit interpretation? - What additional evidence would a production system need before claiming that a decision is fully reproducible? -This prepares for the next tutorial, where acknowledgment and audit residue become first-class concerns. +This prepares for the next tutorial, where acknowledgment and decision receipt become first-class concerns. ### Resetting the Sample @@ -461,12 +461,12 @@ Use `git status` before restoring anything so that you understand which local ch - [Policy Context and Explicit Decision Outcomes tutorial](../tutorials/policy-context-and-explicit-decision-outcomes.md) — review the architectural reasoning behind the lab. - [Policy Context and Explicit Decision Outcomes sample](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/README.md) — return to the executable baseline used by this exercise. - [Decision Before Execution lab](decision-before-execution.md) — practice the earlier boundary between decision and host-owned execution. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — continue from structured outcomes into acknowledgment, lineage, and governance evidence. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — continue from structured outcomes into acknowledgment, lineage, and governance evidence. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) — compare the teaching vocabulary with the working framework. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the fuller decision model and reason metadata. -- [`IAsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IAsiBackboneConstraintEvaluationContext.cs) — compare the explicit teaching snapshot with the framework context surface. -- [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) — inspect fuller constraint evaluation and decision composition. +- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) — compare the teaching vocabulary with the working framework. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the fuller decision model and reason metadata. +- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — compare the explicit teaching snapshot with the framework context surface. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — inspect fuller constraint evaluation and decision composition. --- diff --git a/docs/labs/policy-simulation-and-change-impact-analysis.md b/docs/labs/policy-simulation-and-change-impact-analysis.md index 56e740a..a50105a 100644 --- a/docs/labs/policy-simulation-and-change-impact-analysis.md +++ b/docs/labs/policy-simulation-and-change-impact-analysis.md @@ -1389,12 +1389,12 @@ This lab is framework-neutral. | Learning concern | Reference | What to inspect | | --- | --- | --- | -| Policy evaluation | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | A concrete evaluation pipeline that returns governance decisions without performing host side effects. | -| Structured decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity that can participate in comparison evidence. | -| Host-specific decision policy | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | A boundary where candidate host/domain decision behavior can be evaluated separately from execution. | -| Policy pipeline explanation | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) | Evaluation and composition boundaries useful when designing replayable policy inputs. | -| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Examples of host policy variations that could be compared in a simulation corpus. | -| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why evaluating an allowed result does not require or imply performing the protected action. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | A concrete evaluation pipeline that returns governance decisions without performing host side effects. | +| Structured decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity that can participate in comparison evidence. | +| Host-specific decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A boundary where candidate host/domain decision behavior can be evaluated separately from execution. | +| Policy pipeline explanation | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) | Evaluation and composition boundaries useful when designing replayable policy inputs. | +| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Examples of host policy variations that could be compared in a simulation corpus. | +| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why evaluating an allowed result does not require or imply performing the protected action. | Learning does not require a particular simulation service, policy-management product, event store, data warehouse, or deployment controller. diff --git a/docs/labs/policy-version-evidence-in-governance-decisions.md b/docs/labs/policy-version-evidence-in-governance-decisions.md index d4d74d0..5c1944e 100644 --- a/docs/labs/policy-version-evidence-in-governance-decisions.md +++ b/docs/labs/policy-version-evidence-in-governance-decisions.md @@ -245,7 +245,7 @@ PolicyId = account-disable PolicyVersion = 2.0 ``` -Also preserve the sample's correlation identifier so that later audit residue can connect the decision to the same governed workflow. +Also preserve the sample's correlation identifier so that later decision receipt can connect the decision to the same governed workflow. At this point, the record should be able to answer: @@ -469,14 +469,14 @@ This distinction matters when policy can change faster than the capability lifet --- -## Part 6 — Correlate Policy Evidence with Audit Residue +## Part 6 — Correlate Policy Evidence with Decision Receipt Create a small audit record for the changed-policy execution attempt. One possible shape is: ```csharp -public sealed record PolicyEvidenceResidue( +public sealed record PolicyEvidenceReceipt( string EventId, string CorrelationId, string DecisionId, @@ -604,7 +604,7 @@ It is easy to react to audit requirements by copying everything into every decis Do not do that by default. -Review your final `DecisionRecord` and `PolicyEvidenceResidue` models. +Review your final `DecisionRecord` and `PolicyEvidenceReceipt` models. For each field, ask whether it is required for: @@ -656,7 +656,7 @@ Run the modified sample and confirm all of the following: - Acknowledgment remains bound to the decision and policy evidence that produced the challenge. - Policy changes after acknowledgment do not turn acknowledgment into a policy override. - Capability authority remains connected to the decision evidence that justified issuance. -- Audit residue can distinguish decision-time policy from current execution-time policy. +- Decision receipt can distinguish decision-time policy from current execution-time policy. - A fingerprint, if added, is described as a digest of a chosen representation rather than as cryptographic proof of authorship or tamper evidence. - Decision records avoid unnecessary secrets and unrelated personal data. @@ -781,8 +781,8 @@ Use `git status` first so you understand which local work will be affected. - [Policy Versioning and Decision Provenance tutorial](../governance/policy-versioning-and-decision-provenance.md) — review the conceptual model this lab puts into practice, including stable policy identity, drift, freshness, fingerprints, and evidence boundaries. - [Policy Context and Explicit Decision Outcomes tutorial](../tutorials/policy-context-and-explicit-decision-outcomes.md) — review explicit decision inputs, outputs, reason codes, and policy identity. - [Policy Context and Explicit Decision Outcomes sample](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/README.md) — use the intentionally small executable baseline for this lab. -- [Acknowledgment and Audit Residue tutorial](../tutorials/acknowledgment-and-audit-residue.md) — review acknowledgment binding, re-evaluation, correlation, and durable governance evidence. -- [Acknowledgment and Audit Residue lab](acknowledgment-and-audit-residue.md) — compare the broader lifecycle exercise, including policy-identity drift after acknowledgment. +- [Decision Receipts and Acknowledgment tutorial](../tutorials/decision-receipts-and-acknowledgment.md) — review acknowledgment binding, re-evaluation, correlation, and durable governance evidence. +- [Decision Receipts and Acknowledgment lab](decision-receipts-and-acknowledgment.md) — compare the broader lifecycle exercise, including policy-identity drift after acknowledgment. - [Scoped Capability and Host-Owned Execution tutorial](../tutorials/scoped-capability-and-host-owned-execution.md) — continue into short-lived, narrowly bound execution authority and execution-boundary validation. - [Scoped Capability and Host-Owned Execution lab](scoped-capability-and-host-owned-execution.md) — practice stale authority, resource freshness, expiration, and replay boundaries. - [AsiBackbone/AsiBackbone](https://github.com/AsiBackbone/AsiBackbone) — inspect the fuller governance implementation after working through the teaching model. diff --git a/docs/labs/replay-protection-and-bounded-use.md b/docs/labs/replay-protection-and-bounded-use.md index 0b4ffa7..2851468 100644 --- a/docs/labs/replay-protection-and-bounded-use.md +++ b/docs/labs/replay-protection-and-bounded-use.md @@ -712,9 +712,9 @@ Use `git status` first so you understand which local work will be affected. - [Scoped Capability and Host-Owned Execution lab](scoped-capability-and-host-owned-execution.md) — revisit the broader capability boundary and its introductory single-use exercise. - [Data Access Boundaries and Transaction Reasoning](../aspnetcore/data-access-boundaries-and-transaction-reasoning.md) — bridge `TryConsumeAsync` semantics into durable transaction and persistence design. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — see bounded authority inside a larger AI-assisted execution boundary. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab contract with the working framework seam. -- [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — inspect the working local reference provider and its limitations. -- [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) — compare local concurrency invariant coverage. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab contract with the working framework seam. +- [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — inspect the working local reference provider and its limitations. +- [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) — compare local concurrency invariant coverage. --- diff --git a/docs/labs/safe-degraded-mode-and-fail-safe-governance.md b/docs/labs/safe-degraded-mode-and-fail-safe-governance.md index 550909f..b670fd5 100644 --- a/docs/labs/safe-degraded-mode-and-fail-safe-governance.md +++ b/docs/labs/safe-degraded-mode-and-fail-safe-governance.md @@ -8,7 +8,7 @@ description: Practice fail-safe governance when policy, replay, acknowledgment, **Difficulty:** Advanced -**Prerequisites:** Complete [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md). Run the [Governed AI Tool Gateway sample](https://github.com/AsiBackbone/Learning/blob/main/samples/governed-ai-tool-gateway/README.md) before beginning. [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md), [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md), [Centralized Error Handling and Problem Details](../aspnetcore/centralized-error-handling-and-problem-details.md), [Data Access Boundaries and Transaction Reasoning](../aspnetcore/data-access-boundaries-and-transaction-reasoning.md), and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) provide the deeper failure-model context used throughout the exercise. +**Prerequisites:** Complete [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md), [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md), [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md), and [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md). Run the [Governed AI Tool Gateway sample](https://github.com/AsiBackbone/Learning/blob/main/samples/governed-ai-tool-gateway/README.md) before beginning. [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md), [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md), [Centralized Error Handling and Problem Details](../aspnetcore/centralized-error-handling-and-problem-details.md), [Data Access Boundaries and Transaction Reasoning](../aspnetcore/data-access-boundaries-and-transaction-reasoning.md), and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) provide the deeper failure-model context used throughout the exercise. This lab extends the failure exercise already present in the Governed AI Tool Gateway lab. @@ -65,7 +65,7 @@ Replay/use-state check ↓ Host-owned dry-run executor ↓ -Audit residue +Decision receipt ``` The sample already demonstrates a useful rule: @@ -1236,7 +1236,7 @@ If you added temporary files under the sample directory, remove only the files y - [Governed AI Tool Gateway advanced lab](governed-ai-tool-gateway.md) — begin with the broader composed gateway threat model before specializing in failure policy. - [Governed AI Tool Gateway sample](https://github.com/AsiBackbone/Learning/blob/main/samples/governed-ai-tool-gateway/README.md) — use the existing deterministic host-owned execution boundary as the main lab surface. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — preserve `Deferred`, `AcknowledgmentRequired`, and `EscalationRecommended` instead of collapsing failure behavior into a boolean. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — distinguish responsibility evidence from authorization and execution. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — distinguish responsibility evidence from authorization and execution. - [Trust Boundaries and Least Privilege](../security/trust-boundaries-and-least-privilege.md) — identify which component owns each trust property before choosing degraded behavior. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — reason about replay-store unavailability, atomic consumption, and failure windows. - [Signing, Verification, Key Custody, and Tamper Evidence](../security/signing-verification-key-custody-and-tamper-evidence.md) — distinguish cryptographic verification from current authority and safe execution. diff --git a/docs/labs/scoped-capability-and-host-owned-execution.md b/docs/labs/scoped-capability-and-host-owned-execution.md index 008d4d5..eb0fdc2 100644 --- a/docs/labs/scoped-capability-and-host-owned-execution.md +++ b/docs/labs/scoped-capability-and-host-owned-execution.md @@ -534,14 +534,14 @@ Use `git status` first so you understand which local work will be affected. - [Scoped Capability and Host-Owned Execution tutorial](../tutorials/scoped-capability-and-host-owned-execution.md) — review the architectural reasoning behind the lab. - [Scoped Capability and Host-Owned Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/README.md#scoped-capability-and-host-owned-execution) — return to the executable baseline used by the exercise. -- [Acknowledgment and Audit Residue lab](acknowledgment-and-audit-residue.md) — revisit acknowledgment, re-evaluation, and evidence before execution authority is issued. +- [Decision Receipts and Acknowledgment lab](decision-receipts-and-acknowledgment.md) — revisit acknowledgment, re-evaluation, and evidence before execution authority is issued. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — continue into the end-to-end composition where AI may propose and the host retains execution authority. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — connect this lab's in-memory single-use exercise to durable, atomic, multi-instance replay protection and idempotency boundaries. - [Replay Protection and Bounded-Use Authority lab](replay-protection-and-bounded-use.md) — continue from the introductory single-use exercise into a dedicated concurrency race, atomic consume repair, bounded-use contention, and failure-window analysis. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — compare the teaching capability with the working framework model. -- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — inspect fuller execution-boundary validation. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab's in-memory replay exercise with the provider-neutral production seam. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — review proof, binding, replay, time, and failure-handling guidance. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — compare the teaching capability with the working framework model. +- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — inspect fuller execution-boundary validation. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab's in-memory replay exercise with the provider-neutral production seam. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — review proof, binding, replay, time, and failure-handling guidance. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. --- diff --git a/docs/labs/toc.yml b/docs/labs/toc.yml index 8d3c424..3c2a79d 100644 --- a/docs/labs/toc.yml +++ b/docs/labs/toc.yml @@ -17,8 +17,8 @@ - name: Intermediate Labs expanded: true items: - - name: Acknowledgment and Audit Residue - href: acknowledgment-and-audit-residue.md + - name: Decision Receipts and Acknowledgment + href: decision-receipts-and-acknowledgment.md - name: Scoped Capability and Host-Owned Execution href: scoped-capability-and-host-owned-execution.md - name: Replay Protection and Bounded-Use Authority diff --git a/docs/samples/index.md b/docs/samples/index.md index ee532fd..c029969 100644 --- a/docs/samples/index.md +++ b/docs/samples/index.md @@ -1,11 +1,11 @@ --- -description: Browse runnable companion samples that demonstrate ASI Backbone Learning patterns between the problem-first tutorials and hands-on architectural labs. +description: Browse runnable companion samples that demonstrate AsiBackbone Learning patterns between the problem-first tutorials and hands-on architectural labs. _disableBreadcrumb: true --- # Executable Samples -Executable samples are the **runnable demonstration layer** of ASI Backbone Learning. +Executable samples are the **runnable demonstration layer** of AsiBackbone Learning. They sit between the problem-first tutorials and the hands-on labs: @@ -29,7 +29,7 @@ All executable sample projects currently under `samples/` are listed below, grou | --- | --- | --- | | Foundational | [Decision Before Execution](#decision-before-execution) | A blocked decision never reaches the executor. | | Foundational | [Policy Context and Explicit Decision Outcomes](#policy-context-and-explicit-decision-outcomes) | Policy consumes explicit facts and returns a structured outcome without performing the side effect. | -| Foundational | [Acknowledgment and Audit Residue](#acknowledgment-and-audit-residue) | Acknowledgment satisfies a governance requirement; it does not become execution authority. | +| Foundational | [Decision Receipts and Acknowledgment](#decision-receipts-and-acknowledgment) | Acknowledgment satisfies a governance requirement; it does not become execution authority. | | Foundational | [Scoped Capability and Host-Owned Execution](#scoped-capability-and-host-owned-execution) | Narrow authority is validated again at the host-owned execution boundary. | | Foundational | [Governed AI Tool Gateway](#governed-ai-tool-gateway) | The model may propose; the host retains execution authority. | | Governance and Policy Architecture | [Decision Pipeline Refactoring](#decision-pipeline-refactoring) | Explicit outcomes remain separate from protected execution. | @@ -88,7 +88,7 @@ dotnet run --project samples/policy-context-and-explicit-decision-outcomes/Sampl - [Read the tutorial](../tutorials/policy-context-and-explicit-decision-outcomes.md) - [Continue with the learner exercise](../labs/policy-context-and-explicit-decision-outcomes.md) -### Acknowledgment and Audit Residue +### 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. @@ -103,12 +103,12 @@ Decision, acknowledgment, re-evaluation, and execution remain distinguishable ev Run from the repository root: ```bash -dotnet run --project samples/acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj +dotnet run --project samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj ``` -- [Open the canonical sample README](https://github.com/AsiBackbone/Learning/blob/main/samples/acknowledgment-and-audit-residue/README.md) -- [Read the tutorial](../tutorials/acknowledgment-and-audit-residue.md) -- [Continue with the intermediate lab](../labs/acknowledgment-and-audit-residue.md) +- [Open the canonical sample README](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md) +- [Read the tutorial](../tutorials/decision-receipts-and-acknowledgment.md) +- [Continue with the intermediate lab](../labs/decision-receipts-and-acknowledgment.md) ### Scoped Capability and Host-Owned Execution @@ -153,7 +153,7 @@ dotnet run --project samples/governed-ai-tool-gateway/Sample/GovernedAiToolGatew - [Trace the governed proposal end to end](../ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md) - [Continue with the advanced lab](../labs/governed-ai-tool-gateway.md) -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 audit residue. It prints allowed, denied, and acknowledgment-required traces without requiring a real AI provider or telemetry backend. +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 diff --git a/docs/samples/toc.yml b/docs/samples/toc.yml index 5d91969..ed188fc 100644 --- a/docs/samples/toc.yml +++ b/docs/samples/toc.yml @@ -8,8 +8,8 @@ href: index.md#decision-before-execution - name: Policy Context and Explicit Decision Outcomes href: index.md#policy-context-and-explicit-decision-outcomes - - name: Acknowledgment and Audit Residue - href: index.md#acknowledgment-and-audit-residue + - name: Decision Receipts and Acknowledgment + href: index.md#decision-receipts-and-acknowledgment - name: Scoped Capability and Host-Owned Execution href: index.md#scoped-capability-and-host-owned-execution - name: Governed AI Tool Gateway diff --git a/docs/security/index.md b/docs/security/index.md index 067713d..0e4f186 100644 --- a/docs/security/index.md +++ b/docs/security/index.md @@ -6,7 +6,7 @@ description: Explore trust boundaries, least privilege, secrets, secure logging, The Security section examines architectural boundaries that can reduce accidental authority, hidden execution paths, unsafe defaults, and ambiguous control flow. -Security in ASI Backbone Learning is approached as an architectural responsibility rather than a single feature or package. +Security in AsiBackbone Learning is approached as an architectural responsibility rather than a single feature or package. > **Section status:** Focused security learning now covers trust boundaries, least privilege, secret handling, secure logging, replay protection, cryptographic evidence boundaries, software supply-chain integrity, and threat modeling as architecture reasoning. Start with [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md), continue with [Secret Handling Across Trust Boundaries](secret-handling-across-trust-boundaries.md) to follow authority-bearing values through custody, delivery, use, rotation, and revocation, then use [Secure Logging Across Trust Boundaries](secure-logging-across-trust-boundaries.md) to examine observability as an outbound data boundary. Continue with [Replay Protection and Bounded-Use Authority](replay-protection-and-bounded-use.md), [Signing, Verification, Key Custody, and Tamper Evidence](signing-verification-key-custody-and-tamper-evidence.md), and [Software Supply-Chain Integrity for .NET Repositories](software-supply-chain-integrity-for-dotnet-repositories.md). Finish with [Threat Modeling as Architecture Reasoning](threat-modeling-as-architecture-reasoning.md) to synthesize those controls into a repeatable architecture-review method before returning to the [Foundational Tutorials](../tutorials/index.md) and governed-execution path. @@ -108,7 +108,7 @@ See: ## Related Foundational Material * [Decision Before Execution](../tutorials/decision-before-execution.md) -* [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) +* [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) * [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) * [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) diff --git a/docs/security/replay-protection-and-bounded-use.md b/docs/security/replay-protection-and-bounded-use.md index 411fd0e..1147a89 100644 --- a/docs/security/replay-protection-and-bounded-use.md +++ b/docs/security/replay-protection-and-bounded-use.md @@ -1214,8 +1214,8 @@ A host-owned gateway can make the state transition explicit: > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to keep the replay-protection discussion independent of the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). ```csharp public sealed class ProtectedOperationGateway( @@ -1382,12 +1382,12 @@ The current `AsiBackbone/AsiBackbone` repository contains a fuller capability-us | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Provider-neutral bounded-use state | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | `TryConsumeAsync` combines checking and consumption; Core explicitly leaves durable state, distributed locking, cache consistency, database schema, and replay-window guarantees to the host/provider. | -| Teaching/local in-memory provider | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe in-process use counts and stopped/cancelled state, with explicit documentation that the provider is non-durable, non-distributed, and not production replay protection. | -| Execution validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Proof checks, metadata/binding checks, then optional use-store consumption; missing or unavailable replay state maps to an explicit non-success validation outcome instead of silent execution. | -| Use-check configuration | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | `RequireUseCheck`, `MaxUseCount`, validation time, scope, policy, binding, and proof options. | -| Broader capability guidance | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Proof, issuer/audience/scope, replay/use limits, cancellation/revocation, time windows, and the host-owned security boundary. | -| Executable use-store behavior | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | In-process accepted use, use-limit, stopped/cancelled, and local concurrency behavior. | +| Provider-neutral bounded-use state | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | `TryConsumeAsync` combines checking and consumption; Core explicitly leaves durable state, distributed locking, cache consistency, database schema, and replay-window guarantees to the host/provider. | +| Teaching/local in-memory provider | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe in-process use counts and stopped/cancelled state, with explicit documentation that the provider is non-durable, non-distributed, and not production replay protection. | +| Execution validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Proof checks, metadata/binding checks, then optional use-store consumption; missing or unavailable replay state maps to an explicit non-success validation outcome instead of silent execution. | +| Use-check configuration | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | `RequireUseCheck`, `MaxUseCount`, validation time, scope, policy, binding, and proof options. | +| Broader capability guidance | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Proof, issuer/audience/scope, replay/use limits, cancellation/revocation, time windows, and the host-owned security boundary. | +| Executable use-store behavior | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | In-process accepted use, use-limit, stopped/cancelled, and local concurrency behavior. | The implementation repository is a specimen, not a universal storage prescription. @@ -1571,7 +1571,7 @@ Before moving on, you should be able to answer: - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — see single-use capability validation composed around AI-proposed actions. - [Governed AI Tool Gateway sample](https://github.com/AsiBackbone/Learning/blob/main/samples/governed-ai-tool-gateway/README.md) — observe single-use consumption inside the dry-run AI gateway. - [Governed AI Tool Gateway lab](../labs/governed-ai-tool-gateway.md) — break single-use enforcement and threat-model replay versus idempotency. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — preserve evidence across decision, acknowledgment, execution, and failure stages. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — preserve evidence across decision, acknowledgment, execution, and failure stages. - [Signing, Verification, Key Custody, and Tamper Evidence](signing-verification-key-custody-and-tamper-evidence.md) — continue from replay-safe authority into cryptographic authenticity, verifier trust policy, key lifecycle, and tamper-evidence boundaries. --- diff --git a/docs/security/secret-handling-across-trust-boundaries.md b/docs/security/secret-handling-across-trust-boundaries.md index 3323b2b..c11f33f 100644 --- a/docs/security/secret-handling-across-trust-boundaries.md +++ b/docs/security/secret-handling-across-trust-boundaries.md @@ -1961,7 +1961,7 @@ The organization repositories provide useful specimens for specific boundaries w | CI/workflow authority | [Software Supply-Chain Integrity for .NET Repositories](software-supply-chain-integrity-for-dotnet-repositories.md) | Workflow permissions, checkout credentials, OIDC identity, environment secrets, package credentials, cloud credentials, and the separation between validation and publication authority. | | AI host-owned credential boundary | [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) | Why a model proposes an action while the host-owned tool handler keeps infrastructure credentials outside model-visible context. | | Narrow follow-on authority | [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) | Actor, operation, resource, audience, time, and use bindings that provide an architectural analogue for reducing credential authority. | -| Audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | Host responsibility for keeping credentials, tokens, connection strings, prompts, and uncontrolled payloads out of durable governance and telemetry paths. | +| Audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | Host responsibility for keeping credentials, tokens, connection strings, prompts, and uncontrolled payloads out of durable governance and telemetry paths. | Use these as working specimens rather than as a claim that every deployment needs the same secret manager, identity provider, or credential type. @@ -1985,7 +1985,7 @@ For each credential or secret, answer: 12. **Can a short-lived token replace a long-lived distributed secret?** 13. **Can workload identity remove the need to distribute the secret at all?** 14. **Can command-line, URL, environment, debugging, or process inspection reveal it?** -15. **Can it enter logs, traces, metrics, exceptions, audit residue, or public errors?** +15. **Can it enter logs, traces, metrics, exceptions, decision receipt, or public errors?** 16. **Can it enter an AI prompt, conversation, tool argument, evaluation set, or provider trace?** 17. **Which CI jobs can access it?** 18. **Does a validation job receive publication or deployment authority unnecessarily?** diff --git a/docs/security/secure-logging-across-trust-boundaries.md b/docs/security/secure-logging-across-trust-boundaries.md index f7e88b4..baf88d9 100644 --- a/docs/security/secure-logging-across-trust-boundaries.md +++ b/docs/security/secure-logging-across-trust-boundaries.md @@ -8,7 +8,7 @@ description: Treat logging as an outbound trust boundary by minimizing data befo **Difficulty:** Intermediate -**Prerequisites:** [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md) and [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md). [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) is useful when comparing operational telemetry with governance evidence. +**Prerequisites:** [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md) and [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md). [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) is useful when comparing operational telemetry with governance evidence. **Learning objective:** Treat logging as a chain of trust-boundary decisions rather than only an `ILogger` or observability concern. Decide what may leave application memory, minimize and bound event data before emission, validate externally supplied identifiers, review provider/export/storage/access/retention assumptions, preserve tenant separation, define degraded behavior, and distinguish operational logs from evidence-oriented governance records. @@ -1193,7 +1193,7 @@ A useful comparison is: | Schema | Diagnostic event schema | Purpose-built decision/lifecycle schema | | Sensitive-data rule | Minimize | Minimize; evidence is not a data-dumping exception | -See [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) for the evidence-oriented lifecycle. +See [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) for the evidence-oriented lifecycle. The two paths can share a correlation identifier: @@ -1206,7 +1206,7 @@ ElapsedMilliseconds = 12 ↓ Troubleshooting -Governance residue +Decision receipt Outcome = denied ReasonCodes = [resource.protected] PolicyVersion = 4.1 @@ -1556,8 +1556,8 @@ The organization repositories provide fuller specimens where the same boundaries | Minimized structured request logging and correlation | [`RequestLoggingExtensions.cs`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/Extensions/RequestLoggingExtensions.cs) | Request/trace enrichment, excluded paths, status-based levels, and explicit warnings against unreviewed bodies, cookies, authorization headers, tokens, identity payloads, password/form fields, and query strings. | | Provider levels, local file behavior, and bounded retention | [`appsettings.json`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/appsettings.json) | Logging configuration, correlation/trace properties, file rolling, retention, size limits, and request-logging options. Treat concrete settings as one implementation choice rather than universal security defaults. | | Remote tracing/metrics export boundary | [`OpenTelemetryServiceExtensions.cs`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/Extensions/OpenTelemetryServiceExtensions.cs) | Separate instrumentation and optional OTLP export surfaces that make the remote telemetry boundary visible. | -| Governance evidence versus ordinary telemetry | [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) | Distinct decision, acknowledgment, execution, persistence, and operational-logging responsibilities. | -| Audit and telemetry metadata hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | Allowlisted metadata, bounded codes, prompt/body/secret avoidance, provider emission review, retention, access control, and host-owned data-safety responsibility. | +| Governance evidence versus ordinary telemetry | [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) | Distinct decision, acknowledgment, execution, persistence, and operational-logging responsibilities. | +| Audit and telemetry metadata hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | Allowlisted metadata, bounded codes, prompt/body/secret avoidance, provider emission review, retention, access control, and host-owned data-safety responsibility. | | Tamper-evidence boundaries | [Signing, Verification, Key Custody, and Tamper Evidence](signing-verification-key-custody-and-tamper-evidence.md) | Why signing, verification, key custody, and tamper evidence establish narrower properties than confidentiality, authorization, or safe collection. | Use these as specimens, not as proof that every application needs the same provider, collector, storage topology, or governance framework. @@ -1654,7 +1654,7 @@ Before moving on, you should be able to answer: - [Security](index.md) — return to the Security learning-area overview. - [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md) — apply the broader rule that a boundary should change what the system is willing to trust and pass onward. - [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md) — study application-level event design, `ILogger`, stable event identity, correlation, scopes, exception boundaries, log levels, cardinality, and observability roles. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — compare ordinary operational telemetry with evidence-oriented governance records. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — compare ordinary operational telemetry with evidence-oriented governance records. - [Centralized Error Handling and Problem Details](../aspnetcore/centralized-error-handling-and-problem-details.md) — separate public error disclosure from internal diagnostics. - [Signing, Verification, Key Custody, and Tamper Evidence](signing-verification-key-custody-and-tamper-evidence.md) — distinguish cryptographic evidence properties from safe collection and confidentiality. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — apply data and execution boundaries to AI-proposed operations. diff --git a/docs/security/signing-verification-key-custody-and-tamper-evidence.md b/docs/security/signing-verification-key-custody-and-tamper-evidence.md index 6a12e1e..2a80ede 100644 --- a/docs/security/signing-verification-key-custody-and-tamper-evidence.md +++ b/docs/security/signing-verification-key-custody-and-tamper-evidence.md @@ -8,7 +8,7 @@ description: Learn how signatures, verification, key custody, rotation, fingerpr **Difficulty:** Advanced -**Prerequisites:** [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md), [Replay Protection and Bounded-Use Authority](replay-protection-and-bounded-use.md), and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md). Familiarity with [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) is helpful. +**Prerequisites:** [Trust Boundaries and Least Privilege](trust-boundaries-and-least-privilege.md), [Replay Protection and Bounded-Use Authority](replay-protection-and-bounded-use.md), and [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md). Familiarity with [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) and [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) is helpful. **Learning objective:** Distinguish content fingerprints from digital signatures, separate signing from verification and authorization, place signing and verification at explicit trust boundaries, reason about key ownership and rotation, and explain what signed or tamper-evident evidence can and cannot prove. @@ -1576,9 +1576,9 @@ Cryptographic authenticity and replay state are complementary controls. --- -## Audit Residue as Signed Evidence +## Decision Receipt as Signed Evidence -Audit residue can preserve: +Decision receipt can preserve: ```text What decision occurred? @@ -2199,12 +2199,12 @@ The current `AsiBackbone/AsiBackbone` repository provides useful working referen | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Canonical payloads, hashes, signing metadata, and provider-neutral interfaces | [Signing-Ready Receipts and Key Handling](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signing-ready-receipts-and-key-handling.md) | Deterministic canonical payloads, key ID/version metadata, signing seams, and explicit wording limits. | -| Signed is not verified | [Verification Policy and Result Handling](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/verification-policy-and-result-handling.md) | Verification categories, host policy actions, trust-context checks, and failure handling. | -| Rotation and historical verification | [Key Rotation and Retired-Key Verification](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/key-rotation-and-retired-key-verification.md) | Active, retired, revoked, expired, disabled, and unknown key states plus historical verification guidance. | -| Signed governance artifacts | [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signed-audit-and-outbox-records.md) | Signing points for audit and outbox artifacts and the boundary between signed records and tamper-evident trails. | -| Narrow proof authority | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-proof-trust-pinning.md) | Why a cryptographically valid proof can still fail when key, version, provider, algorithm, or policy expectations do not match. | -| Production security wording and non-goals | [Cryptographic Security Posture and Production Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/cryptographic-security-posture.md) | Host responsibilities, provider boundaries, security non-goals, and safe production claims. | +| Canonical payloads, hashes, signing metadata, and provider-neutral interfaces | [Signing-Ready Receipts and Key Handling](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signing-ready-receipts-and-key-handling.md) | Deterministic canonical payloads, key ID/version metadata, signing seams, and explicit wording limits. | +| Signed is not verified | [Verification Policy and Result Handling](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/verification-policy-and-result-handling.md) | Verification categories, host policy actions, trust-context checks, and failure handling. | +| Rotation and historical verification | [Key Rotation and Retired-Key Verification](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/key-rotation-and-retired-key-verification.md) | Active, retired, revoked, expired, disabled, and unknown key states plus historical verification guidance. | +| Signed governance artifacts | [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signed-audit-and-outbox-records.md) | Signing points for audit and outbox artifacts and the boundary between signed records and tamper-evident trails. | +| Narrow proof authority | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-proof-trust-pinning.md) | Why a cryptographically valid proof can still fail when key, version, provider, algorithm, or policy expectations do not match. | +| Production security wording and non-goals | [Cryptographic Security Posture and Production Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/cryptographic-security-posture.md) | Host responsibilities, provider boundaries, security non-goals, and safe production claims. | These references are implementation specimens rather than universal prescriptions. @@ -2222,7 +2222,7 @@ The Learning boundary remains: - [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) — distinguish policy identity and fingerprints from authenticity and tamper-evidence claims. - [Durable Decision Ledgers and Cryptographic Audit Chains](../advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md) — continue from hash/signature primitives into ordered append semantics, protected checkpoints, tail-truncation detection, key lifecycle, archival, migration, restore, and corrupted-chain handling. - [Software Supply-Chain Integrity for .NET Repositories](software-supply-chain-integrity-for-dotnet-repositories.md) — apply provenance, checksum, signing, and verification distinctions to build and release artifacts without treating any one mechanism as proof of artifact safety. -- [Acknowledgment and Audit Residue](../tutorials/acknowledgment-and-audit-residue.md) — connect signatures to durable governance evidence without treating acknowledgment as an execution override. +- [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — connect signatures to durable governance evidence without treating acknowledgment as an execution override. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — apply verification as one execution-boundary check around narrow authority. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — preserve the rule that AI may propose while host-owned code retains verification, policy, and execution authority. diff --git a/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md b/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md index 5f68d94..c9871f8 100644 --- a/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md +++ b/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md @@ -84,7 +84,7 @@ If your starting question is whether a green CI run proves the NuGet package you ## What This Walkthrough Uses as Working Specimens -This article uses three ASI Backbone organization repositories selectively: +This article uses three AsiBackbone organization repositories selectively: - [`AsiBackbone/Learning`](https://github.com/AsiBackbone/Learning) — an educational repository with documentation and sample validation, SHA-pinned workflow dependencies, grouped Dependabot update automation, and repository-maintained CodeQL analysis for C# source. - [`AsiBackbone/AsiBackbone`](https://github.com/AsiBackbone/AsiBackbone) — a package-producing .NET repository with central dependency management, locked restore, release validation, SBOM generation, provenance attestations, and package publication automation. @@ -2083,10 +2083,10 @@ Pinned DocFX tool manifest ### AsiBackbone - [AsiBackbone repository](https://github.com/AsiBackbone/AsiBackbone) -- [AsiBackbone workflow directory](https://github.com/AsiBackbone/AsiBackbone/tree/main/.github/workflows) -- [Directory.Build.props](https://github.com/AsiBackbone/AsiBackbone/blob/main/Directory.Build.props) -- [Directory.Packages.props](https://github.com/AsiBackbone/AsiBackbone/blob/main/Directory.Packages.props) -- [Dependabot configuration](https://github.com/AsiBackbone/AsiBackbone/blob/main/.github/dependabot.yml) +- [AsiBackbone workflow directory](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/.github/workflows) +- [Directory.Build.props](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/Directory.Build.props) +- [Directory.Packages.props](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/Directory.Packages.props) +- [Dependabot configuration](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/.github/dependabot.yml) Inspect it for: diff --git a/docs/security/threat-modeling-as-architecture-reasoning.md b/docs/security/threat-modeling-as-architecture-reasoning.md index ea53422..1a1aa3d 100644 --- a/docs/security/threat-modeling-as-architecture-reasoning.md +++ b/docs/security/threat-modeling-as-architecture-reasoning.md @@ -259,7 +259,7 @@ For governed systems, important assets often include: - Secrets and credentials. - Signing keys. - Replay/use state. -- Audit residue and decision provenance. +- Decision receipt and decision provenance. - Trusted identity or tenant mappings. - Service availability. - Build and release integrity. @@ -272,7 +272,7 @@ For each asset, write the security objective in plain language. | Execution authority | Authority must remain bound to the actor, operation, resource, audience, time, and use count required by the decision. | | Policy configuration | A caller or model must not be able to choose the policy version that governs its own request. | | External API credential | The credential must remain host-owned and should not enter prompts, client payloads, logs, or unrelated components. | -| Audit residue | Records should be useful for reconstruction without exposing secrets or unnecessary sensitive payloads. | +| Decision receipt | Records should be useful for reconstruction without exposing secrets or unnecessary sensitive payloads. | | Service capacity | One actor should not be able to exhaust shared execution resources without bounded controls. | The objective is more useful than a generic label such as "protect the database." @@ -1806,7 +1806,7 @@ It does not constitute: - A penetration test. - A vulnerability assessment. - A compliance assessment. -- A production threat model for any ASI Backbone organization repository. +- A production threat model for any AsiBackbone organization repository. - A guarantee that the listed mitigations are sufficient for a particular application. Threat modeling identifies and structures reasoning. diff --git a/docs/security/trust-boundaries-and-least-privilege.md b/docs/security/trust-boundaries-and-least-privilege.md index 77b2a79..aa760d0 100644 --- a/docs/security/trust-boundaries-and-least-privilege.md +++ b/docs/security/trust-boundaries-and-least-privilege.md @@ -1127,8 +1127,8 @@ The organization repositories provide fuller specimens where the same reasoning | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Trusted actor claims | [`AsiBackboneHttpActorContextOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Actors/AsiBackboneHttpActorContextOptions.cs) | Privileged software actor types require explicit host opt-in, and the actor-type claim is expected to come from a trusted identity-provider-issued or host-generated source rather than user-controlled request data. | -| Narrow execution authority | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Grants are scoped by issuer, audience, operation-related scopes, policy state, acknowledgment, gateway/resource bindings, time, and bounded use, while host authentication and authorization remain separate responsibilities. | +| Trusted actor claims | [`HttpGovernanceActorContextOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Actors/HttpGovernanceActorContextOptions.cs) | Privileged software actor types require explicit host opt-in, and the actor-type claim is expected to come from a trusted identity-provider-issued or host-generated source rather than user-controlled request data. | +| Narrow execution authority | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Grants are scoped by issuer, audience, operation-related scopes, policy state, acknowledgment, gateway/resource bindings, time, and bounded use, while host authentication and authorization remain separate responsibilities. | | Proxy trust boundary | [Forwarded Headers and Proxy Support](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/docs/articles/forwarded-headers.md) | Production deployments can configure trusted proxies/networks; application code should not treat raw forwarded headers as authoritative client identity. | Use these as specimens, not as proof that every application requires the same implementation. diff --git a/docs/templates/conceptual.extension.js b/docs/templates/conceptual.extension.js index db6e589..f90b190 100644 --- a/docs/templates/conceptual.extension.js +++ b/docs/templates/conceptual.extension.js @@ -118,7 +118,7 @@ function buildStructuredData(model) { return null } - var siteName = firstText(model._structuredDataSiteName, model._appName, 'ASI Backbone Learning') + var siteName = firstText(model._structuredDataSiteName, model._appName, 'AsiBackbone Learning') var siteAlternateName = firstText(model._structuredDataSiteAlternateName) var siteDescription = firstText(model._structuredDataSiteDescription) var publisherName = firstText(model._structuredDataPublisherName) diff --git a/docs/templates/layout/_master.tmpl b/docs/templates/layout/_master.tmpl index 187334e..a0a71c7 100644 --- a/docs/templates/layout/_master.tmpl +++ b/docs/templates/layout/_master.tmpl @@ -19,7 +19,7 @@ {{#_description}}{{/_description}} {{#description}}{{/description}} {{#_canonicalUrl}}{{/_canonicalUrl}} - + {{#feed}}{{/feed}}{{^feed}}{{/feed}} {{#description}}{{/description}} @@ -42,7 +42,7 @@ {{#_socialImageAlt}}{{/_socialImageAlt}} {{#_structuredDataJson}}{{/_structuredDataJson}} - + {{#_appLogoPath}}{{/_appLogoPath}} @@ -180,7 +180,7 @@ diff --git a/docs/tutorials/decision-before-execution.md b/docs/tutorials/decision-before-execution.md index 9869445..4b04935 100644 --- a/docs/tutorials/decision-before-execution.md +++ b/docs/tutorials/decision-before-execution.md @@ -26,7 +26,7 @@ description: Learn why consequential operations should become explicit proposed > > **Observe:** A blocked decision never reaches the executor. -This is the first foundational tutorial in ASI Backbone Learning. +This is the first foundational tutorial in AsiBackbone Learning. The pattern is deliberately broader than the `AsiBackbone` package. You can use the same separation in a small application, an API gateway, an administrative workflow, a background process, or an AI-assisted tool system. @@ -567,7 +567,7 @@ It does not prove that: Operational logging and governance evidence can overlap, but they solve different problems. -Later tutorials explore audit residue and provenance in more detail. +Later tutorials explore decision receipt and provenance in more detail. ## Common Failure Modes @@ -699,13 +699,13 @@ Use these references as an implementation map rather than as required dependenci | Tutorial concept | Working reference | What to inspect | | --- | --- | --- | -| Explicit governance decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) and [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | Compare the tutorial's small decision record and outcome enum with the framework's fuller decision model and outcome vocabulary. | -| Context and constraint evaluation | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | Inspect how the working framework evaluates policy and composes governance decisions without turning the evaluator into the host operation itself. | -| Decision behavior under tests | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Follow concrete tests that exercise the evaluator and verify decision behavior through the policy pipeline. | -| Intent through execution | [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | Compare the tutorial's Request -> Intent -> Context -> Decision -> Execution flow with the fuller documented lifecycle. | -| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Examine the framework guidance for keeping execution authority with the host after governance evaluation. | -| Concrete ASP.NET Core host | [`SampleGovernanceController`](https://github.com/AsiBackbone/AsiBackbone/blob/main/samples/PlainAspNetCoreHost/SampleGovernanceController.cs) | See a working host consume governance behavior in an ASP.NET Core application rather than treating the evaluator as the side-effect owner. | -| ASP.NET Core enforcement layer | [`AsiBackboneEndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Endpoints/AsiBackboneEndpointGovernanceMiddleware.cs) and [`AsiBackboneEndpointGovernanceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Endpoints/AsiBackboneEndpointGovernanceTests.cs) | Inspect one concrete request-pipeline enforcement boundary together with the tests that exercise it. | +| Explicit governance decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) and [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | Compare the tutorial's small decision record and outcome enum with the framework's fuller decision model and outcome vocabulary. | +| Context and constraint evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Inspect how the working framework evaluates policy and composes governance decisions without turning the evaluator into the host operation itself. | +| Decision behavior under tests | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Follow concrete tests that exercise the evaluator and verify decision behavior through the policy pipeline. | +| Intent through execution | [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | Compare the tutorial's Request -> Intent -> Context -> Decision -> Execution flow with the fuller documented lifecycle. | +| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Examine the framework guidance for keeping execution authority with the host after governance evaluation. | +| Concrete ASP.NET Core host | [`SampleGovernanceController`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/samples/PlainAspNetCoreHost/SampleGovernanceController.cs) | See a working host consume governance behavior in an ASP.NET Core application rather than treating the evaluator as the side-effect owner. | +| ASP.NET Core enforcement layer | [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) and [`AsiBackboneEndpointGovernanceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Endpoints/AsiBackboneEndpointGovernanceTests.cs) | Inspect one concrete request-pipeline enforcement boundary together with the tests that exercise it. | ### Suggested Reading Order @@ -715,7 +715,7 @@ If you are moving from this tutorial into the production-oriented repository, a GovernanceDecision + GovernanceDecisionOutcome | v -DefaultAsiBackbonePolicyEvaluator +DefaultGovernancePolicyEvaluator | v PolicyEvaluatorEndToEndTests @@ -782,7 +782,7 @@ Host-controlled execution boundary Tool invocation ``` -This leads to a recurring rule throughout ASI Backbone Learning: +This leads to a recurring rule throughout AsiBackbone Learning: > **The model may propose. The host retains execution authority.** @@ -848,7 +848,7 @@ and examines how the facts and outcomes of a governance decision can be represen - [Foundational Tutorial Index](index.md) — view the complete five-tutorial learning path. - [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) — continue into explicit policy facts, constraints, and structured outcomes. - [Escalation Patterns in Governed Systems](../governance/escalation-patterns-in-governed-systems.md) — follow `EscalationRecommended` into an explicit non-executable routing, evidence, and re-evaluation lifecycle. -- [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) — follow the decision lifecycle into acknowledgment and evidence. +- [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) — follow the decision lifecycle into acknowledgment and evidence. - [Governed AI Tool Gateway](governed-ai-tool-gateway.md) — see the proposal-versus-execution boundary composed around AI-proposed tool calls. - [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md) — examine the decision boundary under adversarial assumptions and connect bypass risks to explicit architectural invariants. - [Decision Before Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-before-execution/README.md) — run the framework-neutral companion and observe that blocked decisions never invoke the executor. diff --git a/docs/tutorials/acknowledgment-and-audit-residue.md b/docs/tutorials/decision-receipts-and-acknowledgment.md similarity index 75% rename from docs/tutorials/acknowledgment-and-audit-residue.md rename to docs/tutorials/decision-receipts-and-acknowledgment.md index c584544..5213a34 100644 --- a/docs/tutorials/acknowledgment-and-audit-residue.md +++ b/docs/tutorials/decision-receipts-and-acknowledgment.md @@ -2,7 +2,7 @@ description: Learn how operations pause for bound acknowledgment, re-evaluate current policy, and preserve distinct decision, acknowledgment, and execution evidence. --- -# Acknowledgment and Audit Residue +# Decision Receipts and Acknowledgment **Learning objective:** Understand how a consequential operation can pause for explicit acknowledgment, resume through a governed boundary, and leave structured evidence explaining what was proposed, decided, acknowledged, and ultimately performed. @@ -12,7 +12,7 @@ description: Learn how operations pause for bound acknowledgment, re-evaluate cu **Prerequisites:** [Decision Before Execution](decision-before-execution.md) and [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) -**Glossary:** [Acknowledgment](../architecture/glossary.md#acknowledgment), [audit residue](../architecture/glossary.md#audit-residue), and [decision provenance](../architecture/glossary.md#decision-provenance). +**Glossary:** [Acknowledgment](../architecture/glossary.md#acknowledgment), [decision receipt](../architecture/glossary.md#decision-receipt), and [decision provenance](../architecture/glossary.md#decision-provenance). ## Pattern Card @@ -26,7 +26,7 @@ description: Learn how operations pause for bound acknowledgment, re-evaluate cu > > **Observe:** A valid acknowledgment does not override policy; changed context can still block execution after acknowledgment. -This is the third foundational tutorial in ASI Backbone Learning. +This is the third foundational tutorial in AsiBackbone Learning. It builds on: @@ -48,11 +48,13 @@ Constraints ↓ Decision ↓ +Decision receipt + ↓ Acknowledgment when required ↓ Host-owned continuation ↓ -Audit residue +Correlated lifecycle evidence ``` The core ideas are: @@ -61,7 +63,7 @@ The core ideas are: and: -> **Audit residue should explain the governed path without pretending that an ordinary log line is durable proof.** +> **A decision receipt should explain the evaluation outcome and its reasons without pretending that an ordinary log line is durable proof—or that a decision proves execution.** ## The Problem @@ -112,7 +114,7 @@ At the same time, the system may need to answer later: - Did execution happen afterward? - Which correlation identifier connects these events? -Those questions motivate structured audit residue. +Those questions motivate structured decision receipt. ## A Naive Confirmation Dialog @@ -522,10 +524,10 @@ User disabled account. does not explain the governed path. -A more useful residue might capture: +A decision receipt might capture: ```text -EventId +ReceiptId OccurredUtc ActorId OperationName @@ -534,7 +536,6 @@ ReasonCodes CorrelationId PolicyVersion PolicyHash -DecisionStage ``` These policy fields are part of decision provenance, not merely decoration on an audit record. See [Policy Versioning and Decision Provenance](../governance/policy-versioning-and-decision-provenance.md) for the deeper treatment of decision-time identity, policy drift, freshness, and the limits of fingerprints. @@ -542,8 +543,8 @@ These policy fields are part of decision provenance, not merely decoration on an A minimal educational model: ```csharp -public sealed record AuditResidue( - string EventId, +public sealed record DecisionReceipt( + string ReceiptId, DateTimeOffset OccurredUtc, string ActorId, string OperationName, @@ -551,11 +552,22 @@ public sealed record AuditResidue( IReadOnlyList ReasonCodes, string CorrelationId, string PolicyVersion, - string? PolicyHash, - string DecisionStage); + string? PolicyHash); +``` + +Acknowledgment and execution are later lifecycle events, not additional claims about what the evaluator decided. A separate event shape can correlate those stages with the original receipt: + +```csharp +public sealed record DecisionReceiptLifecycleEvent( + string EventId, + DateTimeOffset OccurredUtc, + string CorrelationId, + string ReceiptId, + string Stage, + string Outcome); ``` -Examples of stages: +Examples of lifecycle stages: ```text decision @@ -568,7 +580,7 @@ execution-completed execution-failed ``` -A single operation can therefore leave multiple related residues. +A single operation can therefore produce a decision receipt, later lifecycle events, and a fresh decision receipt if policy is re-evaluated. Correlation does not collapse those records into one claim. ## Think in a Timeline @@ -600,22 +612,21 @@ CorrelationId = req-7d91 This creates a navigable governance timeline without forcing every fact into one giant record. -## Decision Residue +## Decision Receipt -A helper might create residue from a decision: +A helper might create receipt from a decision: ```csharp -public static AuditResidue FromDecision( +public static DecisionReceipt FromDecision( string actorId, string operationName, GovernanceDecision decision, string correlationId, string policyVersion, - string? policyHash, - string stage) + string? policyHash) { - return new AuditResidue( - EventId: Guid.NewGuid().ToString("N"), + return new DecisionReceipt( + ReceiptId: Guid.NewGuid().ToString("N"), OccurredUtc: DateTimeOffset.UtcNow, ActorId: actorId, OperationName: operationName, @@ -626,52 +637,43 @@ public static AuditResidue FromDecision( .ToArray(), CorrelationId: correlationId, PolicyVersion: policyVersion, - PolicyHash: policyHash, - DecisionStage: stage); + PolicyHash: policyHash); } ``` -The host can create a decision residue before execution: +The host can create a decision receipt before execution: ```csharp -AuditResidue residue = - AuditResidueFactory.FromDecision( +DecisionReceipt receipt = + DecisionReceiptFactory.FromDecision( actor.Id, "account.disable", decision, context.CorrelationId, context.PolicyVersion, - policyHash: null, - stage: "decision"); + policyHash: null); ``` -## Acknowledgment Residue +## Acknowledgment Lifecycle Event The acknowledgment itself can produce a separate event: ```csharp -public static AuditResidue FromAcknowledgment( +public static DecisionReceiptLifecycleEvent FromAcknowledgment( + DecisionReceipt receipt, AcknowledgmentChallenge challenge, AcknowledgmentResponse response) { - return new AuditResidue( + return new DecisionReceiptLifecycleEvent( EventId: response.AcknowledgmentId, OccurredUtc: response.OccurredUtc, - ActorId: response.ActorId, - OperationName: challenge.OperationName, + CorrelationId: challenge.CorrelationId, + ReceiptId: receipt.ReceiptId, + Stage: "acknowledgment", Outcome: response.Accepted ? "AcknowledgmentAccepted" - : "AcknowledgmentRejected", - ReasonCodes: - [ - challenge.ReasonCode, - challenge.RequiredAcknowledgmentCode - ], - CorrelationId: challenge.CorrelationId, - PolicyVersion: challenge.PolicyVersion, - PolicyHash: null, - DecisionStage: "acknowledgment"); + : "AcknowledgmentRejected"); } ``` @@ -695,43 +697,32 @@ Host later executed operation Those are different events. -## Execution Residue +## Execution Lifecycle Event After the host operation: ```csharp -AuditResidue completed = +DecisionReceiptLifecycleEvent completed = new( EventId: Guid.NewGuid().ToString("N"), OccurredUtc: DateTimeOffset.UtcNow, - ActorId: actor.Id, - OperationName: "account.disable", - Outcome: "Executed", - ReasonCodes: [], CorrelationId: context.CorrelationId, - PolicyVersion: context.PolicyVersion, - PolicyHash: null, - DecisionStage: "execution-completed"); + ReceiptId: receipt.ReceiptId, + Stage: "execution-completed", + Outcome: "Executed"); ``` If execution fails: ```csharp -AuditResidue failed = +DecisionReceiptLifecycleEvent failed = new( EventId: Guid.NewGuid().ToString("N"), OccurredUtc: DateTimeOffset.UtcNow, - ActorId: actor.Id, - OperationName: "account.disable", - Outcome: "ExecutionFailed", - ReasonCodes: - [ - "account.disable.execution-failed" - ], CorrelationId: context.CorrelationId, - PolicyVersion: context.PolicyVersion, - PolicyHash: null, - DecisionStage: "execution-failed"); + ReceiptId: receipt.ReceiptId, + Stage: "execution-failed", + Outcome: "ExecutionFailed"); ``` The decision and execution are now distinguishable in the evidence. @@ -748,7 +739,7 @@ does not mean: Executed successfully ``` -## Logging and Audit Residue Are Different +## Logging and Decision Receipt Are Different Operational logging asks questions such as: @@ -757,12 +748,15 @@ Operational logging asks questions such as: - Which exception occurred? - Which dependency failed? -Audit residue asks questions such as: +Decision receipts ask questions such as: - What consequential operation was proposed? - What governance outcome was produced? - Which reason codes applied? - Was acknowledgment required? + +Correlated lifecycle evidence asks follow-on questions such as: + - Who acknowledged? - What execution state followed? @@ -793,16 +787,16 @@ Timestamp Accepted / Rejected ``` -Structured audit residue gives those concepts a deliberate shape. +Structured decision receipts and correlated lifecycle events give those concepts deliberate, separate shapes. -## Audit Residue Is Not Automatically Tamper-Proof +## Decision Receipt Is Not Automatically Tamper-Proof This boundary is important. Creating: ```csharp -new AuditResidue(...) +new DecisionReceipt(...) ``` does not automatically create: @@ -866,18 +860,18 @@ Mark delivery status This is an implementation concern beyond the minimal tutorial, but it illustrates an important distinction: ```text -Create residue +Create receipt ≠ -Persist residue +Persist receipt ≠ -Deliver residue +Deliver receipt ``` Those are separate responsibilities. ## Keep Audit Data Purposeful -Audit residue should not become a dumping ground. +A decision receipt should not become a dumping ground. Avoid copying: @@ -1128,7 +1122,7 @@ A production workflow depends on evidence that may disappear with process restar Durability requires a persistence design. -### 8. Audit Residue Stores Too Much Sensitive Data +### 8. Decision Receipt Stores Too Much Sensitive Data Evidence becomes a secondary data breach surface. @@ -1179,39 +1173,39 @@ This tutorial is framework-neutral, but the working `AsiBackbone` repository con ### Working Implementation Map -The Learning example keeps acknowledgment and audit residue in one small workflow so the lifecycle is easy to observe. The production framework separates handshake records, ASP.NET Core challenge handling, lifecycle evidence, persistence-ready records, and storage contracts into distinct surfaces. +The Learning example keeps acknowledgment and decision receipt in one small workflow so the lifecycle is easy to observe. The production framework separates handshake records, ASP.NET Core challenge handling, lifecycle evidence, persistence-ready records, and storage contracts into distinct surfaces. | Tutorial concept | Working implementation | What to inspect | | --- | --- | --- | -| Decision-derived acknowledgment request | [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) | `FromDecision` carries the decision's reason, correlation ID, trace ID, policy version, and policy hash into a framework-neutral handshake request. | -| Accepted or rejected actor response | [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) | The separate acknowledgment record preserves handshake identity, responding actor, acknowledgment code, accepted/rejected state, timestamp, and correlation metadata without becoming execution authority. | -| ASP.NET Core challenge boundary | [`DefaultAsiBackboneAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Handshakes/DefaultAsiBackboneAcknowledgmentChallengeService.cs) | How an `AcknowledgmentRequired` decision becomes a host-facing challenge and how response handshake IDs and acknowledgment codes are checked before an acknowledgment record is produced. | -| Challenge behavior under tests | [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) | Executable examples for challenge creation, accepted and rejected responses, mismatch handling, correlation, trace, and policy metadata. | -| Structured governance evidence | [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) | The richer evidence model for actor, operation, outcome, reason codes, correlation/trace data, decision stage, policy identity, and optional observability fields. | -| Append-style lifecycle evidence | [`AuditResidueLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidueLifecycleEvent.cs) and [`AuditResidueLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidueLifecycleStage.cs) | How acknowledgment, capability, gateway, and emission progress can be represented as separate correlated events without rewriting the original decision residue. | -| Lifecycle behavior under tests | [`AuditResidueLifecycleEventTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditResidueLifecycleEventTests.cs) | Stable lifecycle-stage sequencing, required correlation, and tests showing that later progress can be recorded without mutating the original residue. | -| Persistence-ready audit record | [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) | The persistence-oriented projection that adds recording time, handshake and acknowledgment references, optional hash/signature metadata, and other durable-record fields. | -| Host-owned audit persistence | [`IAsiBackboneAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/IAsiBackboneAuditLedgerStore.cs) | The provider-neutral append and query contract for durable host-owned audit ledger storage. | -| Audit model and persistence tests | [`AuditLedgerRecordTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) and [`IAsiBackboneAuditLedgerStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/IAsiBackboneAuditLedgerStoreTests.cs) | Executable coverage for persistence-ready records and the audit ledger storage contract. | +| Decision-derived acknowledgment request | [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) | `FromDecision` carries the decision's reason, correlation ID, trace ID, policy version, and policy hash into a framework-neutral handshake request. | +| Accepted or rejected actor response | [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) | The separate acknowledgment record preserves handshake identity, responding actor, acknowledgment code, accepted/rejected state, timestamp, and correlation metadata without becoming execution authority. | +| ASP.NET Core challenge boundary | [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) | How an `AcknowledgmentRequired` decision becomes a host-facing challenge and how response handshake IDs and acknowledgment codes are checked before an acknowledgment record is produced. | +| Challenge behavior under tests | [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) | Executable examples for challenge creation, accepted and rejected responses, mismatch handling, correlation, trace, and policy metadata. | +| Structured governance evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | The richer evidence model for actor, operation, outcome, reason codes, correlation/trace data, decision stage, policy identity, and optional observability fields. | +| Append-style lifecycle evidence | [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | How acknowledgment, capability, gateway, and emission progress can be represented as separate correlated events without rewriting the original decision receipt. | +| Lifecycle behavior under tests | [`AuditResidueLifecycleEventTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditResidueLifecycleEventTests.cs) | This compatibility-retained test fixture name exercises the 6.0 `DecisionReceiptLifecycleEvent` stages and shows that later progress can be recorded without mutating the original receipt. | +| Persistence-ready audit record | [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) | The persistence-oriented projection that adds recording time, handshake and acknowledgment references, optional hash/signature metadata, and other durable-record fields. | +| Host-owned audit persistence | [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) | The provider-neutral append and query contract for durable host-owned audit ledger storage. | +| Audit model and persistence tests | [`AuditLedgerRecordTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) and [`IAsiBackboneAuditLedgerStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/IAsiBackboneAuditLedgerStoreTests.cs) | Executable coverage for persistence-ready records and the `IGovernanceAuditLedgerStore` contract; the latter test fixture retains its pre-6.0 filename. | ### Follow the Acknowledgment and Evidence Path For a code-first inspection, follow these references in order: -1. [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — begin where an acknowledgment-required governance decision is projected into an explicit responsibility-handshake request. -2. [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the separate accepted/rejected actor response. -3. [`DefaultAsiBackboneAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Handshakes/DefaultAsiBackboneAcknowledgmentChallengeService.cs) — see one host-integration boundary for challenge creation and response handling. -4. [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) — compare the integration behavior with executable challenge and mismatch scenarios. -5. [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — inspect the evidence object that can retain outcome, reason, correlation, trace, policy, and stage information. -6. [`AuditResidueLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidueLifecycleEvent.cs) and [`AuditResidueLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidueLifecycleStage.cs) — follow how later acknowledgment and execution progress remains separate from the original decision record. -7. [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`IAsiBackboneAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/IAsiBackboneAuditLedgerStore.cs) — continue from in-memory evidence shape into persistence-ready records and host-owned durable storage. +1. [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — begin where an acknowledgment-required governance decision is projected into an explicit responsibility-handshake request. +2. [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the separate accepted/rejected actor response. +3. [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) — see one host-integration boundary for challenge creation and response handling. +4. [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) — compare the integration behavior with executable challenge and mismatch scenarios. +5. [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — inspect the evidence object that can retain outcome, reason, correlation, trace, policy, and stage information. +6. [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) — follow how later acknowledgment and execution progress remains separate from the original decision record. +7. [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) — continue from in-memory evidence shape into persistence-ready records and host-owned durable storage. For architectural explanation rather than source code, see: -- [Dynamic Liability Handshake](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) — documents the broader acknowledgment/responsibility-handshake lifecycle and explicitly keeps execution policy host-owned. -- [Durable Audit and Outbox Persistence](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) — explains why local durable evidence should precede optional downstream emission and distinguishes append-style audit evidence from outbox delivery state. -- [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) — connects the tutorial's evidence-minimization guidance to production-oriented metadata hygiene. -- [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signed-audit-and-outbox-records.md) — shows the implemented signing seams while preserving the important distinction between signing and stronger immutability or tamper-evidence claims. +- [Dynamic Liability Handshake](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) — documents the broader acknowledgment/responsibility-handshake lifecycle and explicitly keeps execution policy host-owned. +- [Durable Audit and Outbox Persistence](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) — explains why local durable evidence should precede optional downstream emission and distinguishes append-style audit evidence from outbox delivery state. +- [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) — connects the tutorial's evidence-minimization guidance to production-oriented metadata hygiene. +- [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signed-audit-and-outbox-records.md) — shows the implemented signing seams while preserving the important distinction between signing and stronger immutability or tamper-evidence claims. The production framework carries considerably more metadata and persistence/signing seams than the teaching model because it supports broader integration, observability, and governance scenarios. The Learning records are teaching-specific shapes rather than copies of framework production types. @@ -1253,7 +1247,7 @@ Current decision ↓ Host-controlled execution ↓ -Audit residue +Decision receipt ``` The evidence can distinguish: @@ -1278,7 +1272,7 @@ Add: ```text AcknowledgmentChallenge AcknowledgmentResponse -AuditResidue +DecisionReceipt ``` Implement this flow: @@ -1304,7 +1298,7 @@ Decision = Allowed ↓ Executor invoked ↓ -Execution residue created +Execution receipt created ``` Write tests proving: @@ -1314,10 +1308,10 @@ Write tests proving: 3. An expired challenge is invalid. 4. A valid acknowledgment satisfies only the intended requirement. 5. A newly introduced denial still blocks execution after acknowledgment. -6. Decision, acknowledgment, and execution residues share the same correlation identifier. +6. Decision, acknowledgment, and execution receipts share the same correlation identifier. 7. An allowed decision and a successful execution are recorded as distinct states. -For additional practice, persist challenge state and audit residue using an in-memory repository abstraction. +For additional practice, persist challenge state and decision receipt using an in-memory repository abstraction. Then simulate a process restart and ask: @@ -1334,7 +1328,7 @@ Before moving on, you should be able to: - [ ] Explain why current policy and context may need to be re-evaluated after acknowledgment before execution can proceed. - [ ] Demonstrate that rejection, actor mismatch, expiration, replay, or a newly introduced denial still prevents the protected side effect. - [ ] Preserve correlated but distinct evidence for decision, acknowledgment, re-evaluation, and execution outcomes. -- [ ] Explain what audit residue contributes beyond ordinary diagnostics without claiming that an unsigned or mutable store is automatically tamper-proof. +- [ ] Explain what decision receipt contributes beyond ordinary diagnostics without claiming that an unsigned or mutable store is automatically tamper-proof. - [ ] Identify the additional persistence, privacy, and lifecycle responsibilities that appear when acknowledgment and evidence must survive process restarts. ## Next @@ -1373,12 +1367,12 @@ This continues the same principle established throughout Learning: - [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) — revisit the explicit decision inputs and outcomes that can lead to an acknowledgment requirement. - [Escalation Patterns in Governed Systems](../governance/escalation-patterns-in-governed-systems.md) — compare acknowledgment with escalation and follow an escalation into a separate authority, evidence, and re-evaluation path. - [Scoped Capability and Host-Owned Execution](scoped-capability-and-host-owned-execution.md) — continue from acknowledgment into narrow, short-lived execution authority. -- [Governed AI Tool Gateway](governed-ai-tool-gateway.md) — see acknowledgment, capability, execution, and audit residue composed around AI-proposed actions. +- [Governed AI Tool Gateway](governed-ai-tool-gateway.md) — see acknowledgment, capability, execution, and decision receipt composed around AI-proposed actions. - [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md) — reason about acknowledgment replay, evidence leakage, alternate continuation paths, and residual risk around responsibility boundaries. - [Structured Logging Without Sensitive-Data Sprawl](../aspnetcore/structured-logging-without-sensitive-data-sprawl.md) — compare high-volume operational diagnostics with evidence-oriented governance records that may share correlation without becoming the same artifact. - [Secure Logging Across Trust Boundaries](../security/secure-logging-across-trust-boundaries.md) — continue from the log-versus-evidence distinction into provider, export, storage, access, tenant, retention, and degraded-observability trust boundaries. -- [Acknowledgment and Audit Residue sample](https://github.com/AsiBackbone/Learning/blob/main/samples/acknowledgment-and-audit-residue/README.md) — run the companion workflow and observe bound acknowledgment, re-evaluation, correlation, and distinct evidence stages. -- [Acknowledgment and Audit Residue intermediate lab](../labs/acknowledgment-and-audit-residue.md) — break and strengthen the acknowledgment boundary, add replay state, preserve evidence behind a store, and distinguish policy decisions from execution failure. +- [Decision Receipts and Acknowledgment sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md) — run the companion workflow and observe bound acknowledgment, re-evaluation, correlation, and distinct evidence stages. +- [Decision Receipts and Acknowledgment intermediate lab](../labs/decision-receipts-and-acknowledgment.md) — break and strengthen the acknowledgment boundary, add replay state, preserve evidence behind a store, and distinguish policy decisions from execution failure. - [Executable Samples](../samples/index.md) — explore the published companion-sample guide before following a canonical sample README. - [Hands-On Labs](../labs/index.md) — practice acknowledgment, evidence, and governed-continuation boundaries through hands-on exercises. diff --git a/docs/tutorials/governed-ai-tool-gateway.md b/docs/tutorials/governed-ai-tool-gateway.md index 3e02105..a01cdbb 100644 --- a/docs/tutorials/governed-ai-tool-gateway.md +++ b/docs/tutorials/governed-ai-tool-gateway.md @@ -26,13 +26,13 @@ description: Learn an AI tool gateway pattern where models propose actions while > > **Observe:** Unknown or invalid proposals never reach the handler, model-provided claims cannot override authoritative host context, and stale or replayed execution authority is rejected. -This is the fifth foundational tutorial in ASI Backbone Learning. +This is the fifth foundational tutorial in AsiBackbone Learning. It builds on: 1. [Decision Before Execution](decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) 4. [Scoped Capability and Host-Owned Execution](scoped-capability-and-host-owned-execution.md) The first four tutorials introduced individual architectural boundaries. @@ -62,7 +62,7 @@ Execution-boundary validation ↓ Host-owned tool invocation ↓ -Audit residue +Decision receipt ``` The central rule is: @@ -428,7 +428,7 @@ switch (decision.Outcome) case GovernanceDecisionOutcome.Deferred: case GovernanceDecisionOutcome.EscalationRecommended: await auditSink.WriteAsync( - CreateDecisionResidue( + CreateDecisionReceipt( context, decision), cancellationToken); @@ -706,7 +706,7 @@ public sealed class GovernedAiToolGateway( policy.Evaluate(context); await auditSink.WriteAsync( - AuditResidueFactory.FromDecision( + DecisionReceiptFactory.FromDecision( context, decision), cancellationToken); @@ -732,7 +732,7 @@ public sealed class GovernedAiToolGateway( cancellationToken); await auditSink.WriteAsync( - AuditResidueFactory + DecisionReceiptFactory .FromAcknowledgment( context, acknowledgment), @@ -761,7 +761,7 @@ public sealed class GovernedAiToolGateway( }); await auditSink.WriteAsync( - AuditResidueFactory.FromDecision( + DecisionReceiptFactory.FromDecision( context, decision, stage: "re-evaluation"), @@ -789,7 +789,7 @@ public sealed class GovernedAiToolGateway( cancellationToken); await auditSink.WriteAsync( - AuditResidueFactory + DecisionReceiptFactory .FromCapabilityValidation( context, validation), @@ -812,7 +812,7 @@ public sealed class GovernedAiToolGateway( cancellationToken); await auditSink.WriteAsync( - AuditResidueFactory + DecisionReceiptFactory .FromExecution( context, result), @@ -1574,13 +1574,13 @@ This tutorial is framework-neutral, but the working `AsiBackbone` repository doc Useful references include: -- [`AI Agent Gateway Scenario`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — positions AsiBackbone as a governance checkpoint between an AI-proposed action and host-owned execution. -- [`Human Approval Before AI Tool Execution`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — focuses on acknowledgment before an AI-proposed consequential action proceeds. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured decision outcomes and reason data. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) — structured governance evidence. -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — framework-neutral acknowledgment/handshake request. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — short-lived, provider-neutral capability metadata for governed follow-on execution. -- [`Capability Grant Hardening`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — execution-boundary validation, proof handling, bindings, failure behavior, and bounded-use guidance. +- [`AI Agent Gateway Scenario`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — positions AsiBackbone as a governance checkpoint between an AI-proposed action and host-owned execution. +- [`Human Approval Before AI Tool Execution`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — focuses on acknowledgment before an AI-proposed consequential action proceeds. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured decision outcomes and reason data. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — structured governance evidence. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — framework-neutral acknowledgment/handshake request. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — short-lived, provider-neutral capability metadata for governed follow-on execution. +- [`Capability Grant Hardening`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — execution-boundary validation, proof handling, bindings, failure behavior, and bounded-use guidance. The working project makes the responsibility boundary explicit: @@ -1666,7 +1666,7 @@ Execution validation ↓ Simulated notification handler ↓ -Audit residue +Decision receipt ``` Do **not** send a real message initially. @@ -1717,7 +1717,7 @@ You have now completed the five foundational patterns: ↓ 2. Policy Context and Explicit Decision Outcomes ↓ -3. Acknowledgment and Audit Residue +3. Decision Receipts and Acknowledgment ↓ 4. Scoped Capability and Host-Owned Execution ↓ @@ -1787,7 +1787,7 @@ Learning is intended to make those tradeoffs visible rather than prescribe one u - [AI Proposal Rejection, Uncertainty, and Recovery Patterns](../ai-integration/ai-proposal-rejection-uncertainty-and-recovery-patterns.md) — classify failed proposal stages, preserve uncertainty, bound retries and feedback, and terminate or escalate without weakening host authority. - [Governed Multi-Tool Workflows and Recovery Boundaries](../ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md) — repeat the gateway boundary per step while handling drift, partial failure, replanning, idempotency, compensation, cancellation, and recovery. - [Agent Memory and Governance Boundaries](../ai-integration/agent-memory-and-governance-boundaries.md) — retain useful context without allowing remembered facts, prior approvals, stale observations, or model-generated notes to bypass current host context and authority. -- [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) — explore responsibility boundaries, re-evaluation, correlation, and evidence across consequential workflows. +- [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) — explore responsibility boundaries, re-evaluation, correlation, and evidence across consequential workflows. - [Scoped Capability and Host-Owned Execution](scoped-capability-and-host-owned-execution.md) — examine narrow execution authority, capability bindings, replay considerations, and execution-boundary validation. - [Governed Agent-to-Agent Requests and Multi-Agent Execution Boundaries](../advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md) — extend the single-agent gateway into an explicitly experimental multi-agent model without treating agent agreement, planning, or delegation requests as execution authority. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — distinguish single-use capability enforcement from request idempotency and exactly-once execution claims. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 0ec0d01..6c89906 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -4,7 +4,7 @@ description: Browse problem-first tutorials that expose failure modes, introduce # Tutorials -ASI Backbone Learning tutorials are **problem-first**. They begin with an architectural problem, expose a failure mode or limitation, introduce a pattern, and connect the teaching example to runnable evidence and fuller implementations. +AsiBackbone Learning tutorials are **problem-first**. They begin with an architectural problem, expose a failure mode or limitation, introduce a pattern, and connect the teaching example to runnable evidence and fuller implementations. The goal is understanding—not framework adoption. @@ -14,7 +14,7 @@ The goal is understanding—not framework adoption. | --- | --- | --- | --- | | 1 | [Decision Before Execution](decision-before-execution.md) | Beginner | Evaluation is separated from protected execution | | 2 | [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) | Beginner | Decision facts and outcomes become explicit | -| 3 | [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) | Intermediate | Acknowledgment and decision evidence remain distinct from authority | +| 3 | [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) | Intermediate | Decision receipts, acknowledgment, and later lifecycle evidence remain distinct from authority | | 4 | [Scoped Capability and Host-Owned Execution](scoped-capability-and-host-owned-execution.md) | Intermediate | Execution authority becomes narrow, temporary, and host-validated | | 5 | [Governed AI Tool Gateway](governed-ai-tool-gateway.md) | Intermediate | AI proposal is composed with host-owned context, policy, authority, and execution | @@ -67,7 +67,7 @@ Represent the facts used by policy explicitly and return outcomes that describe **Core ideas:** actor/resource/operation/environment context, context snapshots, stable reason codes, policy identity, determinism, and decision composition. -### 3. [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) +### 3. [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) Pause a consequential operation for explicit acknowledgment, resume through a governed boundary, and preserve structured evidence of the decision path. @@ -98,7 +98,7 @@ Execution-boundary validation ↓ Host-owned tool execution ↓ -Audit residue +Decision receipt ``` > **The model may propose. The host retains execution authority.** diff --git a/docs/tutorials/policy-context-and-explicit-decision-outcomes.md b/docs/tutorials/policy-context-and-explicit-decision-outcomes.md index b38044c..8844b42 100644 --- a/docs/tutorials/policy-context-and-explicit-decision-outcomes.md +++ b/docs/tutorials/policy-context-and-explicit-decision-outcomes.md @@ -26,7 +26,7 @@ description: Learn to make governance inputs explicit with policy-context snapsh > > **Observe:** Policy evaluation consumes an explicit context snapshot and returns a structured outcome without performing the governed side effect. -This is the second foundational tutorial in ASI Backbone Learning. +This is the second foundational tutorial in AsiBackbone Learning. It builds on [Decision Before Execution](decision-before-execution.md), which established the first boundary: @@ -841,7 +841,7 @@ Policy identity Decision evidence ``` -Later tutorials will expand this into acknowledgment and audit residue. +Later tutorials will expand this into acknowledgment and decision receipt. ## Keep Sensitive Data Out of Reason Messages @@ -1036,7 +1036,7 @@ Context must be available before governed execution. Not every context field belongs in durable audit storage. -Decision context and audit residue are related but different concepts. +Decision context and decision receipt are related but different concepts. The next tutorial will examine that boundary more closely. @@ -1076,14 +1076,14 @@ The Learning example intentionally compresses the architecture so the policy bou | Tutorial concept | Working implementation | What to inspect | | --- | --- | --- | -| Framework-neutral policy context contract | [`IAsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IAsiBackboneConstraintEvaluationContext.cs) | The minimum context surface shared by evaluators and constraints. | -| Concrete context snapshot | [`AsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/AsiBackboneConstraintEvaluationContext.cs) | Correlation ID, policy version/hash, and normalized host-provided metadata. | -| Explicit outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework's allowed, warning, denied, deferred, acknowledgment-required, and escalation-recommended states. | -| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, stable reason codes, correlation and trace identifiers, policy identity, and `CanProceed`. | -| Constraint composition | [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) | How constraint results are accumulated and composed into a governance decision. | -| Domain- or host-specific final decision rules | [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) | The post-composition boundary that can introduce deferred, acknowledgment-required, or escalation-recommended outcomes. | -| Transport mapping | [`AsiBackboneHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Results/AsiBackboneHttpResultMappingExtensions.cs) | How a governance decision is translated into HTTP without moving transport concerns into the Core decision model. | -| End-to-end policy behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable examples of evaluator behavior and decision composition. | +| Framework-neutral policy context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimum context surface shared by evaluators and constraints. | +| Concrete context snapshot | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation ID, policy version/hash, and normalized host-provided metadata. | +| Explicit outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework's allowed, warning, denied, deferred, acknowledgment-required, and escalation-recommended states. | +| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, stable reason codes, correlation and trace identifiers, policy identity, and `CanProceed`. | +| Constraint composition | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | How constraint results are accumulated and composed into a governance decision. | +| Domain- or host-specific final decision rules | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary that can introduce deferred, acknowledgment-required, or escalation-recommended outcomes. | +| Transport mapping | [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) | How a governance decision is translated into HTTP without moving transport concerns into the Core decision model. | +| End-to-end policy behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable examples of evaluator behavior and decision composition. | The framework currently distinguishes these outcomes: @@ -1102,17 +1102,17 @@ The Learning example uses the same vocabulary so the conceptual model maps clean For a code-first inspection, follow these references in order: -1. [`IAsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IAsiBackboneConstraintEvaluationContext.cs) — begin with the context contract. -2. [`AsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/AsiBackboneConstraintEvaluationContext.cs) — inspect the default concrete context snapshot. -3. [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) — follow constraint evaluation and composition. -4. [`IAsiBackboneDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IAsiBackboneDecisionPolicy.cs) — see where broader host or domain policy can refine the composed result. -5. [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the final structured decision contract. -6. [`AsiBackboneHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Results/AsiBackboneHttpResultMappingExtensions.cs) — observe transport mapping after the governance decision exists. +1. [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — begin with the context contract. +2. [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) — inspect the default concrete context snapshot. +3. [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — follow constraint evaluation and composition. +4. [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) — see where broader host or domain policy can refine the composed result. +5. [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the final structured decision contract. +6. [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) — observe transport mapping after the governance decision exists. For architectural explanation rather than source code, see: -- [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) — explains the evaluator flow and composition boundary. -- [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) — shows how host-specific policy can transform a composed result without pushing those rules into individual constraints. +- [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) — explains the evaluator flow and composition boundary. +- [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) — shows how host-specific policy can transform a composed result without pushing those rules into individual constraints. The Learning records such as `ActorContext`, `AccountContext`, and `EnvironmentContext` are teaching-specific shapes. They are not copies of framework production types. The important mapping is architectural: **explicit facts enter evaluation, policy interprets those facts, and a structured decision leaves evaluation**. @@ -1225,7 +1225,7 @@ Before moving on, you should be able to: ## Next -The next foundational topic is **Acknowledgment and Audit Residue**. +The next foundational topic is **Decision Receipts and Acknowledgment**. That tutorial expands the lifecycle after a decision: @@ -1236,7 +1236,7 @@ Acknowledgment when required ↓ Host action ↓ -Audit residue +Decision receipt ``` It will examine how a consequential operation can pause for explicit acknowledgment and how structured evidence can preserve what happened without confusing governance evidence with ordinary application logging. @@ -1249,7 +1249,7 @@ It will examine how a consequential operation can pause for explicit acknowledgm - [Risk-Based Decisions in Governed Systems](../governance/risk-based-decisions-in-governed-systems.md) — extend explicit context and structured outcomes with reviewable risk factors, versioned risk-to-outcome mapping, freshness, provenance, and threshold tests. - [Escalation Patterns in Governed Systems](../governance/escalation-patterns-in-governed-systems.md) — continue from the `EscalationRecommended` outcome into routing, additional evidence, current-context re-evaluation, and a new decision. - [When ASP.NET Core Authorization Is Enough](../architecture/when-aspnet-core-authorization-is-enough.md) — compare this richer decision model with built-in ASP.NET Core policies, requirements, handlers, and resource-based authorization, including cases where the simpler authorization model is the better choice. -- [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) — continue from explicit decision outcomes into acknowledgment, re-evaluation, correlation, and governance evidence. +- [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) — continue from explicit decision outcomes into acknowledgment, re-evaluation, correlation, and governance evidence. - [Scoped Capability and Host-Owned Execution](scoped-capability-and-host-owned-execution.md) — follow allowed or acknowledged decisions into narrowly scoped execution authority. - [Governed AI Tool Gateway](governed-ai-tool-gateway.md) — see authoritative host context and explicit decision outcomes applied to AI-proposed tool actions. - [Threat Modeling as Architecture Reasoning](../security/threat-modeling-as-architecture-reasoning.md) — use source-of-authority questions to identify caller-controlled context, trust changes, bypass paths, and unprotected assumptions. diff --git a/docs/tutorials/scoped-capability-and-host-owned-execution.md b/docs/tutorials/scoped-capability-and-host-owned-execution.md index 02581de..a91b262 100644 --- a/docs/tutorials/scoped-capability-and-host-owned-execution.md +++ b/docs/tutorials/scoped-capability-and-host-owned-execution.md @@ -10,7 +10,7 @@ description: Learn how narrow, short-lived capabilities preserve host control be **Difficulty:** Intermediate -**Prerequisites:** [Decision Before Execution](decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md), and [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) +**Prerequisites:** [Decision Before Execution](decision-before-execution.md), [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md), and [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) **Glossary:** [Scoped capability](../architecture/glossary.md#scoped-capability), [capability token](../architecture/glossary.md#capability-token), [execution authority](../architecture/glossary.md#execution-authority), [host-owned execution](../architecture/glossary.md#host-owned-execution), and [trust boundary](../architecture/glossary.md#trust-boundary). @@ -26,13 +26,13 @@ description: Learn how narrow, short-lived capabilities preserve host control be > > **Observe:** A blocked decision cannot mint execution authority, and expired or stale authority never reaches the executor. -This is the fourth foundational tutorial in ASI Backbone Learning. +This is the fourth foundational tutorial in AsiBackbone Learning. It builds on: 1. [Decision Before Execution](decision-before-execution.md) 2. [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) -3. [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) +3. [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) The earlier tutorials established that a consequential action should be proposed, evaluated, and—when necessary—acknowledged before execution. @@ -59,7 +59,7 @@ Capability validation ↓ Host-owned execution ↓ -Audit residue +Decision receipt ``` The central principle is: @@ -1351,27 +1351,27 @@ Use these references as an implementation map rather than as required dependenci | Tutorial concept | Working reference | What to inspect | | --- | --- | --- | -| Narrow, short-lived execution authority | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | Compare the tutorial's compact `ExecutionCapability` with the provider-neutral grant metadata for issuer, audience, scopes, time bounds, subject, operation, policy identity, acknowledgment/handshake references, gateway binding, and resource binding. | -| Execution-boundary versus metadata-only validation | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | Compare `CreateExecutionBoundary(...)`, which requires proof and bounded-use validation by default, with the deliberately weaker `CreateMetadataValidation(...)` profile. | -| Capability validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Follow proof verification, issuer/audience checks, time bounds, scopes, policy identity, acknowledgment/handshake references, gateway/resource bindings, and optional bounded-use state before a result can allow continuation. | -| Execution-profile behavior under tests | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | Inspect executable cases for strict execution-boundary defaults, metadata-only behavior, proof failure, unavailable use-state, binding mismatches, expiration, policy evidence, and validation outcomes. | -| Bounded-use and replay-state seam | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Compare the provider-neutral host contract with the explicitly local in-memory reference implementation. Durable, distributed, atomic replay guarantees remain host-owned. | -| Bounded-use behavior under tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Follow first-use, reuse-limit, stopped/cancelled, and local-state behavior without mistaking the in-memory store for distributed replay protection. | -| Production-oriented capability hardening | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Review execution-boundary profiles, proof handling, binding checks, clock skew, failure behavior, bounded use, and the explicit boundary between capability validation and host authorization/execution. | -| Proof trust narrowing | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-proof-trust-pinning.md) | See how a host can narrow which otherwise valid signing authority is acceptable for a particular capability-validation context. | -| Host-owned execution lifecycle | [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | Follow the broader governed lifecycle and observe that execution remains deliberately outside the governance spine and under host control. | +| Narrow, short-lived execution authority | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | Compare the tutorial's compact `ExecutionCapability` with the provider-neutral grant metadata for issuer, audience, scopes, time bounds, subject, operation, policy identity, acknowledgment/handshake references, gateway binding, and resource binding. | +| Execution-boundary versus metadata-only validation | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | Compare `CreateExecutionBoundary(...)`, which requires proof and bounded-use validation by default, with the deliberately weaker `CreateMetadataValidation(...)` profile. | +| Capability validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Follow proof verification, issuer/audience checks, time bounds, scopes, policy identity, acknowledgment/handshake references, gateway/resource bindings, and optional bounded-use state before a result can allow continuation. | +| Execution-profile behavior under tests | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | Inspect executable cases for strict execution-boundary defaults, metadata-only behavior, proof failure, unavailable use-state, binding mismatches, expiration, policy evidence, and validation outcomes. | +| Bounded-use and replay-state seam | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Compare the provider-neutral host contract with the explicitly local in-memory reference implementation. Durable, distributed, atomic replay guarantees remain host-owned. | +| Bounded-use behavior under tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Follow first-use, reuse-limit, stopped/cancelled, and local-state behavior without mistaking the in-memory store for distributed replay protection. | +| Production-oriented capability hardening | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Review execution-boundary profiles, proof handling, binding checks, clock skew, failure behavior, bounded use, and the explicit boundary between capability validation and host authorization/execution. | +| Proof trust narrowing | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-proof-trust-pinning.md) | See how a host can narrow which otherwise valid signing authority is acceptable for a particular capability-validation context. | +| Host-owned execution lifecycle | [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | Follow the broader governed lifecycle and observe that execution remains deliberately outside the governance spine and under host control. | ### Follow the Capability Path For a code-first inspection, follow these references in order: -1. [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — begin with the provider-neutral description of narrow follow-on authority. -2. [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) — inspect how the host declares whether it is performing strict execution-boundary validation or intentionally weaker metadata validation. -3. [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — follow the configured proof, time, scope, policy, acknowledgment, gateway, resource, and use-state checks. -4. [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) — compare the API surface with executable allow, deny, and defer behavior. -5. [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — continue into bounded-use state while keeping production persistence and concurrency guarantees host-owned. -6. [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — put those source types back into their production-oriented security and failure-handling context. -7. [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — finish at the broader lifecycle and the boundary where the host performs the real side effect. +1. [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — begin with the provider-neutral description of narrow follow-on authority. +2. [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) — inspect how the host declares whether it is performing strict execution-boundary validation or intentionally weaker metadata validation. +3. [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — follow the configured proof, time, scope, policy, acknowledgment, gateway, resource, and use-state checks. +4. [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) — compare the API surface with executable allow, deny, and defer behavior. +5. [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — continue into bounded-use state while keeping production persistence and concurrency guarantees host-owned. +6. [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — put those source types back into their production-oriented security and failure-handling context. +7. [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — finish at the broader lifecycle and the boundary where the host performs the real side effect. ### Teaching Model Versus Working Framework @@ -1448,7 +1448,7 @@ Execution gateway validates capability ↓ Host invokes tool ↓ -Audit residue +Decision receipt ``` Example: @@ -1563,7 +1563,7 @@ Execution-boundary validation ↓ Host invokes tool ↓ -Audit residue +Decision receipt ``` The fifth tutorial is therefore not a new architectural primitive. @@ -1575,7 +1575,7 @@ It is the first full composition of the primitives established so far. - [Foundational Tutorial Index](index.md) — view the complete five-tutorial governed-execution learning path. - [Do You Need a Capability Token, or Are Roles and Claims Enough?](../articles/2026/roles-claims-or-capability-token-dotnet.md) — use a scenario-driven selection guide before introducing capability infrastructure where roles, claims, or immediate host authorization may already be enough. - [Decision Before Execution](decision-before-execution.md) — revisit the foundational boundary between a proposed operation, a governance decision, and the host-owned side effect. -- [Acknowledgment and Audit Residue](acknowledgment-and-audit-residue.md) — review the responsibility and evidence boundaries that may precede issuance of execution authority. +- [Decision Receipts and Acknowledgment](decision-receipts-and-acknowledgment.md) — review the responsibility and evidence boundaries that may precede issuance of execution authority. - [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) — revisit the policy facts, outcome semantics, and policy identity that justify a scoped capability. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — go deeper on durable replay state, atomic consumption, distributed races, idempotency, and execution failure windows. - [Governed Agent-to-Agent Requests and Multi-Agent Execution Boundaries](../advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md) — explore the experimental delegation rule that derived authority must not silently become broader than its source authority. diff --git a/docs/tutorials/toc.yml b/docs/tutorials/toc.yml index 29cfb9f..92ece57 100644 --- a/docs/tutorials/toc.yml +++ b/docs/tutorials/toc.yml @@ -7,8 +7,8 @@ - name: Policy Context and Explicit Decision Outcomes href: policy-context-and-explicit-decision-outcomes.md -- name: Acknowledgment and Audit Residue - href: acknowledgment-and-audit-residue.md +- name: Decision Receipts and Acknowledgment + href: decision-receipts-and-acknowledgment.md - name: Scoped Capability and Host-Owned Execution href: scoped-capability-and-host-owned-execution.md diff --git a/samples/README.md b/samples/README.md index 33f006f..5f39ea5 100644 --- a/samples/README.md +++ b/samples/README.md @@ -1,6 +1,6 @@ -# ASI Backbone Learning Samples +# AsiBackbone Learning Samples -The `samples/` directory is the executable companion-code area for **ASI Backbone Learning**. +The `samples/` directory is the executable companion-code area for **AsiBackbone Learning**. 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. @@ -154,15 +154,15 @@ Escalate It should make information such as actor, resource, operation, and environment visible rather than hiding policy inputs throughout application code. -### Acknowledgment and Audit Residue +### Decision Receipts and Acknowledgment Related tutorial: -[Acknowledgment and Audit Residue](../docs/tutorials/acknowledgment-and-audit-residue.md) +[Decision Receipts and Acknowledgment](../docs/tutorials/decision-receipts-and-acknowledgment.md) Executable companion: -[Acknowledgment and Audit Residue sample](acknowledgment-and-audit-residue/README.md) +[Decision Receipts and Acknowledgment sample](decision-receipts-and-acknowledgment/README.md) The sample demonstrates a workflow that can pause for explicit acknowledgment while preserving evidence of the governed path. @@ -185,7 +185,7 @@ The sample makes these concerns visible: * Re-evaluation * Reason codes * Correlation -* Audit residue +* Decision receipt ### Scoped Capability and Host-Owned Execution @@ -264,7 +264,7 @@ Execution-Boundary Validation ↓ Host-Owned Dry-Run Tool Execution ↓ -Audit Residue +Decision Receipt ``` Important invariants include: @@ -586,7 +586,7 @@ The sample uses an in-memory append store to isolate deterministic canonicalizat Its central evidence boundary is: ```text -Governance receipts +Decision receipts ↓ Canonical record fingerprints ↓ @@ -1009,7 +1009,7 @@ Provides fuller governance and policy-control implementations, including areas s * Policy evaluation * Structured decisions * Acknowledgment workflows -* Audit residue +* Decision receipt * Capability boundaries * Host-owned execution * AI governance scenarios @@ -1034,7 +1034,7 @@ Learning samples should remain smaller than these repositories by design. ## Licensing -ASI Backbone Learning uses component-specific licensing. +AsiBackbone Learning uses component-specific licensing. Executable source code and sample projects added under `samples/` are licensed under the **MIT License** unless otherwise noted. diff --git a/samples/Samples.slnx b/samples/Samples.slnx index e6bbe18..704403a 100644 --- a/samples/Samples.slnx +++ b/samples/Samples.slnx @@ -1,6 +1,6 @@ - - + + diff --git a/samples/decision-before-execution/README.md b/samples/decision-before-execution/README.md index d2d38c2..fd0271c 100644 --- a/samples/decision-before-execution/README.md +++ b/samples/decision-before-execution/README.md @@ -99,10 +99,10 @@ Useful experiments include: - [Decision Before Execution tutorial](../../docs/tutorials/decision-before-execution.md) - [Decision Before Execution beginner lab](../../docs/labs/decision-before-execution.md) - [Policy Context and Explicit Decision Outcomes](../../docs/tutorials/policy-context-and-explicit-decision-outcomes.md) -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - compare the teaching decision model with the fuller framework decision type. -- [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) - inspect fuller policy and constraint evaluation. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) - follow the production-oriented execution-boundary guidance. -- [Plain ASP.NET Core Host](https://github.com/AsiBackbone/AsiBackbone/tree/main/samples/PlainAspNetCoreHost) - inspect a concrete host integration. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - compare the teaching decision model with the fuller framework decision type. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller policy and constraint evaluation. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) - follow the production-oriented execution-boundary guidance. +- [Plain ASP.NET Core Host](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/samples/PlainAspNetCoreHost) - inspect a concrete host integration. ## License diff --git a/samples/acknowledgment-and-audit-residue/README.md b/samples/decision-receipts-and-acknowledgment/README.md similarity index 72% rename from samples/acknowledgment-and-audit-residue/README.md rename to samples/decision-receipts-and-acknowledgment/README.md index 8e5fa2a..c0bc894 100644 --- a/samples/acknowledgment-and-audit-residue/README.md +++ b/samples/decision-receipts-and-acknowledgment/README.md @@ -1,6 +1,6 @@ -# Acknowledgment and Audit Residue Sample +# Decision Receipts and Acknowledgment Sample -This executable companion sample demonstrates the architectural boundary taught in the [Acknowledgment and Audit Residue](../../docs/tutorials/acknowledgment-and-audit-residue.md) tutorial. +This executable companion sample demonstrates the architectural boundary taught in the [Decision Receipts and Acknowledgment](../../docs/tutorials/decision-receipts-and-acknowledgment.md) tutorial. The sample makes the acknowledgment lifecycle and its evidence visible: @@ -11,6 +11,8 @@ Policy evaluation ↓ AcknowledgmentRequired ↓ +Decision receipt + ↓ Challenge issued ↓ Actor response @@ -21,9 +23,11 @@ Current context reconstructed ↓ Policy re-evaluated ↓ +Fresh decision receipt + ↓ Host-owned execution or stop ↓ -Audit residue +Correlated lifecycle evidence ``` The central invariants are: @@ -53,7 +57,7 @@ Intermediate From the repository root: ```bash -dotnet run --project samples/acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj +dotnet run --project samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj ``` ## Run the Tests @@ -61,7 +65,7 @@ dotnet run --project samples/acknowledgment-and-audit-residue/Sample/Acknowledgm From the repository root: ```bash -dotnet test samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj +dotnet test samples/decision-receipts-and-acknowledgment/Tests/DecisionReceiptsAndAcknowledgment.Tests.csproj ``` The focused xUnit tests cover every policy outcome and acknowledgment binding failure, including the expiration boundary and stable reason codes. They also prove that acknowledgment does not grant execution authority, changed resource state can still block execution, and the executable scenarios preserve their correlated audit timelines. @@ -139,7 +143,7 @@ The context-drift scenario changes the resource to protected after acknowledgmen ### 4. Correlation Connects the Timeline -Every `AuditResidue` for a scenario carries the same correlation identifier. +Every lifecycle event for a scenario carries the same correlation identifier, and decision-derived events reference a distinct `DecisionReceipt`. A successful flow produces stages such as: @@ -155,7 +159,7 @@ A rejected or invalid response stops earlier and therefore leaves a shorter time ### 5. Policy Identity Remains Visible -The sample carries `PolicyVersion` through the challenge and audit residue. +The sample carries `PolicyVersion` through the challenge and each decision receipt. This keeps policy identity connected to the governed path without implying that version metadata alone creates tamper-evident proof. @@ -170,20 +174,22 @@ It checks that: 3. An expired challenge produces zero executor invocations. 4. A valid acknowledgment can continue only after re-evaluation. 5. A newly active protected-resource constraint still blocks execution after acknowledgment. -6. Every residue in one workflow preserves the same correlation identifier. +6. Every lifecycle event in one workflow preserves the same correlation identifier. 7. The audit stage sequence matches the expected lifecycle. The runtime checks remain useful because they make failures visible while learners execute the demonstration directly. The companion xUnit project now provides structured test results for the same class of architectural invariants and is included in the shared sample solution for CI execution. -## Audit Residue Is Not the Same as Logging +## Decision Receipt Is Not the Same as Logging The sample prints the timeline to the console so the learner can observe it. That console output is not presented as durable governance evidence. -The `AuditResidue` objects model evidence-oriented data such as: +The `DecisionReceipt` objects record evaluation outcomes and reasons. Separate `GovernanceLifecycleEvent` objects correlate acknowledgment and execution progress without implying that the original decision proves execution. + +The combined evidence includes: - Event identity - Actor @@ -194,7 +200,7 @@ The `AuditResidue` objects model evidence-oriented data such as: - Policy version - Lifecycle stage -A production system would still need to decide how residue is persisted, protected, retained, delivered, and possibly signed. +A production system would still need to decide how receipts and lifecycle events are persisted, protected, retained, delivered, and possibly signed. Do not infer from this sample that an in-memory list or console output is: @@ -233,21 +239,22 @@ Useful experiments include: 2. Change the response correlation identifier and add a scenario for `acknowledgment.correlation-mismatch`. 3. Add a one-time challenge-consumption flag and demonstrate why replay state needs persistence. 4. Add a policy version change between challenge issuance and acknowledgment, then decide whether the host should reject or re-evaluate under the new policy. -5. Add a durable `IAuditResidueStore` abstraction backed by an in-memory implementation. -6. Simulate an execution failure and add a distinct `execution-failed` residue instead of rewriting the `Allowed` decision. +5. Add a durable `IDecisionReceiptStore` abstraction backed by an in-memory implementation. +6. Simulate an execution failure and add a distinct `execution-failed` lifecycle event instead of rewriting the `Allowed` decision receipt. 7. Add a policy hash or fingerprint and discuss what additional architecture is required before calling the resulting history tamper-evident. ## Related Material -- [Acknowledgment and Audit Residue tutorial](../../docs/tutorials/acknowledgment-and-audit-residue.md) -- [Acknowledgment and Audit Residue intermediate lab](../../docs/labs/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment tutorial](../../docs/tutorials/decision-receipts-and-acknowledgment.md) +- [Decision Receipts and Acknowledgment intermediate lab](../../docs/labs/decision-receipts-and-acknowledgment.md) - [Policy Context and Explicit Decision Outcomes sample](../policy-context-and-explicit-decision-outcomes/README.md) - [Scoped Capability and Host-Owned Execution](../../docs/tutorials/scoped-capability-and-host-owned-execution.md) -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) - compare the teaching challenge with the fuller working handshake request. -- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) - inspect the working acknowledgment model. -- [`AuditResidue`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) - compare the small teaching residue with the framework's richer governance evidence model. -- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) - review the fuller handshake lifecycle. -- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) - review production-oriented persistence and delivery concerns. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) - compare the teaching challenge with the fuller working handshake request. +- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) - inspect the working acknowledgment model. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) - compare the small teaching receipt with the framework's decision-outcome record. +- [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) - compare the sample's correlated lifecycle events with the framework's acknowledgment, capability, gateway, and emission stages. +- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) - review the fuller handshake lifecycle. +- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) - review production-oriented persistence and delivery concerns. ## License diff --git a/samples/acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj b/samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj similarity index 100% rename from samples/acknowledgment-and-audit-residue/Sample/AcknowledgmentAndAuditResidue.csproj rename to samples/decision-receipts-and-acknowledgment/Sample/DecisionReceiptsAndAcknowledgment.csproj diff --git a/samples/acknowledgment-and-audit-residue/Sample/Program.cs b/samples/decision-receipts-and-acknowledgment/Sample/Program.cs similarity index 87% rename from samples/acknowledgment-and-audit-residue/Sample/Program.cs rename to samples/decision-receipts-and-acknowledgment/Sample/Program.cs index a8289de..9449ae5 100644 --- a/samples/acknowledgment-and-audit-residue/Sample/Program.cs +++ b/samples/decision-receipts-and-acknowledgment/Sample/Program.cs @@ -79,7 +79,7 @@ ]) ]; -Console.WriteLine("Acknowledgment and Audit Residue"); +Console.WriteLine("Decision Receipts and Acknowledgment"); Console.WriteLine(new string('=', 34)); Console.WriteLine(); @@ -102,20 +102,20 @@ Console.WriteLine($"Final state: {result.FinalState}"); Console.WriteLine($"Last decision: {result.LastDecision.Outcome}"); Console.WriteLine($"Executor invocations: {executor.InvocationCount}"); - Console.WriteLine("Audit timeline:"); + Console.WriteLine("Evidence timeline:"); - foreach (AuditResidue residue in result.AuditTrail) + foreach (GovernanceLifecycleEvent receipt in result.EvidenceTrail) { Console.WriteLine( - $" {residue.Sequence,2}. {residue.Stage,-25} " + - $"outcome={residue.Outcome,-28} " + - $"reasons={FormatReasons(residue.ReasonCodes)}"); + $" {receipt.Sequence,2}. {receipt.Stage,-25} " + + $"outcome={receipt.Outcome,-28} " + + $"reasons={FormatReasons(receipt.ReasonCodes)}"); } Console.WriteLine( "Correlation preserved: " + - result.AuditTrail.All( - residue => residue.CorrelationId == + result.EvidenceTrail.All( + receipt => receipt.CorrelationId == scenario.Context.CorrelationId)); Console.WriteLine(); } @@ -135,12 +135,12 @@ static WorkflowResult RunScenario( DateTimeOffset nowUtc = new(2026, 8, 13, 19, 0, 0, TimeSpan.Zero); - var audit = new List(); + var evidence = new List(); DisableAccountPolicyContext context = scenario.Context; GovernanceDecision decision = DisableAccountPolicy.Evaluate(context); - AddDecisionResidue( - audit, + AddDecisionReceipt( + evidence, nowUtc, context, decision, @@ -152,7 +152,7 @@ static WorkflowResult RunScenario( return new WorkflowResult( "BlockedByInitialDecision", decision, - audit); + evidence); } AcknowledgmentChallenge challenge = @@ -162,8 +162,8 @@ static WorkflowResult RunScenario( nowUtc); nowUtc = nowUtc.AddSeconds(1); - AddResidue( - audit, + AddLifecycleEvent( + evidence, nowUtc, context, outcome: "ChallengeIssued", @@ -192,8 +192,8 @@ static WorkflowResult RunScenario( if (!response.Accepted) { - AddResidue( - audit, + AddLifecycleEvent( + evidence, responseUtc, context, outcome: "AcknowledgmentRejected", @@ -204,13 +204,13 @@ static WorkflowResult RunScenario( return new WorkflowResult( "AcknowledgmentRejected", decision, - audit); + evidence); } if (!validation.IsValid) { - AddResidue( - audit, + AddLifecycleEvent( + evidence, responseUtc, context, outcome: "AcknowledgmentInvalid", @@ -221,11 +221,11 @@ static WorkflowResult RunScenario( return new WorkflowResult( "AcknowledgmentInvalid", decision, - audit); + evidence); } - AddResidue( - audit, + AddLifecycleEvent( + evidence, responseUtc, context, outcome: "AcknowledgmentAccepted", @@ -248,8 +248,8 @@ static WorkflowResult RunScenario( decision = DisableAccountPolicy.Evaluate(context); nowUtc = responseUtc.AddSeconds(1); - AddDecisionResidue( - audit, + AddDecisionReceipt( + evidence, nowUtc, context, decision, @@ -260,13 +260,13 @@ static WorkflowResult RunScenario( return new WorkflowResult( "BlockedAfterReevaluation", decision, - audit); + evidence); } executor.Execute(context.Intent); - AddResidue( - audit, + AddLifecycleEvent( + evidence, nowUtc.AddSeconds(1), context, outcome: "Executed", @@ -276,7 +276,7 @@ static WorkflowResult RunScenario( return new WorkflowResult( "Executed", decision, - audit); + evidence); } static DisableAccountPolicyContext CreateContext( @@ -342,15 +342,28 @@ static AcknowledgmentResponse CreateResponse( CorrelationId: challenge.CorrelationId); } -static void AddDecisionResidue( - List audit, +static void AddDecisionReceipt( + List evidence, DateTimeOffset occurredUtc, DisableAccountPolicyContext context, GovernanceDecision decision, string stage) { - AddResidue( - audit, + var receipt = new DecisionReceipt( + ReceiptId: $"{context.CorrelationId}-{stage}", + OccurredUtc: occurredUtc, + ActorId: context.Actor.ActorId, + OperationName: "account.disable", + Outcome: decision.Outcome.ToString(), + ReasonCodes: + decision.Reasons + .Select(reason => reason.Code) + .ToArray(), + CorrelationId: context.CorrelationId, + PolicyVersion: context.PolicyVersion); + + AddLifecycleEvent( + evidence, occurredUtc, context, outcome: decision.Outcome.ToString(), @@ -358,22 +371,24 @@ static void AddDecisionResidue( decision.Reasons .Select(reason => reason.Code) .ToArray(), - stage: stage); + stage: stage, + decisionReceipt: receipt); } -static void AddResidue( - List audit, +static void AddLifecycleEvent( + List evidence, DateTimeOffset occurredUtc, DisableAccountPolicyContext context, string outcome, IReadOnlyList reasonCodes, string stage, - string? actorId = null) + string? actorId = null, + DecisionReceipt? decisionReceipt = null) { - int sequence = audit.Count + 1; + int sequence = evidence.Count + 1; - audit.Add( - new AuditResidue( + evidence.Add( + new GovernanceLifecycleEvent( Sequence: sequence, EventId: $"{context.CorrelationId}-event-{sequence:00}", @@ -384,7 +399,8 @@ static void AddResidue( ReasonCodes: reasonCodes, CorrelationId: context.CorrelationId, PolicyVersion: context.PolicyVersion, - Stage: stage)); + Stage: stage, + DecisionReceipt: decisionReceipt)); } static void VerifyScenario( @@ -417,22 +433,22 @@ static void VerifyScenario( $"but observed {executorInvocations}."); } - string[] stages = [.. result.AuditTrail.Select(residue => residue.Stage)]; + string[] stages = [.. result.EvidenceTrail.Select(receipt => receipt.Stage)]; if (!stages.SequenceEqual( scenario.ExpectedStages, StringComparer.Ordinal)) { throw new InvalidOperationException( - $"Scenario '{scenario.Name}' produced an unexpected audit timeline."); + $"Scenario '{scenario.Name}' produced an unexpected evidence timeline."); } - if (result.AuditTrail.Any( - residue => residue.CorrelationId != + if (result.EvidenceTrail.Any( + receipt => receipt.CorrelationId != scenario.Context.CorrelationId)) { throw new InvalidOperationException( - $"Scenario '{scenario.Name}' lost correlation across its audit timeline."); + $"Scenario '{scenario.Name}' lost correlation across its evidence timeline."); } } @@ -457,7 +473,7 @@ public sealed record WorkflowScenario( public sealed record WorkflowResult( string FinalState, GovernanceDecision LastDecision, - IReadOnlyList AuditTrail); + IReadOnlyList EvidenceTrail); public enum ResponseMode { @@ -635,7 +651,7 @@ public static AcknowledgmentValidation Validate( } } -public sealed record AuditResidue( +public sealed record GovernanceLifecycleEvent( int Sequence, string EventId, DateTimeOffset OccurredUtc, @@ -645,7 +661,18 @@ public sealed record AuditResidue( IReadOnlyList ReasonCodes, string CorrelationId, string PolicyVersion, - string Stage); + string Stage, + DecisionReceipt? DecisionReceipt); + +public sealed record DecisionReceipt( + string ReceiptId, + DateTimeOffset OccurredUtc, + string ActorId, + string OperationName, + string Outcome, + IReadOnlyList ReasonCodes, + string CorrelationId, + string PolicyVersion); public sealed class RecordingExecutor { diff --git a/samples/acknowledgment-and-audit-residue/Sample/packages.lock.json b/samples/decision-receipts-and-acknowledgment/Sample/packages.lock.json similarity index 100% rename from samples/acknowledgment-and-audit-residue/Sample/packages.lock.json rename to samples/decision-receipts-and-acknowledgment/Sample/packages.lock.json diff --git a/samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentBoundaryTests.cs b/samples/decision-receipts-and-acknowledgment/Tests/AcknowledgmentBoundaryTests.cs similarity index 95% rename from samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentBoundaryTests.cs rename to samples/decision-receipts-and-acknowledgment/Tests/AcknowledgmentBoundaryTests.cs index 552854d..2912e58 100644 --- a/samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentBoundaryTests.cs +++ b/samples/decision-receipts-and-acknowledgment/Tests/AcknowledgmentBoundaryTests.cs @@ -1,6 +1,6 @@ using Xunit; -namespace AcknowledgmentAndAuditResidue.Tests; +namespace DecisionReceiptsAndAcknowledgment.Tests; public sealed class AcknowledgmentBoundaryTests { @@ -290,24 +290,22 @@ public void SuppliedReasonAllowsRequestWithoutReasonCodes() } [Fact] - public void AuditResidueKeepsLifecycleIdentityExplicit() + public void DecisionReceiptKeepsDecisionIdentityExplicit() { - var residue = new AuditResidue( - Sequence: 2, - EventId: "test-user-100-event-02", + var receipt = new DecisionReceipt( + ReceiptId: "test-user-100-decision", OccurredUtc: _nowUtc, ActorId: "operator-7", OperationName: "account.disable", - Outcome: "AcknowledgmentAccepted", - ReasonCodes: ["account.disable.reason-required", "acknowledgment.accepted"], + Outcome: "AcknowledgmentRequired", + ReasonCodes: ["account.disable.reason-required"], CorrelationId: "test-user-100", - PolicyVersion: "3.2", - Stage: "acknowledgment-accepted"); + PolicyVersion: "3.2"); - Assert.Equal("test-user-100", residue.CorrelationId); - Assert.Equal("3.2", residue.PolicyVersion); - Assert.Equal("acknowledgment-accepted", residue.Stage); - Assert.Equal(2, residue.ReasonCodes.Count); + Assert.Equal("test-user-100", receipt.CorrelationId); + Assert.Equal("3.2", receipt.PolicyVersion); + Assert.Equal("AcknowledgmentRequired", receipt.Outcome); + Assert.Single(receipt.ReasonCodes); } [Fact] diff --git a/samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj b/samples/decision-receipts-and-acknowledgment/Tests/DecisionReceiptsAndAcknowledgment.Tests.csproj similarity index 86% rename from samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj rename to samples/decision-receipts-and-acknowledgment/Tests/DecisionReceiptsAndAcknowledgment.Tests.csproj index f9f2590..e1ac06a 100644 --- a/samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj +++ b/samples/decision-receipts-and-acknowledgment/Tests/DecisionReceiptsAndAcknowledgment.Tests.csproj @@ -15,7 +15,7 @@ - + diff --git a/samples/acknowledgment-and-audit-residue/Tests/packages.lock.json b/samples/decision-receipts-and-acknowledgment/Tests/packages.lock.json similarity index 99% rename from samples/acknowledgment-and-audit-residue/Tests/packages.lock.json rename to samples/decision-receipts-and-acknowledgment/Tests/packages.lock.json index 34eecb7..9cc3e1b 100644 --- a/samples/acknowledgment-and-audit-residue/Tests/packages.lock.json +++ b/samples/decision-receipts-and-acknowledgment/Tests/packages.lock.json @@ -163,9 +163,9 @@ "xunit.v3.runner.common": "[4.0.0]" } }, - "acknowledgmentandauditresidue": { + "decisionreceiptsandacknowledgment": { "type": "Project" } } } -} \ No newline at end of file +} diff --git a/samples/durable-decision-ledger-audit-chain/README.md b/samples/durable-decision-ledger-audit-chain/README.md index e68b5cf..6e22a94 100644 --- a/samples/durable-decision-ledger-audit-chain/README.md +++ b/samples/durable-decision-ledger-audit-chain/README.md @@ -33,10 +33,10 @@ dotnet test samples/Samples.slnx ## What the Console Demonstrates -The console appends two governance receipts, retries the first logical append, captures a checkpoint at the current head, and then verifies several views: +The console appends two decision receipts, retries the first logical append, captures a checkpoint at the current head, and then verifies several views: ```text -Governance receipts +Decision receipts ↓ Deterministic canonical bytes ↓ diff --git a/samples/governed-ai-tool-gateway/README.md b/samples/governed-ai-tool-gateway/README.md index 735011c..4ce6b82 100644 --- a/samples/governed-ai-tool-gateway/README.md +++ b/samples/governed-ai-tool-gateway/README.md @@ -44,7 +44,7 @@ Execution-boundary validation ↓ Host-owned dry-run handler ↓ -Audit residue +Decision receipt ``` The sample deliberately keeps the proposer and executor separate. @@ -389,7 +389,7 @@ Policy version where recorded Acknowledgment challenge identity Capability identity Executor invocation -Audit residue +Decision receipt ``` The sample deliberately preserves this distinction: @@ -489,15 +489,15 @@ The sample exists to make the **ordering and ownership of authority** observable Compare the small teaching implementation with the fuller working `AsiBackbone` repository: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) -- [GovernanceDecision](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) -- [AuditResidue](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditResidue.cs) -- [CapabilityTokenGrant](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) -- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/README.md) -- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) -- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) +- [GovernanceDecision](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) +- [DecisionReceipt](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) +- [CapabilityTokenGrant](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/README.md) +- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) +- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) The Learning sample remains framework-neutral so the architectural pattern can be studied independently of package adoption. diff --git a/samples/governed-ai-tool-gateway/Sample/GovernanceObservability.cs b/samples/governed-ai-tool-gateway/Sample/GovernanceObservability.cs index c80735a..a17e105 100644 --- a/samples/governed-ai-tool-gateway/Sample/GovernanceObservability.cs +++ b/samples/governed-ai-tool-gateway/Sample/GovernanceObservability.cs @@ -59,26 +59,26 @@ public static class GovernanceObservabilityInstrumentation return activity; } - public static void RecordAuditEvent(AuditResidue residue) + public static void RecordAuditEvent(DecisionReceipt receipt) { var tags = new ActivityTagsCollection { - { CorrelationIdTagName, residue.CorrelationId }, - { "governance.stage", residue.Stage }, - { "governance.outcome", residue.Outcome }, - { "governance.reason_code", residue.ReasonCode } + { CorrelationIdTagName, receipt.CorrelationId }, + { "governance.stage", receipt.Stage }, + { "governance.outcome", receipt.Outcome }, + { "governance.reason_code", receipt.ReasonCode } }; - if (!string.IsNullOrWhiteSpace(residue.PolicyVersion)) + if (!string.IsNullOrWhiteSpace(receipt.PolicyVersion)) { tags.Add( "governance.policy.version", - residue.PolicyVersion); + receipt.PolicyVersion); } Activity.Current?.AddEvent( new ActivityEvent( - $"governance.{residue.Stage}", + $"governance.{receipt.Stage}", tags: tags)); } } @@ -233,7 +233,7 @@ public sealed record GovernanceObservabilityRun( GatewayResult Result, int ExecutorInvocationCount, IReadOnlyList Activities, - IReadOnlyList AuditEntries); + IReadOnlyList AuditEntries); public static class GovernanceObservabilityRunner { @@ -319,7 +319,7 @@ public static async Task RunAsync( host.Handler.InvocationCount); } - AuditResidue[] auditEntries = [.. host.AuditSink.Entries + DecisionReceipt[] auditEntries = [.. host.AuditSink.Entries .Where(entry => string.Equals( entry.CorrelationId, correlationId, @@ -431,12 +431,12 @@ await GovernanceObservabilityRunner.RunAsync( Console.WriteLine("Audit evidence:"); - foreach (AuditResidue residue in run.AuditEntries) + foreach (DecisionReceipt receipt in run.AuditEntries) { Console.WriteLine( - $"- {residue.Stage}: {residue.Outcome} " + - $"({residue.ReasonCode}) " + - $"policy={residue.PolicyVersion ?? "-"}"); + $"- {receipt.Stage}: {receipt.Outcome} " + + $"({receipt.ReasonCode}) " + + $"policy={receipt.PolicyVersion ?? "-"}"); } Console.WriteLine(); diff --git a/samples/governed-ai-tool-gateway/Sample/Program.cs b/samples/governed-ai-tool-gateway/Sample/Program.cs index ef201ab..36477c1 100644 --- a/samples/governed-ai-tool-gateway/Sample/Program.cs +++ b/samples/governed-ai-tool-gateway/Sample/Program.cs @@ -105,14 +105,14 @@ Console.WriteLine("Observed audit stages for the acknowledged proposal:"); -foreach (AuditResidue residue in host.AuditSink.Entries.Where( +foreach (DecisionReceipt receipt in host.AuditSink.Entries.Where( entry => string.Equals( entry.CorrelationId, externalProposal.ProposalId, StringComparison.Ordinal))) { Console.WriteLine( - $"- {residue.Stage}: {residue.Outcome} ({residue.ReasonCode})"); + $"- {receipt.Stage}: {receipt.Outcome} ({receipt.ReasonCode})"); } Console.WriteLine(); @@ -741,7 +741,7 @@ public void Reset() } } -public sealed record AuditResidue( +public sealed record DecisionReceipt( string CorrelationId, string Stage, string Outcome, @@ -750,9 +750,9 @@ public sealed record AuditResidue( public sealed class InMemoryAuditSink { - private readonly List _entries = []; + private readonly List _entries = []; - public IReadOnlyList Entries => _entries; + public IReadOnlyList Entries => _entries; public void Write( string correlationId, @@ -761,15 +761,15 @@ public void Write( string reasonCode, string? policyVersion = null) { - var residue = new AuditResidue( + var receipt = new DecisionReceipt( correlationId, stage, outcome, reasonCode, policyVersion); - _entries.Add(residue); - GovernanceObservabilityInstrumentation.RecordAuditEvent(residue); + _entries.Add(receipt); + GovernanceObservabilityInstrumentation.RecordAuditEvent(receipt); } } diff --git a/samples/governed-ai-tool-gateway/Tests/GovernedGatewayTests.cs b/samples/governed-ai-tool-gateway/Tests/GovernedGatewayTests.cs index 1cbf726..8a69339 100644 --- a/samples/governed-ai-tool-gateway/Tests/GovernedGatewayTests.cs +++ b/samples/governed-ai-tool-gateway/Tests/GovernedGatewayTests.cs @@ -91,7 +91,7 @@ public async Task ModelSuppliedClassificationDoesNotOverrideHostClassification() result.DecisionOutcome); Assert.Equal(0, host.Handler.InvocationCount); - AuditResidue contextEntry = Assert.Single( + DecisionReceipt contextEntry = Assert.Single( host.AuditSink.Entries, entry => entry.Stage == "context"); @@ -419,7 +419,7 @@ public async Task SuccessfulFlowPreservesCorrelationAcrossEvidenceStages() Assert.Equal(GatewayStatus.WouldExecute, result.Status); - AuditResidue[] entries = [.. host.AuditSink.Entries.Where(entry => entry.CorrelationId == proposalId)]; + DecisionReceipt[] entries = [.. host.AuditSink.Entries.Where(entry => entry.CorrelationId == proposalId)]; Assert.NotEmpty(entries); Assert.All( diff --git a/samples/policy-context-and-explicit-decision-outcomes/README.md b/samples/policy-context-and-explicit-decision-outcomes/README.md index 12e72c6..3d5392e 100644 --- a/samples/policy-context-and-explicit-decision-outcomes/README.md +++ b/samples/policy-context-and-explicit-decision-outcomes/README.md @@ -158,11 +158,11 @@ Useful experiments include: - [Policy Context and Explicit Decision Outcomes tutorial](../../docs/tutorials/policy-context-and-explicit-decision-outcomes.md) - [Policy Context and Explicit Decision Outcomes learner exercise](../../docs/labs/policy-context-and-explicit-decision-outcomes.md) - [Decision Before Execution sample](../decision-before-execution/README.md) -- [Acknowledgment and Audit Residue](../../docs/tutorials/acknowledgment-and-audit-residue.md) -- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) - compare the teaching outcome vocabulary with the working framework. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - inspect the fuller decision model, reason metadata, correlation, and policy identity. -- [`IAsiBackboneConstraintEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IAsiBackboneConstraintEvaluationContext.cs) - compare the sample snapshot with the framework's constraint-evaluation context surface. -- [`DefaultAsiBackbonePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultAsiBackbonePolicyEvaluator.cs) - inspect fuller constraint composition and decision evaluation. +- [Decision Receipts and Acknowledgment](../../docs/tutorials/decision-receipts-and-acknowledgment.md) +- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) - compare the teaching outcome vocabulary with the working framework. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - inspect the fuller decision model, reason metadata, correlation, and policy identity. +- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) - compare the sample snapshot with the framework's constraint-evaluation context surface. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller constraint composition and decision evaluation. ## License diff --git a/samples/policy-simulation-harness/README.md b/samples/policy-simulation-harness/README.md index 0701599..77b67c6 100644 --- a/samples/policy-simulation-harness/README.md +++ b/samples/policy-simulation-harness/README.md @@ -1,6 +1,6 @@ # Minimal Policy Simulation Harness Sample -This sample is an executable companion for the governance and policy architecture material in ASI Backbone Learning. +This sample is an executable companion for the governance and policy architecture material in AsiBackbone Learning. **Learning objective:** Observe how the same proposed intent can produce different structured governance decisions when authoritative policy context or the selected policy version changes, without invoking a protected executor or producing a real-world side effect. diff --git a/samples/replay-protection-and-bounded-use/README.md b/samples/replay-protection-and-bounded-use/README.md index 9150ba7..c7e3f6f 100644 --- a/samples/replay-protection-and-bounded-use/README.md +++ b/samples/replay-protection-and-bounded-use/README.md @@ -395,10 +395,10 @@ The sample stays framework-neutral so the atomic state transition remains easy t | Teaching sample | Working reference | What to inspect | | --- | --- | --- | -| `ICapabilityUseStore` | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | Provider-neutral `TryConsumeAsync` semantics and the boundary between Core behavior and host-owned durable state. | -| `AtomicInMemoryCapabilityUseStore` | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe local use counts and explicit non-durable/non-distributed limitations. | -| Concurrent invariant tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Accepted use, use limits, stop/cancel state, and local concurrency behavior. | -| `ProtectedOperationGateway` | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Static/proof validation composed with optional stateful use checking before host-owned execution. | +| `ICapabilityUseStore` | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | Provider-neutral `TryConsumeAsync` semantics and the boundary between Core behavior and host-owned durable state. | +| `AtomicInMemoryCapabilityUseStore` | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe local use counts and explicit non-durable/non-distributed limitations. | +| Concurrent invariant tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Accepted use, use limits, stop/cancel state, and local concurrency behavior. | +| `ProtectedOperationGateway` | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Static/proof validation composed with optional stateful use checking before host-owned execution. | The framework implementation remains a specimen. Durable replay guarantees are still defined by the host and selected provider. @@ -422,7 +422,7 @@ Continue with the [Replay Protection and Bounded-Use Authority lab](../../docs/l - [Scoped Capability and Host-Owned Execution sample](../scoped-capability-and-host-owned-execution/README.md) - [Data Access Boundaries and Transaction Reasoning](../../docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md) - [Governed AI Tool Gateway](../../docs/tutorials/governed-ai-tool-gateway.md) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) ## License diff --git a/samples/scoped-capability-and-host-owned-execution/README.md b/samples/scoped-capability-and-host-owned-execution/README.md index d15d589..5129a9c 100644 --- a/samples/scoped-capability-and-host-owned-execution/README.md +++ b/samples/scoped-capability-and-host-owned-execution/README.md @@ -41,7 +41,7 @@ Intermediate - .NET 10 SDK - [Decision Before Execution](../../docs/tutorials/decision-before-execution.md) - [Policy Context and Explicit Decision Outcomes](../../docs/tutorials/policy-context-and-explicit-decision-outcomes.md) -- [Acknowledgment and Audit Residue](../../docs/tutorials/acknowledgment-and-audit-residue.md) +- [Decision Receipts and Acknowledgment](../../docs/tutorials/decision-receipts-and-acknowledgment.md) ## Run the Sample @@ -205,11 +205,11 @@ This sample exposes the capability boundary with intentionally small, determinis | Teaching sample | Working reference | Important difference | | --- | --- | --- | -| `ExecutionCapability` | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | The framework grant is provider-neutral metadata and adds fields such as not-before time, policy hash, handshake reference, gateway binding, resource binding, metadata, and schema version. It is explicitly not a bearer-token format. | -| `ExecutionCapabilityValidator` | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) and [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | The framework distinguishes strict execution-boundary validation from intentionally weaker metadata validation and can add proof verification plus bounded-use checks. | -| Deterministic validation scenarios | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | The framework tests cover the richer validation surface, including proof, use-state availability, time, scope, policy, acknowledgment, gateway, and resource behavior. | -| Replay deliberately omitted from the baseline | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs), [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs), and [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | The framework provides a bounded-use seam and a local reference store, while durable distributed replay protection remains a host responsibility. | -| `DisableAccountGateway` owns the simulated side effect | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) and [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | The framework validates governance authority but deliberately does not become the external account, robotics, deployment, or tool executor. The host still owns the real action. | +| `ExecutionCapability` | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | The framework grant is provider-neutral metadata and adds fields such as not-before time, policy hash, handshake reference, gateway binding, resource binding, metadata, and schema version. It is explicitly not a bearer-token format. | +| `ExecutionCapabilityValidator` | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) and [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | The framework distinguishes strict execution-boundary validation from intentionally weaker metadata validation and can add proof verification plus bounded-use checks. | +| Deterministic validation scenarios | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | The framework tests cover the richer validation surface, including proof, use-state availability, time, scope, policy, acknowledgment, gateway, and resource behavior. | +| Replay deliberately omitted from the baseline | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs), [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs), and [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | The framework provides a bounded-use seam and a local reference store, while durable distributed replay protection remains a host responsibility. | +| `DisableAccountGateway` owns the simulated side effect | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) and [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | The framework validates governance authority but deliberately does not become the external account, robotics, deployment, or tool executor. The host still owns the real action. | The sample's `ResourceVersion` deserves special attention. It exists so a learner can observe state drift directly: @@ -234,18 +234,18 @@ Useful experiments include: 4. Change the audience to another gateway and decide whether cross-gateway reuse should be allowed. 5. Add `NotBeforeUtc` and test the exact lower time boundary. 6. Add a single-use store and demonstrate first-use success followed by replay rejection. -7. Record capability issuance and validation as distinct audit-residue events. +7. Record capability issuance and validation as distinct decision-receipt events. ## Related Material - [Scoped Capability and Host-Owned Execution tutorial](../../docs/tutorials/scoped-capability-and-host-owned-execution.md) - [Scoped Capability and Host-Owned Execution intermediate lab](../../docs/labs/scoped-capability-and-host-owned-execution.md) -- [Acknowledgment and Audit Residue sample](../acknowledgment-and-audit-residue/README.md) -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) - compare the teaching capability with the working framework's provider-neutral grant metadata. -- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) - inspect fuller execution-context validation. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) - review the working seam for bounded-use and replay-state enforcement. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) - review production-oriented proof, binding, time, replay, and failure guidance. -- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) - place capability validation in the fuller governed flow. +- [Decision Receipts and Acknowledgment sample](../decision-receipts-and-acknowledgment/README.md) +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) - compare the teaching capability with the working framework's provider-neutral grant metadata. +- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) - inspect fuller execution-context validation. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) - review the working seam for bounded-use and replay-state enforcement. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) - review production-oriented proof, binding, time, replay, and failure guidance. +- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) - place capability validation in the fuller governed flow. ## License diff --git a/tools/generate-feed.cs b/tools/generate-feed.cs index 556b605..6e6d25b 100644 --- a/tools/generate-feed.cs +++ b/tools/generate-feed.cs @@ -190,7 +190,7 @@ public static int RunSelfTest() StringComparison.Ordinal) || !string.Equals( channelImage.SelectSingleNode("title")?.InnerText, - "ASI Backbone Learning", + "AsiBackbone Learning", StringComparison.Ordinal) || !string.Equals( channelImage.SelectSingleNode("link")?.InnerText, @@ -536,11 +536,11 @@ private static void WriteFeed( writer.WriteStartElement("channel"); - writer.WriteElementString("title", "ASI Backbone Learning"); + writer.WriteElementString("title", "AsiBackbone Learning"); writer.WriteElementString("link", SiteRoot.AbsoluteUri); writer.WriteElementString( "description", - "Long-form technical articles from Accountable Systems Infrastructure (ASI) Backbone Learning on " + + "Long-form technical articles from AsiBackbone Learning on " + "governed .NET decision flow and execution, secure application architecture, AI integration, and policy-" + "driven systems."); writer.WriteElementString("language", "en-us"); @@ -550,7 +550,7 @@ private static void WriteFeed( writer.WriteStartElement("image"); writer.WriteElementString("url", FeedImageUri.AbsoluteUri); - writer.WriteElementString("title", "ASI Backbone Learning"); + writer.WriteElementString("title", "AsiBackbone Learning"); writer.WriteElementString("link", SiteRoot.AbsoluteUri); writer.WriteElementString("width", "144"); writer.WriteElementString("height", "144"); diff --git a/tools/publish-x.cs b/tools/publish-x.cs index 2761c10..3c90d51 100644 --- a/tools/publish-x.cs +++ b/tools/publish-x.cs @@ -502,7 +502,7 @@ private ProcessResult RunForResult(params string[] arguments) sealed class JackdawPatioPostComposer : IXPostComposer { private const int MaximumLength = 280; - private const string Prefix = "New from ASI Backbone Learning:\n\n"; + private const string Prefix = "New from AsiBackbone Learning:\n\n"; public string Compose(LearningPublication publication) { diff --git a/tools/validate-doc-metadata.cs b/tools/validate-doc-metadata.cs index 782772e..5665351 100644 --- a/tools/validate-doc-metadata.cs +++ b/tools/validate-doc-metadata.cs @@ -12,7 +12,7 @@ static class MetadataValidator { private const int MaximumDescriptionLength = 160; private const string SiteDescription = "Practical .NET architecture tutorials, labs, and reference patterns for governed execution, secure applications, AI integration, and policy-driven systems."; - private const string LandingPageTitle = "Governed Execution & Secure .NET Architecture Tutorials | ASI Backbone Learning"; + private const string LandingPageTitle = "Governed Execution & Secure .NET Architecture Tutorials | AsiBackbone Learning"; private static readonly Uri SiteRoot = new("https://asibackbone.github.io/Learning/"); private static readonly Uri FeedUri = new(SiteRoot, "feed.xml"); @@ -27,7 +27,7 @@ static class MetadataValidator RegexOptions.IgnoreCase | RegexOptions.Compiled); private static readonly Regex RssAutodiscoveryRegex = new( - "[^\"]+)\">", + "[^\"]+)\">", RegexOptions.IgnoreCase | RegexOptions.Compiled); private static readonly Regex OpenGraphUrlRegex = new( @@ -489,7 +489,7 @@ private static void ValidateLandingPage(string outputRoot, ICollection e errors.Add($"{relativePath}: disabled landing-page TOC must not trigger a second toc.json request."); } - int headingIndex = html.IndexOf("

    ", StringComparison.Ordinal); + int headingIndex = html.IndexOf("

    ", StringComparison.Ordinal); int actionsIndex = html.IndexOf("
    = 0 ? html.IndexOf(" Date: Fri, 18 Sep 2026 07:00:29 -0500 Subject: [PATCH 02/10] docs: validate AsiBackbone 6.0 API references (#344) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #340 ## Summary - add a canonical AsiBackbone 6.0 API boundary guide with finalized core names, namespaces, evaluator construction, endpoint markers, and all seven removed compatibility members - clearly distinguish Learning-owned framework-neutral teaching models from exact package API examples, including ambiguous receipt and acknowledgment snippets - document that current executable samples intentionally have no AsiBackbone package references; future package-integration samples must pin and lock a released 6.x version - add a CI validator covering all 102 upstream type renames, removed API names, implementation links outside release/6.0.0, code-scope notices, and future AsiBackbone package versions ## Upstream baseline reviewed - AsiBackbone/AsiBackbone#785 — obsolete API removals - AsiBackbone/AsiBackbone#786 — complete public API naming inventory - AsiBackbone/AsiBackbone#787 — finalized terminology - release/6.0.0 migration guide and source tree ## Validation - `dotnet restore Samples.slnx --locked-mode` - `dotnet build Samples.slnx --no-restore` (0 warnings, 0 errors) - `dotnet format Samples.slnx --verify-no-changes --no-restore --verbosity minimal` - `dotnet test Samples.slnx --no-build` (300 passed) - AsiBackbone 6.0 API-reference validator (348 instructional files) - `dotnet tool run docfx docs/docfx.json --warningsAsErrors` (0 warnings, 0 errors) - DocFX template baseline, metadata, sitemap, IndexNow, feed, and X publisher validation - Lychee link validation (2,801 OK, 0 errors, 3 configured exclusions) --- .github/workflows/docs-validation.yml | 4 + README.md | 2 + ...knowledgment-and-continuation-workflows.md | 2 + ...ss-boundaries-and-transaction-reasoning.md | 12 +- .../governed-administrative-operation.md | 2 + .../human-acknowledgment-workflow.md | 1 + .../asibackbone-6-api-boundary.md | 144 ++++++ docs/getting-started/index.md | 3 + docs/getting-started/toc.yml | 2 + docs/labs/build-a-governed-api-operation.md | 1 + docs/samples/index.md | 2 + docs/tutorials/index.md | 2 + samples/README.md | 2 + .../validate-asibackbone-6-api-references.cs | 423 ++++++++++++++++++ 14 files changed, 597 insertions(+), 5 deletions(-) create mode 100644 docs/getting-started/asibackbone-6-api-boundary.md create mode 100644 tools/validate-asibackbone-6-api-references.cs diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml index c5de426..072f03c 100644 --- a/.github/workflows/docs-validation.yml +++ b/.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 diff --git a/README.md b/README.md index afc8c9c..a5f4042 100644 --- a/README.md +++ b/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. diff --git a/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md b/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md index 3bd56df..172c8fb 100644 --- a/docs/advanced/distributed-acknowledgment-and-continuation-workflows.md +++ b/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, diff --git a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md b/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md index 4861b09..c51a545 100644 --- a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md +++ b/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 FindForDisableAsync(...) ValueTask 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 TryStartAsync( string capabilityId, - DecisionReceipt executionStart, + LearningDecisionReceipt executionStart, CancellationToken cancellationToken) { await using var transaction = diff --git a/docs/case-studies/governed-administrative-operation.md b/docs/case-studies/governed-administrative-operation.md index 8bf7344..2bb86df 100644 --- a/docs/case-studies/governed-administrative-operation.md +++ b/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, diff --git a/docs/case-studies/human-acknowledgment-workflow.md b/docs/case-studies/human-acknowledgment-workflow.md index 3609de4..bd17c88 100644 --- a/docs/case-studies/human-acknowledgment-workflow.md +++ b/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, diff --git a/docs/getting-started/asibackbone-6-api-boundary.md b/docs/getting-started/asibackbone-6-api-boundary.md new file mode 100644 index 0000000..12acc72 --- /dev/null +++ b/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` | +| Policy evaluator | `AsiBackbone.Core.Evaluation.IGovernancePolicyEvaluator` | +| Default evaluator | `AsiBackbone.Core.Evaluation.DefaultGovernancePolicyEvaluator` | +| Evaluator builder | `AsiBackbone.Core.Evaluation.GovernancePolicyEvaluatorBuilder` | +| Evaluator options | `AsiBackbone.Core.Evaluation.GovernancePolicyOptions` | +| Decision policy | `AsiBackbone.Core.Evaluation.IGovernanceDecisionPolicy` | +| 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 evaluator = + DefaultGovernancePolicyEvaluator + .CreateBuilder() + .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( + 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.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(); + +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(constraints, decisionPolicy = null)` | Builder with `AddConstraints` and `WithDecisionPolicy` | +| `DefaultAsiBackbonePolicyEvaluator(constraints, decisionPolicy, options)` | Builder plus `WithOptions` | +| `DefaultAsiBackbonePolicyEvaluator(constraints, decisionPolicy, options, logger)` | Builder plus `WithOptions` and `WithLogger` | +| `DefaultAsiBackbonePolicyEvaluator(constraints, threatModelContributors, decisionPolicy = null)` | Builder plus `AddThreatModelContributors` and `WithDecisionPolicy` | +| `DefaultAsiBackbonePolicyEvaluator(constraints, threatModelContributors, decisionPolicy, options)` | Builder plus contributors, policy, and options | +| `RequireGovernancePolicy(RouteHandlerBuilder)` | `MarkGovernancePolicy()`, or `MarkGovernancePolicy(typeof(TPolicy))` for a plain marker | +| `RequireGovernancePolicy(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. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index e0a4d07..d4cea6f 100644 --- a/docs/getting-started/index.md +++ b/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: diff --git a/docs/getting-started/toc.yml b/docs/getting-started/toc.yml index 458a619..d515ef1 100644 --- a/docs/getting-started/toc.yml +++ b/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 diff --git a/docs/labs/build-a-governed-api-operation.md b/docs/labs/build-a-governed-api-operation.md index 59e343a..0683b62 100644 --- a/docs/labs/build-a-governed-api-operation.md +++ b/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, diff --git a/docs/samples/index.md b/docs/samples/index.md index c029969..e967acb 100644 --- a/docs/samples/index.md +++ b/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 diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 6c89906..d5935d4 100644 --- a/docs/tutorials/index.md +++ b/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 | diff --git a/samples/README.md b/samples/README.md index 5f39ea5..ff75fd3 100644 --- a/samples/README.md +++ b/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 diff --git a/tools/validate-asibackbone-6-api-references.cs b/tools/validate-asibackbone-6-api-references.cs new file mode 100644 index 0000000..40b8e20 --- /dev/null +++ b/tools/validate-asibackbone-6-api-references.cs @@ -0,0 +1,423 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.RegularExpressions; +using System.Xml.Linq; + +return AsiBackboneApiReferenceValidator.Run(); + +static class AsiBackboneApiReferenceValidator +{ + private const string ApiBoundaryRelativePath = + "docs/getting-started/asibackbone-6-api-boundary.md"; + + private static readonly HashSet ForbiddenCurrentSymbols = new(StringComparer.Ordinal) + { + "AsiBackboneAcknowledgmentChallenge", + "AsiBackboneAcknowledgmentChallengeOptions", + "AsiBackboneAcknowledgmentChallengeRequest", + "AsiBackboneAcknowledgmentChallengeResult", + "AsiBackboneActorContext", + "AsiBackboneActorType", + "AsiBackboneAspNetCoreOptions", + "AsiBackboneAuditLedgerMetadataEntity", + "AsiBackboneAuditLedgerMetadataEntityConfiguration", + "AsiBackboneAuditLedgerReasonCodeEntity", + "AsiBackboneAuditLedgerReasonCodeEntityConfiguration", + "AsiBackboneAuditLedgerRecordEntity", + "AsiBackboneAuditLedgerRecordEntityConfiguration", + "AsiBackboneAuditResidueLifecycleEventEntity", + "AsiBackboneAuditResidueLifecycleEventEntityConfiguration", + "AsiBackboneAuditSinkContract", + "AsiBackboneConstraintContract", + "AsiBackboneConstraintEvaluationContext", + "AsiBackboneContractViolationException", + "AsiBackboneDecisionContract", + "AsiBackboneDecisionPolicyContract", + "AsiBackboneEndpointCapabilityGrantValidatorContract", + "AsiBackboneEndpointGovernanceApplicationBuilderExtensions", + "AsiBackboneEndpointGovernanceDescriptor", + "AsiBackboneEndpointGovernanceMetadataMode", + "AsiBackboneEndpointGovernanceMiddleware", + "AsiBackboneEndpointGovernanceOptions", + "AsiBackboneEndpointGovernanceResult", + "AsiBackboneEndpointGovernanceRouteBuilderExtensions", + "AsiBackboneEntity", + "AsiBackboneGovernanceOutboxDrain", + "AsiBackboneGovernanceOutboxDrainHostedService", + "AsiBackboneGovernanceOutboxDrainWorkerOptions", + "AsiBackboneGovernanceOutboxEntryEntity", + "AsiBackboneGovernanceOutboxEntryEntityConfiguration", + "AsiBackboneGovernanceOutboxOptions", + "AsiBackboneHandshakeAcknowledgmentEntity", + "AsiBackboneHandshakeAcknowledgmentEntityConfiguration", + "AsiBackboneHandshakeAcknowledgmentMetadataEntity", + "AsiBackboneHandshakeAcknowledgmentMetadataEntityConfiguration", + "AsiBackboneHandshakeRequestEntity", + "AsiBackboneHandshakeRequestEntityConfiguration", + "AsiBackboneHandshakeRequestMetadataEntity", + "AsiBackboneHandshakeRequestMetadataEntityConfiguration", + "AsiBackboneHttpActorContextOptions", + "AsiBackboneHttpRequestCorrelation", + "AsiBackboneHttpRequestCorrelationAuditExtensions", + "AsiBackboneHttpRequestMetadataKeys", + "AsiBackboneHttpResultMappingExtensions", + "AsiBackboneHttpResultMappingOptions", + "AsiBackboneIdentifierLimits", + "AsiBackbonePolicyEvaluatorBuilder", + "AsiBackbonePolicyEvaluatorContract", + "AsiBackbonePolicyEvaluatorOptions", + "AsiBackboneSchemaVersions", + "AsiBackboneTestAuditSink", + "AsiBackboneTestHarnessEndpointCapabilityGrantValidator", + "AsiBackboneTestHarnessOptions", + "AsiBackboneTestHarnessPolicyEvaluator", + "AsiBackboneTestHarnessServiceCollectionExtensions", + "AsiBackboneTestSigningService", + "AuditResidue", + "AuditResidueBuilder", + "AuditResidueLifecycleEvent", + "AuditResidueLifecycleStage", + "BackboneResult", + "DefaultAsiBackboneAcknowledgmentChallengeService", + "DefaultAsiBackboneDlpFailurePolicyResolver", + "DefaultAsiBackboneEndpointGovernanceService", + "DefaultAsiBackbonePolicyEvaluator", + "EfCoreAuditResidueLifecycleStore", + "HttpContextAsiBackboneActorContextResolver", + "HttpContextAsiBackboneRequestCorrelationResolver", + "IAsiBackboneAcknowledgmentChallengeService", + "IAsiBackboneActorContext", + "IAsiBackboneAuditLedgerStore", + "IAsiBackboneAuditResidue", + "IAsiBackboneAuditResidueLifecycleStore", + "IAsiBackboneAuditSink", + "IAsiBackboneConstraint", + "IAsiBackboneConstraintEvaluationContext", + "IAsiBackboneDecisionPolicy", + "IAsiBackboneDlpFailurePolicyResolver", + "IAsiBackboneEndpointAuditEmissionMetadata", + "IAsiBackboneEndpointCapabilityGrantMetadata", + "IAsiBackboneEndpointCapabilityGrantValidator", + "IAsiBackboneEndpointGovernanceMetadata", + "IAsiBackboneEndpointGovernancePolicyMetadata", + "IAsiBackboneEndpointGovernanceService", + "IAsiBackboneEndpointLiabilityHandshakeMetadata", + "IAsiBackboneEndpointPolicyEvaluationOptionsMetadata", + "IAsiBackboneEntity", + "IAsiBackboneGovernanceEmitter", + "IAsiBackboneGovernanceOutboxClaimOutcomeStore", + "IAsiBackboneGovernanceOutboxClaimStore", + "IAsiBackboneGovernanceOutboxStore", + "IAsiBackboneHttpActorContextResolver", + "IAsiBackboneHttpRequestCorrelationResolver", + "IAsiBackbonePolicyEvaluator", + "IAsiBackboneSignatureVerificationService", + "IAsiBackboneSigningService", + "InMemoryAuditResidueLifecycleStore", + "RequireGovernancePolicy" + }; + + private static readonly HashSet TextExtensions = new(StringComparer.OrdinalIgnoreCase) + { + ".cs", + ".csproj", + ".html", + ".js", + ".json", + ".md", + ".props", + ".svg", + ".targets", + ".tmpl", + ".xml", + ".yaml", + ".yml" + }; + + private static readonly Regex IdentifierRegex = new( + @"\b[A-Za-z_][A-Za-z0-9_]*\b", + RegexOptions.Compiled | RegexOptions.CultureInvariant); + + private static readonly Regex StaleImplementationLinkRegex = new( + @"https://github\.com/AsiBackbone/AsiBackbone/(?:blob|tree)/(?!release/6\.0\.0(?:/|\b))[^\s)\]'>]+", + RegexOptions.Compiled | RegexOptions.CultureInvariant | RegexOptions.IgnoreCase); + + public static int Run() + { + string repositoryRoot; + + try + { + repositoryRoot = FindRepositoryRoot(Environment.CurrentDirectory); + } + catch (InvalidOperationException exception) + { + Console.Error.WriteLine(exception.Message); + return 1; + } + + var errors = new List(); + IReadOnlyList textFiles = EnumerateTextFiles(repositoryRoot).ToArray(); + + ValidateCurrentSymbolsAndLinks(repositoryRoot, textFiles, errors); + int packageReferenceCount = ValidatePackageReferences(repositoryRoot, errors); + ValidateScopeNotices(repositoryRoot, errors); + + if (errors.Count > 0) + { + Console.Error.WriteLine("AsiBackbone 6.0 API-reference validation failed:"); + + foreach (string error in errors) + { + Console.Error.WriteLine($"- {error}"); + } + + Console.Error.WriteLine(); + Console.Error.WriteLine( + $"Use '{ApiBoundaryRelativePath}' for the current names, supported construction paths, and historical-removal inventory."); + return 1; + } + + string packageSummary = packageReferenceCount == 0 + ? "no AsiBackbone package references (framework-neutral sample policy)" + : $"{packageReferenceCount} AsiBackbone 6.x package reference(s)"; + + Console.WriteLine( + $"Validated AsiBackbone 6.0 API references across {textFiles.Count} instructional file(s): {packageSummary}."); + return 0; + } + + private static void ValidateCurrentSymbolsAndLinks( + string repositoryRoot, + IEnumerable files, + ICollection errors) + { + foreach (string path in files) + { + string relativePath = NormalizeRelativePath(repositoryRoot, path); + + if (string.Equals(relativePath, ApiBoundaryRelativePath, StringComparison.Ordinal) || + string.Equals(relativePath, "tools/validate-asibackbone-6-api-references.cs", StringComparison.Ordinal)) + { + continue; + } + + string text = File.ReadAllText(path); + string[] lines = File.ReadAllLines(path); + + for (int lineIndex = 0; lineIndex < lines.Length; lineIndex++) + { + string line = lines[lineIndex]; + + foreach (Match identifierMatch in IdentifierRegex.Matches(line)) + { + if (ForbiddenCurrentSymbols.Contains(identifierMatch.Value)) + { + errors.Add( + $"{relativePath}:{lineIndex + 1} uses removed or renamed 5.x symbol '{identifierMatch.Value}'."); + } + } + } + + foreach (Match linkMatch in StaleImplementationLinkRegex.Matches(text)) + { + int lineNumber = GetLineNumber(text, linkMatch.Index); + errors.Add( + $"{relativePath}:{lineNumber} links implementation source outside release/6.0.0: {linkMatch.Value}"); + } + } + } + + private static int ValidatePackageReferences( + string repositoryRoot, + ICollection errors) + { + var centralVersions = new Dictionary(StringComparer.OrdinalIgnoreCase); + var references = new List(); + + foreach (string path in Directory.EnumerateFiles(repositoryRoot, "*.props", SearchOption.AllDirectories) + .Concat(Directory.EnumerateFiles(repositoryRoot, "*.csproj", SearchOption.AllDirectories)) + .Where(path => !IsExcludedPath(repositoryRoot, path))) + { + XDocument document; + + try + { + document = XDocument.Load(path, LoadOptions.SetLineInfo); + } + catch (Exception exception) when (exception is IOException or System.Xml.XmlException) + { + errors.Add($"Could not parse {NormalizeRelativePath(repositoryRoot, path)}: {exception.Message}"); + continue; + } + + foreach (XElement element in document.Descendants()) + { + string localName = element.Name.LocalName; + + if (localName is not ("PackageReference" or "PackageVersion")) + { + continue; + } + + string? packageId = element.Attribute("Include")?.Value; + + if (!IsAsiBackbonePackage(packageId)) + { + continue; + } + + string? version = element.Attribute("Version")?.Value; + + if (localName == "PackageVersion") + { + if (!string.IsNullOrWhiteSpace(version)) + { + centralVersions[packageId!] = version; + } + + continue; + } + + references.Add(new PackageReference( + packageId!, + version, + NormalizeRelativePath(repositoryRoot, path))); + } + } + + foreach (PackageReference reference in references) + { + string? version = reference.Version; + + if (string.IsNullOrWhiteSpace(version)) + { + centralVersions.TryGetValue(reference.PackageId, out version); + } + + if (string.IsNullOrWhiteSpace(version)) + { + errors.Add( + $"{reference.RelativePath} references {reference.PackageId} without a pinned package version."); + continue; + } + + string normalizedVersion = version.Trim().TrimStart('[', '('); + + if (!normalizedVersion.StartsWith("6.", StringComparison.Ordinal)) + { + errors.Add( + $"{reference.RelativePath} references {reference.PackageId} {version}; Learning package-integration samples must use 6.x."); + } + } + + return references.Count; + } + + private static void ValidateScopeNotices( + string repositoryRoot, + ICollection errors) + { + string[] noticePaths = + { + "docs/tutorials/index.md", + "docs/samples/index.md", + "samples/README.md" + }; + + foreach (string relativePath in noticePaths) + { + string path = Path.Combine( + repositoryRoot, + relativePath.Replace('/', Path.DirectorySeparatorChar)); + + if (!File.Exists(path)) + { + errors.Add($"Missing code-scope notice location '{relativePath}'."); + continue; + } + + string text = File.ReadAllText(path); + + if (!text.Contains("Learning-owned", StringComparison.Ordinal) || + !text.Contains("asibackbone-6-api-boundary.md", StringComparison.OrdinalIgnoreCase)) + { + errors.Add( + $"{relativePath} must distinguish Learning-owned code from the AsiBackbone 6.0 API and link the API boundary guide."); + } + } + } + + private static IEnumerable EnumerateTextFiles(string repositoryRoot) + { + return Directory + .EnumerateFiles(repositoryRoot, "*", SearchOption.AllDirectories) + .Where(path => !IsExcludedPath(repositoryRoot, path)) + .Where(path => TextExtensions.Contains(Path.GetExtension(path))); + } + + private static bool IsExcludedPath(string repositoryRoot, string path) + { + string relativePath = NormalizeRelativePath(repositoryRoot, path); + string[] segments = relativePath.Split('/'); + + return segments.Any(segment => + segment.Equals(".git", StringComparison.OrdinalIgnoreCase) || + segment.Equals("_site", StringComparison.OrdinalIgnoreCase) || + segment.Equals("bin", StringComparison.OrdinalIgnoreCase) || + segment.Equals("obj", StringComparison.OrdinalIgnoreCase)); + } + + private static bool IsAsiBackbonePackage(string? packageId) + { + return !string.IsNullOrWhiteSpace(packageId) && + (packageId.Equals("AsiBackbone", StringComparison.OrdinalIgnoreCase) || + packageId.StartsWith("AsiBackbone.", StringComparison.OrdinalIgnoreCase)); + } + + private static int GetLineNumber(string text, int characterIndex) + { + int lineNumber = 1; + + for (int index = 0; index < characterIndex; index++) + { + if (text[index] == '\n') + { + lineNumber++; + } + } + + return lineNumber; + } + + private static string NormalizeRelativePath(string repositoryRoot, string path) + { + return Path.GetRelativePath(repositoryRoot, path).Replace('\\', '/'); + } + + private static string FindRepositoryRoot(string startDirectory) + { + DirectoryInfo? directory = new(startDirectory); + + while (directory is not null) + { + if (Directory.Exists(Path.Combine(directory.FullName, ".git")) || + File.Exists(Path.Combine(directory.FullName, ".git"))) + { + return directory.FullName; + } + + directory = directory.Parent; + } + + throw new InvalidOperationException( + $"Could not locate the repository root from '{startDirectory}'."); + } + + private sealed record PackageReference( + string PackageId, + string? Version, + string RelativePath); +} From 7fa4e61c0c52ebcb500cee2454710b34da206b6b Mon Sep 17 00:00:00 2001 From: "Christopher D. Cavell" <28095137+cdcavell@users.noreply.github.com> Date: Fri, 18 Sep 2026 07:23:43 -0500 Subject: [PATCH 03/10] docs: add Learning 1.0 compatibility guide for AsiBackbone 6.0 (#345) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Adds the Learning 1.0 production compatibility and migration guidance for AsiBackbone 6.0. This change establishes the documentation relationship between: - `AsiBackbone/Learning` 1.0 - `AsiBackbone/AsiBackbone` 6.0 and clarifies how readers should interpret earlier Learning material that references the 5.x implementation surface. ## Changes - Added a dedicated Learning 1.0 / AsiBackbone 6.0 compatibility guide. - Identified AsiBackbone 6.0 as the implementation baseline for Learning 1.0. - Documented the ownership boundary between Learning education and AsiBackbone runtime/API truth. - Summarized the major terminology refinements introduced for 6.0. - Added representative 5.x → 6.0 public API rename guidance. - Summarized the seven removed compatibility members that affect older examples without duplicating the full upstream migration guide. - Linked directly to authoritative AsiBackbone 6.0 migration, naming, terminology, and implementation documentation. - Documented the architectural concepts that remain stable across the major-version transition. - Clarified how historical Learning releases and 5.x-oriented content should be interpreted. - Added compatibility-guide links to: - root README - Getting Started - main DocFX navigation - Getting Started navigation ## Documentation Boundary Learning continues to own architecture education, terminology explanation, tutorials, and conceptual guidance. `AsiBackbone/AsiBackbone` remains authoritative for: - released public APIs - namespaces and signatures - runtime behavior - configuration - compatibility - migration requirements - implementation semantics All implementation references added by this change target the `release/6.0.0` branch rather than `main`. ## Validation - `git apply --check` passed against `release/1.0.0` - `git diff --check` passed - Documentation links reference the AsiBackbone `release/6.0.0` production baseline Closes #341 --- README.md | 1 + docs/getting-started/index.md | 3 + .../learning-1-asibackbone-6-compatibility.md | 204 ++++++++++++++++++ docs/getting-started/toc.yml | 2 + docs/toc.yml | 2 + 5 files changed, 212 insertions(+) create mode 100644 docs/getting-started/learning-1-asibackbone-6-compatibility.md diff --git a/README.md b/README.md index a5f4042..713c76f 100644 --- a/README.md +++ b/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) | +| Understand Learning 1.0 / AsiBackbone 6.0 compatibility or interpret 5.x material | [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](docs/getting-started/learning-1-asibackbone-6-compatibility.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) | diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index d4cea6f..9d5325f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -10,6 +10,8 @@ This repository teaches governance and controlled-execution architecture through > **Read it. Run it. Question it. Improve it.** +> **Production baseline:** Learning 1.0 is aligned with AsiBackbone 6.0. If you are reading material that references the AsiBackbone 5.x API, use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](learning-1-asibackbone-6-compatibility.md) before copying package syntax. + ## Start Here Choose the shortest path that matches how you want to learn: @@ -20,6 +22,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) | +| Understand version alignment or translate older 5.x material | [**Learning 1.0 and AsiBackbone 6.0 Compatibility Guide**](learning-1-asibackbone-6-compatibility.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) | diff --git a/docs/getting-started/learning-1-asibackbone-6-compatibility.md b/docs/getting-started/learning-1-asibackbone-6-compatibility.md new file mode 100644 index 0000000..c3c1e38 --- /dev/null +++ b/docs/getting-started/learning-1-asibackbone-6-compatibility.md @@ -0,0 +1,204 @@ +--- +description: Understand the Learning 1.0 and AsiBackbone 6.0 production baseline, the conceptual and API changes from 5.x, and where exact implementation behavior is authoritative. +--- + +# Learning 1.0 and AsiBackbone 6.0 Compatibility Guide + +> **Production baseline:** Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. + +Learning 1.0 is the educational companion to AsiBackbone 6.0. That alignment means current Learning terminology, API-facing examples, and implementation links are interpreted against the `release/6.0.0` product baseline. + +It does **not** mean that Learning depends on the AsiBackbone packages. Most Learning samples remain framework-neutral teaching models, and the architecture lessons are intended to remain useful even when you implement them without AsiBackbone. + +This guide explains the version relationship and the educational impact of the 6.0 transition. For exact package syntax, runtime behavior, and the complete migration inventory, use the implementation repository. + +## Version Relationship + +| Material | How to interpret it | +| --- | --- | +| **Learning 1.0** | Current production architecture education aligned with AsiBackbone 6.0 terminology and public API concepts. | +| **AsiBackbone 6.0** | Authoritative implementation baseline for package IDs, namespaces, public types, members, defaults, runtime behavior, compatibility, and migration details. | +| **Earlier Learning releases** | Historical educational records. Their architecture explanations may still be useful, but API-facing examples can reflect the AsiBackbone release line current when they were published. | +| **AsiBackbone 5.x material** | Historical implementation guidance. Translate package API syntax through the 5.x-to-6.0 migration guidance before using it in current code. | + +The ownership rule is intentionally simple: + +> **Learning teaches the architecture. AsiBackbone defines the released API and runtime truth.** + +The implementation repository documents the same boundary in its [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/documentation-ownership.md) guidance. + +## What Changed Conceptually + +The 6.0 transition refines terminology without changing the central governed-execution model taught by Learning. + +### Decision receipt replaces audit residue in current teaching + +Learning 1.0 uses **decision receipt** for the structured record of a policy decision, its outcome, and its reasons. The 6.0 product API likewise renamed the `AuditResidue` family to the `DecisionReceipt` family. + +A decision receipt is intentionally narrower than a claim of execution proof: + +- it records what evaluation produced; +- later acknowledgment, capability, persistence, gateway, and execution evidence can correlate with it; +- it does not by itself prove that the host executed the protected operation; +- it does not by itself imply durable storage, signing, immutability, or tamper evidence. + +Use **audit ledger**, **outbox**, **signing**, and **execution evidence** when those distinct responsibilities are what you mean. + +### Acknowledgment is the ordinary educational term + +Learning now prefers **acknowledgment** for the architectural concept: an identified actor or system responds to a defined challenge or responsibility statement before continuation. + +The 6.0 Core API intentionally retains `LiabilityHandshakeRequest` and `LiabilityHandshakeAcknowledgment` for the concrete multi-step protocol. ASP.NET Core challenge types use the shorter `AcknowledgmentChallenge` naming. + +The distinction remains the same: + +> **Acknowledgment ≠ authorization ≠ execution authority.** + +The retained word `Liability` in exact Core type names does not claim legal protection, legal advice, or automatic transfer of responsibility. + +### Product type names are more domain-focused + +AsiBackbone 6.0 removes redundant product-name prefixes from many public types and uses domain qualifiers where they communicate architectural role. Current Learning prose therefore emphasizes familiar concepts such as **context**, **constraint**, **decision**, **evaluator**, **receipt**, and **actor**, while exact API examples use the finalized 6.0 names. + +Examples include: + +| 5.x API name | 6.0 API name | +| --- | --- | +| `IAsiBackboneConstraint` | `IGovernanceConstraint` | +| `AsiBackboneConstraintEvaluationContext` | `GovernanceEvaluationContext` | +| `IAsiBackbonePolicyEvaluator` | `IGovernancePolicyEvaluator` | +| `DefaultAsiBackbonePolicyEvaluator` | `DefaultGovernancePolicyEvaluator` | +| `AsiBackbonePolicyEvaluatorBuilder` | `GovernancePolicyEvaluatorBuilder` | +| `AsiBackbonePolicyEvaluatorOptions` | `GovernancePolicyOptions` | +| `AsiBackboneActorContext` | `GovernanceActorContext` | +| `AuditResidue` | `DecisionReceipt` | +| `IAsiBackboneAuditSink` | `IDecisionReceiptSink` | +| `IAsiBackboneEndpointGovernanceService` | `IEndpointGovernanceService` | +| `IAsiBackboneAcknowledgmentChallengeService` | `IAcknowledgmentChallengeService` | + +This is a representative teaching-oriented subset, not the complete rename inventory. Use the authoritative [6.0 public API naming convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md) for the full list. + +### Learning can stay simpler than the product surface + +Learning commonly teaches five workflow outcomes: + +```text +Allow +Deny +Defer +Require acknowledgment +Escalate +``` + +The released 6.0 product also includes `GovernanceDecisionOutcome.Warning`. That product-specific continuation-with-warning state does not require every foundational Learning example to expand to six outcomes. + +The teaching model is allowed to be smaller when the simplification is explicit and does not misrepresent package syntax. + +## What Changed in Code Examples + +Two categories matter most when translating 5.x package examples. + +### Use the finalized 6.0 public names + +Current package-facing snippets should use the 6.0 names and namespaces. The [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md) lists the high-frequency types used by Learning and shows supported evaluator construction and endpoint metadata examples. + +Learning-owned sample types remain local teaching models unless a section is explicitly labeled **AsiBackbone 6.0 API**. + +### Removed 5.x compatibility members are no longer callable + +AsiBackbone 6.0 removes exactly seven public members whose obsolete compatibility windows ended at the major-version boundary. For Learning readers, the practical impact is concentrated in two areas: + +- the five partial `DefaultAsiBackbonePolicyEvaluator` constructors are gone; use `DefaultGovernancePolicyEvaluator.CreateBuilder()` or the supported full-dependency constructor; +- the two `RequireGovernancePolicy(...)` route-builder extension methods are gone; use `MarkGovernancePolicy(...)` instead. + +The non-obsolete `RequireGovernancePolicyAttribute` remains supported. + +Do not use this page as the complete implementation migration checklist. The authoritative [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) guide contains the exact removed-member inventory, replacement guidance, dependency-injection notes, and complete public type rename table. + +## What Did Not Change + +The major-version transition does not change the architecture boundaries that Learning is built around. + +The current model is still: + +```text +Proposed intent + ↓ +Authoritative policy context + ↓ +Constraints + ↓ +Explicit decision + ↓ +Decision receipt + ↓ +Acknowledgment when required + ↓ +Scoped authority when required + ↓ +Host-owned execution + ↓ +Correlated lifecycle evidence +``` + +The durable ideas are: + +- policy evaluation produces decision data; it does not perform the protected side effect; +- a denied decision must not reach the executor; +- acknowledgment does not silently become authorization or execution authority; +- scoped capability is bounded authority that must still be validated at the execution boundary; +- the host retains control of real-world side effects; +- AI tool calls are proposals until a trusted host evaluates and authorizes the operation; +- decision evidence, persistence, outbox delivery, signing, telemetry, and execution are related but distinct responsibilities; +- Learning samples can remain framework-neutral even while current implementation references align to AsiBackbone 6.0. + +Those concepts remain the reason Learning can teach the architecture independently of one package release. + +## How to Read Older Learning and 5.x Material + +Older content is useful when read in version context. + +| When you encounter... | Read it this way | +| --- | --- | +| `AuditResidue` or **audit residue** in an older package example | Historical 5.x naming for what current Learning and the 6.0 API call a decision receipt. Preserve the old wording when discussing the historical release itself. | +| `IAsiBackbone*`, `DefaultAsiBackbonePolicyEvaluator`, or other product-prefixed public types | Treat them as 5.x API names and translate them through the 6.0 naming and migration guides before copying code. | +| `RequireGovernancePolicy(...)` on a route builder | Treat it as historical 5.x syntax. Current 6.0 route metadata uses `MarkGovernancePolicy(...)`. | +| A Learning sample that declares its own context, decision, receipt, acknowledgment, capability, or gateway type | Treat it as a teaching model unless the page explicitly labels the snippet as AsiBackbone 6.0 API. | +| A historical release note, tag, or archived page | Read it as evidence of what that release taught or implemented at the time, not as the current production API contract. | +| A conceptual statement about decision-before-execution, acknowledgment, scoped authority, or host-owned execution | Treat the concept as current unless a newer Learning page explicitly revises it. Verify package-specific behavior in AsiBackbone 6.0. | + +Do not rewrite historical 5.x release records so they appear to have used 6.0 names. Versioned history is useful precisely because it preserves the contract and vocabulary that existed at that point in time. + +## Where to Verify Exact Behavior + +Use these sources in order, depending on the question: + +1. [Learning Architecture Glossary](../architecture/glossary.md) — canonical Learning definitions and teaching vocabulary. +2. [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md) — the high-frequency 6.0 package names and examples that Learning readers are most likely to copy. +3. [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) — authoritative breaking-change and migration guidance. +4. [6.0 Public API Naming Convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md) — complete public type rename inventory and retained-name decisions. +5. [AsiBackbone API Terminology Map](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/terminology-map.md) — mapping from Learning concepts to concrete product APIs. +6. [AsiBackbone API Glossary](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/glossary.md) — implementation-specific meanings, invariants, and host responsibilities. +7. [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/documentation-ownership.md) — the source-of-truth boundary between the two repositories. + +When those sources overlap, exact API/runtime behavior belongs to `AsiBackbone/AsiBackbone`; architecture teaching and canonical Learning terminology belong to `AsiBackbone/Learning`. + +## Migration Checklist for Learning Readers + +If you are moving a code example or internal document from an AsiBackbone 5.x baseline to the Learning 1.0 / AsiBackbone 6.0 baseline: + +- [ ] Decide whether the material is architecture teaching or exact package usage. +- [ ] Keep framework-neutral Learning sample types labeled as teaching models. +- [ ] Replace 5.x package type names with the finalized 6.0 names where the snippet uses the real product API. +- [ ] Replace removed partial evaluator constructors with the builder or full-dependency constructor. +- [ ] Replace removed route-builder `RequireGovernancePolicy(...)` calls with `MarkGovernancePolicy(...)`. +- [ ] Use **decision receipt** in current teaching prose while preserving historical wording in historical release material. +- [ ] Use **acknowledgment** as the ordinary teaching term and reserve **handshake** for the actual protocol or exact retained type names. +- [ ] Keep implementation links pinned to `release/6.0.0` when documenting the Learning 1.0 production baseline. +- [ ] Verify exact behavior in the implementation repository instead of copying a second runtime contract into Learning. + +## Continue + +If you are learning the architecture rather than migrating package code, continue with [Decision Before Execution](../tutorials/decision-before-execution.md). + +If you are copying AsiBackbone package syntax, continue with the [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md), then use the implementation repository for exact API and runtime details. diff --git a/docs/getting-started/toc.yml b/docs/getting-started/toc.yml index d515ef1..3781ca0 100644 --- a/docs/getting-started/toc.yml +++ b/docs/getting-started/toc.yml @@ -4,6 +4,8 @@ href: learning-path-map.md - name: Find Your Path href: find-your-path.md +- name: Learning 1.0 / AsiBackbone 6.0 Compatibility + href: learning-1-asibackbone-6-compatibility.md - name: AsiBackbone 6.0 API Boundary href: asibackbone-6-api-boundary.md - name: Adoption Personas and Entry Points diff --git a/docs/toc.yml b/docs/toc.yml index b5a5f2f..9280f29 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -5,6 +5,8 @@ items: - name: Getting Started href: getting-started/index.md + - name: Learning 1.0 / AsiBackbone 6.0 + href: getting-started/learning-1-asibackbone-6-compatibility.md - name: Articles href: articles/index.md - name: Tutorials From 01d17805a408be7cfd0f9883f2e4b4b779df2cf6 Mon Sep 17 00:00:00 2001 From: "Christopher D. Cavell" <28095137+cdcavell@users.noreply.github.com> Date: Fri, 18 Sep 2026 14:38:58 -0500 Subject: [PATCH 04/10] fix: align Learning 1.0 API validation with AsiBackbone 6.0 (#346) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Fixes the AsiBackbone 6.0 API-reference validation failures introduced by the new Learning 1.0 compatibility guidance. The compatibility documentation intentionally contains historical 5.x API names so readers can understand the 5.x → 6.0 migration, but the validator previously treated those historical references as invalid current API usage. This change also corrects the documented 6.0 endpoint-policy attribute name to match the finalized `AsiBackbone/AsiBackbone` `release/6.0.0` API. ## Changes - Updated `validate-asibackbone-6-api-references.cs` so: - the compatibility guide and API-boundary guide may contain explicitly historical 5.x symbols; - current instructional content remains protected from stale 5.x API names; - implementation links are still validated against `release/6.0.0`; - `RequireGovernancePolicyAttribute` is treated as a stale 5.x public type outside historical/reference documentation. - Updated the Learning 1.0 / AsiBackbone 6.0 compatibility guide to document: - `RequireGovernancePolicyAttribute` → `GovernancePolicyAttribute`; - the distinction between this public type rename and the seven obsolete-member removals; - the current route-builder replacement `MarkGovernancePolicy(...)`. - Updated the AsiBackbone 6.0 API boundary guide to: - include `GovernancePolicyAttribute` in the current API surface; - remove the incorrect statement that `RequireGovernancePolicyAttribute` remains supported; - clarify attribute-based endpoint metadata guidance. - Converted the validator regexes to `GeneratedRegexAttribute`-based implementations to avoid runtime regex compilation and resolve the related `SYSLIB1045` warnings. ## Implementation Baseline This change is built against: - `AsiBackbone/Learning` `release/1.0.0` - `AsiBackbone/AsiBackbone` `release/6.0.0` No references were taken from either repository's `main` branch for the compatibility contract. ## Validation - `git apply --check` passes. - `dotnet run --file tools/validate-asibackbone-6-api-references.cs` passes. - Validator reports: - `Validated AsiBackbone 6.0 API references across 350 instructional file(s)` - no AsiBackbone package references in the framework-neutral samples. - Historical 5.x migration references remain documented without weakening validation of current Learning content. --- .../asibackbone-6-api-boundary.md | 6 ++- .../learning-1-asibackbone-6-compatibility.md | 6 ++- .../validate-asibackbone-6-api-references.cs | 54 +++++++++++-------- 3 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/getting-started/asibackbone-6-api-boundary.md b/docs/getting-started/asibackbone-6-api-boundary.md index 12acc72..2337d88 100644 --- a/docs/getting-started/asibackbone-6-api-boundary.md +++ b/docs/getting-started/asibackbone-6-api-boundary.md @@ -47,6 +47,7 @@ The names most often used by Learning material are: | Durable audit ledger | `AsiBackbone.Core.Audit.IGovernanceAuditLedgerStore` | | Actor context | `AsiBackbone.Core.Actors.GovernanceActorContext` | | ASP.NET Core endpoint service | `AsiBackbone.AspNetCore.Endpoints.IEndpointGovernanceService` | +| ASP.NET Core policy marker attribute | `AsiBackbone.AspNetCore.Endpoints.GovernancePolicyAttribute` | | 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. @@ -107,6 +108,8 @@ app.MapPost("/exports", HandleExport) 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. +For attribute-based endpoint metadata, the 5.x `RequireGovernancePolicyAttribute` type was renamed to `GovernancePolicyAttribute` in 6.0. + ## Removed Compatibility Surface The upstream obsolete-member inventory found exactly seven public members whose compatibility window ended at 6.0: @@ -121,7 +124,7 @@ The upstream obsolete-member inventory found exactly seven public members whose | `RequireGovernancePolicy(RouteHandlerBuilder)` | `MarkGovernancePolicy()`, or `MarkGovernancePolicy(typeof(TPolicy))` for a plain marker | | `RequireGovernancePolicy(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. +The 5.x `RequireGovernancePolicyAttribute` type was renamed to `GovernancePolicyAttribute` in 6.0. That is a public type rename, not one of the seven obsolete-member removals above. Historical 4.x and 5.x migration material may retain old names when it is clearly presented as history; current examples must not present old names or removed members as 6.0 APIs. ## Decision Receipt Is Not Execution Proof @@ -136,6 +139,7 @@ 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; +- use `GovernancePolicyAttribute`, not the 5.x `RequireGovernancePolicyAttribute`, for attribute-based endpoint metadata; - 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; diff --git a/docs/getting-started/learning-1-asibackbone-6-compatibility.md b/docs/getting-started/learning-1-asibackbone-6-compatibility.md index c3c1e38..2ccda5c 100644 --- a/docs/getting-started/learning-1-asibackbone-6-compatibility.md +++ b/docs/getting-started/learning-1-asibackbone-6-compatibility.md @@ -75,6 +75,7 @@ Examples include: | `IAsiBackboneAuditSink` | `IDecisionReceiptSink` | | `IAsiBackboneEndpointGovernanceService` | `IEndpointGovernanceService` | | `IAsiBackboneAcknowledgmentChallengeService` | `IAcknowledgmentChallengeService` | +| `RequireGovernancePolicyAttribute` | `GovernancePolicyAttribute` | This is a representative teaching-oriented subset, not the complete rename inventory. Use the authoritative [6.0 public API naming convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md) for the full list. @@ -111,7 +112,7 @@ AsiBackbone 6.0 removes exactly seven public members whose obsolete compatibilit - the five partial `DefaultAsiBackbonePolicyEvaluator` constructors are gone; use `DefaultGovernancePolicyEvaluator.CreateBuilder()` or the supported full-dependency constructor; - the two `RequireGovernancePolicy(...)` route-builder extension methods are gone; use `MarkGovernancePolicy(...)` instead. -The non-obsolete `RequireGovernancePolicyAttribute` remains supported. +The 5.x `RequireGovernancePolicyAttribute` type was also renamed to `GovernancePolicyAttribute` in 6.0 so the attribute and route-builder paths use the same marker terminology. That type rename is separate from the seven obsolete-member removals. Do not use this page as the complete implementation migration checklist. The authoritative [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) guide contains the exact removed-member inventory, replacement guidance, dependency-injection notes, and complete public type rename table. @@ -162,7 +163,7 @@ Older content is useful when read in version context. | --- | --- | | `AuditResidue` or **audit residue** in an older package example | Historical 5.x naming for what current Learning and the 6.0 API call a decision receipt. Preserve the old wording when discussing the historical release itself. | | `IAsiBackbone*`, `DefaultAsiBackbonePolicyEvaluator`, or other product-prefixed public types | Treat them as 5.x API names and translate them through the 6.0 naming and migration guides before copying code. | -| `RequireGovernancePolicy(...)` on a route builder | Treat it as historical 5.x syntax. Current 6.0 route metadata uses `MarkGovernancePolicy(...)`. | +| `RequireGovernancePolicy(...)` on a route builder or `RequireGovernancePolicyAttribute` on an endpoint | Treat them as historical 5.x names. Current 6.0 route metadata uses `MarkGovernancePolicy(...)`, and attribute-based metadata uses `GovernancePolicyAttribute`. | | A Learning sample that declares its own context, decision, receipt, acknowledgment, capability, or gateway type | Treat it as a teaching model unless the page explicitly labels the snippet as AsiBackbone 6.0 API. | | A historical release note, tag, or archived page | Read it as evidence of what that release taught or implemented at the time, not as the current production API contract. | | A conceptual statement about decision-before-execution, acknowledgment, scoped authority, or host-owned execution | Treat the concept as current unless a newer Learning page explicitly revises it. Verify package-specific behavior in AsiBackbone 6.0. | @@ -192,6 +193,7 @@ If you are moving a code example or internal document from an AsiBackbone 5.x ba - [ ] Replace 5.x package type names with the finalized 6.0 names where the snippet uses the real product API. - [ ] Replace removed partial evaluator constructors with the builder or full-dependency constructor. - [ ] Replace removed route-builder `RequireGovernancePolicy(...)` calls with `MarkGovernancePolicy(...)`. +- [ ] Replace 5.x `RequireGovernancePolicyAttribute` usage with `GovernancePolicyAttribute`. - [ ] Use **decision receipt** in current teaching prose while preserving historical wording in historical release material. - [ ] Use **acknowledgment** as the ordinary teaching term and reserve **handshake** for the actual protocol or exact retained type names. - [ ] Keep implementation links pinned to `release/6.0.0` when documenting the Learning 1.0 production baseline. diff --git a/tools/validate-asibackbone-6-api-references.cs b/tools/validate-asibackbone-6-api-references.cs index 40b8e20..b1ca2d3 100644 --- a/tools/validate-asibackbone-6-api-references.cs +++ b/tools/validate-asibackbone-6-api-references.cs @@ -7,11 +7,17 @@ return AsiBackboneApiReferenceValidator.Run(); -static class AsiBackboneApiReferenceValidator +static partial class AsiBackboneApiReferenceValidator { private const string ApiBoundaryRelativePath = "docs/getting-started/asibackbone-6-api-boundary.md"; + private static readonly HashSet HistoricalSymbolReferencePaths = new(StringComparer.Ordinal) + { + ApiBoundaryRelativePath, + "docs/getting-started/learning-1-asibackbone-6-compatibility.md" + }; + private static readonly HashSet ForbiddenCurrentSymbols = new(StringComparer.Ordinal) { "AsiBackboneAcknowledgmentChallenge", @@ -116,7 +122,8 @@ static class AsiBackboneApiReferenceValidator "IAsiBackboneSignatureVerificationService", "IAsiBackboneSigningService", "InMemoryAuditResidueLifecycleStore", - "RequireGovernancePolicy" + "RequireGovernancePolicy", + "RequireGovernancePolicyAttribute" }; private static readonly HashSet TextExtensions = new(StringComparer.OrdinalIgnoreCase) @@ -136,13 +143,15 @@ static class AsiBackboneApiReferenceValidator ".yml" }; - private static readonly Regex IdentifierRegex = new( + [GeneratedRegex( @"\b[A-Za-z_][A-Za-z0-9_]*\b", - RegexOptions.Compiled | RegexOptions.CultureInvariant); + RegexOptions.CultureInvariant)] + private static partial Regex IdentifierRegex(); - private static readonly Regex StaleImplementationLinkRegex = new( + [GeneratedRegex( @"https://github\.com/AsiBackbone/AsiBackbone/(?:blob|tree)/(?!release/6\.0\.0(?:/|\b))[^\s)\]'>]+", - RegexOptions.Compiled | RegexOptions.CultureInvariant | RegexOptions.IgnoreCase); + RegexOptions.CultureInvariant | RegexOptions.IgnoreCase)] + private static partial Regex StaleImplementationLinkRegex(); public static int Run() { @@ -159,7 +168,7 @@ public static int Run() } var errors = new List(); - IReadOnlyList textFiles = EnumerateTextFiles(repositoryRoot).ToArray(); + string[] textFiles = EnumerateTextFiles(repositoryRoot).ToArray(); ValidateCurrentSymbolsAndLinks(repositoryRoot, textFiles, errors); int packageReferenceCount = ValidatePackageReferences(repositoryRoot, errors); @@ -185,43 +194,46 @@ public static int Run() : $"{packageReferenceCount} AsiBackbone 6.x package reference(s)"; Console.WriteLine( - $"Validated AsiBackbone 6.0 API references across {textFiles.Count} instructional file(s): {packageSummary}."); + $"Validated AsiBackbone 6.0 API references across {textFiles.Length} instructional file(s): {packageSummary}."); return 0; } private static void ValidateCurrentSymbolsAndLinks( string repositoryRoot, IEnumerable files, - ICollection errors) + List errors) { foreach (string path in files) { string relativePath = NormalizeRelativePath(repositoryRoot, path); - if (string.Equals(relativePath, ApiBoundaryRelativePath, StringComparison.Ordinal) || - string.Equals(relativePath, "tools/validate-asibackbone-6-api-references.cs", StringComparison.Ordinal)) + if (string.Equals(relativePath, "tools/validate-asibackbone-6-api-references.cs", StringComparison.Ordinal)) { continue; } string text = File.ReadAllText(path); - string[] lines = File.ReadAllLines(path); - for (int lineIndex = 0; lineIndex < lines.Length; lineIndex++) + if (!HistoricalSymbolReferencePaths.Contains(relativePath)) { - string line = lines[lineIndex]; + string[] lines = File.ReadAllLines(path); - foreach (Match identifierMatch in IdentifierRegex.Matches(line)) + for (int lineIndex = 0; lineIndex < lines.Length; lineIndex++) { - if (ForbiddenCurrentSymbols.Contains(identifierMatch.Value)) + string line = lines[lineIndex]; + + foreach (Match identifierMatch in IdentifierRegex().Matches(line)) { - errors.Add( - $"{relativePath}:{lineIndex + 1} uses removed or renamed 5.x symbol '{identifierMatch.Value}'."); + if (ForbiddenCurrentSymbols.Contains(identifierMatch.Value)) + { + errors.Add( + $"{relativePath}:{lineIndex + 1} uses removed or renamed 5.x symbol '{identifierMatch.Value}'."); + } } } } - foreach (Match linkMatch in StaleImplementationLinkRegex.Matches(text)) + foreach (Match linkMatch in StaleImplementationLinkRegex().Matches(text)) { int lineNumber = GetLineNumber(text, linkMatch.Index); errors.Add( @@ -232,7 +244,7 @@ private static void ValidateCurrentSymbolsAndLinks( private static int ValidatePackageReferences( string repositoryRoot, - ICollection errors) + List errors) { var centralVersions = new Dictionary(StringComparer.OrdinalIgnoreCase); var references = new List(); @@ -318,7 +330,7 @@ private static int ValidatePackageReferences( private static void ValidateScopeNotices( string repositoryRoot, - ICollection errors) + List errors) { string[] noticePaths = { From 539d982ea81f584d6ee2c1542a13a77d6cab9fbe Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 13:26:58 -0500 Subject: [PATCH 05/10] fix(docs): shorten compatibility guide description Keep the Learning 1.0 compatibility guide description within the 160-character metadata limit so documentation validation passes. Refs #341 --- docs/getting-started/learning-1-asibackbone-6-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/learning-1-asibackbone-6-compatibility.md b/docs/getting-started/learning-1-asibackbone-6-compatibility.md index 2ccda5c..0bc8a42 100644 --- a/docs/getting-started/learning-1-asibackbone-6-compatibility.md +++ b/docs/getting-started/learning-1-asibackbone-6-compatibility.md @@ -1,5 +1,5 @@ --- -description: Understand the Learning 1.0 and AsiBackbone 6.0 production baseline, the conceptual and API changes from 5.x, and where exact implementation behavior is authoritative. +description: Understand the Learning 1.0 and AsiBackbone 6.0 baseline, changes from 5.x, and where authoritative implementation behavior is documented. --- # Learning 1.0 and AsiBackbone 6.0 Compatibility Guide From 9f26c55b2adce2476c2b92c3e3bc9679cb1bf334 Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 13:45:46 -0500 Subject: [PATCH 06/10] docs: complete Learning 1.0 release-readiness review Add the dated release-readiness record and final 1.0.0 release notes. Align project-status messaging and navigation with the production documentation baseline, and document validation evidence, known limitations, and remaining publication controls. Closes #342 --- CHANGELOG.md | 2 + README.md | 4 +- RELEASE-NOTES-1.0.0.md | 41 ++++++++ .../learning-1-release-readiness.md | 94 +++++++++++++++++++ docs/getting-started/toc.yml | 2 + docs/index.md | 2 +- 6 files changed, 142 insertions(+), 3 deletions(-) create mode 100644 RELEASE-NOTES-1.0.0.md create mode 100644 docs/getting-started/learning-1-release-readiness.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7be73af..29bb081 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Learning releases are archival and citation snapshots of educational material. T ### Added +- Learning 1.0 production compatibility, API-boundary, release-readiness, and release-note guidance aligned with AsiBackbone 6.0. - Optional post-deployment X publication with source-frontmatter selection, durable receipt/checkpoint state, canonical-URL reconciliation, protected OAuth credentials, deterministic dry runs, and offline contract validation. @@ -16,6 +17,7 @@ Learning releases are archival and citation snapshots of educational material. T ### Changed +- Aligned current terminology, navigation, tutorials, diagrams, and sample guidance with the finalized AsiBackbone 6.0 vocabulary and public API surface. - Aligned all sample tests on `Microsoft.Testing.Platform` and `xunit.v3`, matching the shared AsiBackbone repository posture. ## [0.15.0] - 2026-09-11 diff --git a/README.md b/README.md index 713c76f..0636250 100644 --- a/README.md +++ b/README.md @@ -184,9 +184,9 @@ Issues are best used for concrete repository work; Learning Discussions are bett ## Project Status -**Active development — foundational tutorial, sample, test, and lab path established.** +**Learning 1.0 is the production documentation baseline aligned with AsiBackbone 6.0.** -Current development is focused on stronger implementation references, deeper labs, ASP.NET Core architecture, security and trust architecture, governance material, architecture comparisons, and improved discoverability. See [ROADMAP.md](ROADMAP.md) for the maintained direction. +The foundational tutorial, sample, test, and lab path is established. Current work focuses on maintenance, evidence-driven refinement, implementation alignment, and carefully selected additions. See the [Learning 1.0.0 Release Readiness record](docs/getting-started/learning-1-release-readiness.md) for the dated production review and [ROADMAP.md](ROADMAP.md) for the maintained direction. ## Citing a Release diff --git a/RELEASE-NOTES-1.0.0.md b/RELEASE-NOTES-1.0.0.md new file mode 100644 index 0000000..433801e --- /dev/null +++ b/RELEASE-NOTES-1.0.0.md @@ -0,0 +1,41 @@ +# AsiBackbone Learning 1.0.0 + +AsiBackbone Learning 1.0.0 is the first production documentation baseline for the AsiBackbone ecosystem. It is the educational companion to the AsiBackbone 6.0.0 implementation release. + +## Highlights + +- Aligns current terminology with the finalized AsiBackbone 6.0 vocabulary, including decision receipts, acknowledgment, capability grants, host-owned execution, and familiar outbox terminology. +- Adds a Learning 1.0 / AsiBackbone 6.0 compatibility guide for interpreting historical 5.x material. +- Adds an API boundary guide covering current 6.0 names, namespaces, evaluator construction, endpoint markers, renamed types, and removed compatibility members. +- Distinguishes Learning-owned framework-neutral teaching models from exact released package APIs. +- Refreshes Getting Started, navigation, tutorials, diagrams, samples, and cross-repository links around the production baseline. +- Validates all executable samples through locked restore, build, formatting, and 300 invariant tests. +- Adds durable release evidence: a samples SPDX SBOM, exact release notes, a SHA-256 evidence manifest, and GitHub provenance attestations. +- Strengthens documentation, link, workflow-security, dependency, code-scanning, publication, support, and maintainer gates. + +## Compatibility + +Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. + +Use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](https://asibackbone.github.io/Learning/getting-started/learning-1-asibackbone-6-compatibility.html) to translate older material. Use the [AsiBackbone 6.0 API Boundary](https://asibackbone.github.io/Learning/getting-started/asibackbone-6-api-boundary.html) for current high-frequency names and examples. The AsiBackbone [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) remains authoritative for complete implementation migration details. + +## Stable Architectural Boundaries + +The 6.0 vocabulary and API refinements do not change Learning's central architecture: + +- policy decides before protected execution begins; +- acknowledgment does not silently become authorization; +- capability grants remain narrow, explicit, and independently validated; +- the host retains ownership of side effects and execution; +- decision, acknowledgment, authority, delivery, and execution evidence remain distinct. + +## Known Limitations + +- Learning is educational documentation, not a package or runtime support line, compliance certification, or security guarantee. +- Executable samples use framework-neutral teaching types and do not reference `AsiBackbone.*` packages. +- Experimental material remains explicitly labeled and is not presented as a standardized protocol or production-ready implementation. +- Exact package signatures, runtime behavior, configuration, compatibility, and security semantics remain authoritative in the AsiBackbone 6.0 implementation repository. + +## Release Evidence + +The GitHub Release includes an SPDX 2.3 inventory of sample source and locked dependencies, these exact release notes, and a SHA-256 evidence manifest. GitHub provenance attestations bind each evidence asset to the release workflow. See the [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE.md) for scope and verification commands. diff --git a/docs/getting-started/learning-1-release-readiness.md b/docs/getting-started/learning-1-release-readiness.md new file mode 100644 index 0000000..088f655 --- /dev/null +++ b/docs/getting-started/learning-1-release-readiness.md @@ -0,0 +1,94 @@ +--- +description: Review the dated validation evidence, compatibility boundary, known limitations, and approval checklist for the Learning 1.0.0 release. +--- + +# Learning 1.0.0 Release Readiness + +**Review date:** 2026-09-19 +**Review outcome:** Approved as a release candidate, subject to the final pull-request checks, merge to protected `main`, and tag-bound publication checks described below. +**Learning source reviewed:** [`539d982ea81f584d6ee2c1542a13a77d6cab9fbe`](https://github.com/AsiBackbone/Learning/commit/539d982ea81f584d6ee2c1542a13a77d6cab9fbe) on `release/1.0.0` +**Aligned implementation baseline:** AsiBackbone `6.0.0`, using the authoritative [`release/6.0.0`](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0) source and [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) + +This record captures the final pre-release review of Learning 1.0.0. The record, accompanying release notes, and production-status wording are documentation-only changes to the reviewed source. The pull request containing them must rerun the same protected checks so the resulting merge commit, rather than this pre-record commit alone, becomes the release candidate. + +## Compatibility Statement + +Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. + +Learning owns educational definitions, progressive explanations, tutorials, labs, and framework-neutral samples. The AsiBackbone implementation repository remains authoritative for released package names, namespaces, signatures, runtime behavior, configuration, compatibility, migration requirements, and security semantics. + +## Milestone Review + +| Issue | Review result | Evidence | +| --- | --- | --- | +| [#339 — Align canonical terminology](https://github.com/AsiBackbone/Learning/issues/339) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #343](https://github.com/AsiBackbone/Learning/pull/343), the [canonical glossary](../architecture/glossary.md), and progressive terminology across current content. | +| [#340 — Update API references and examples](https://github.com/AsiBackbone/Learning/issues/340) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #344](https://github.com/AsiBackbone/Learning/pull/344), the [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md), and the repository API-reference validator. | +| [#341 — Publish compatibility and migration guidance](https://github.com/AsiBackbone/Learning/issues/341) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #345](https://github.com/AsiBackbone/Learning/pull/345), [PR #346](https://github.com/AsiBackbone/Learning/pull/346), and the [Learning 1.0 / AsiBackbone 6.0 Compatibility Guide](learning-1-asibackbone-6-compatibility.md). | +| [#342 — Complete the release-readiness review](https://github.com/AsiBackbone/Learning/issues/342) | This dated record and the [Learning 1.0.0 release notes](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE-NOTES-1.0.0.md) complete the pre-release review deliverables. | Local validation listed below plus current security and workflow evidence. | + +The three implementation issues remain open because their closing pull requests were merged into `release/1.0.0`, not the default branch. No implementation work from those issues is deferred. Administrative closure is intentionally left to the merge or explicit issue-closing step that places the completed work on `main`. + +## Documentation and API Review + +- The [canonical glossary](../architecture/glossary.md) introduces context, constraints, decisions, decision receipts, acknowledgment, capability grants, outbox delivery, signing, and advanced controls progressively. +- Current package-facing guidance uses the finalized 6.0 names and distinguishes historical 5.x names from current syntax. +- The API-reference validator rejects removed 5.x APIs and implementation links that do not target `release/6.0.0`, except in the two explicitly historical migration/reference pages. +- Learning-owned samples are framework-neutral teaching models. Their indexes and README files identify that boundary and direct readers to the exact 6.0 API guide. +- Getting Started, the root README, and primary navigation identify Learning 1.0 as the production documentation baseline aligned with AsiBackbone 6.0. + +## Validation Record + +The following commands were run from the reviewed release branch on 2026-09-19: + +| Gate | Command or evidence | Result | +| --- | --- | --- | +| Repository diff | `git diff --check` | Passed. | +| DocFX template baseline | `dotnet run --file tools/validate-docfx-template-baseline.cs` | Passed against pinned DocFX 2.78.5. | +| AsiBackbone 6.0 API references | `dotnet run --file tools/validate-asibackbone-6-api-references.cs` | Passed across 351 instructional files; samples contain no AsiBackbone package references. | +| Documentation metadata | `dotnet run --file tools/validate-doc-metadata.cs` | Passed. | +| DocFX | `dotnet tool run docfx docs/docfx.json --warningsAsErrors` | Passed with zero warnings and zero errors. | +| Samples | Locked restore, build, `dotnet format --verify-no-changes`, and test commands from `samples-validation.yml` | Passed; 300 tests succeeded, with zero failures or skips. | +| Release evidence tooling | `./scripts/Test-ReleaseEvidence.ps1` | Passed, including SBOM generation, manifest generation, and tamper rejection. | +| Learning 1.0.0 evidence rehearsal | `New-LearningSamplesSbom.ps1` and `New-ReleaseEvidence.ps1` in an isolated temporary clone tagged `v1.0.0` | Generated and hash-verified all three evidence files for the reviewed commit: 159 tracked sample files, 32 lock files, and 25 resolved NuGet packages. Temporary rehearsal assets were removed; the release workflow must regenerate them from the final tag. | +| Repository-host security controls | `./scripts/Manage-RepositorySecurityControls.ps1` | Passed after reconciling the main-branch ruleset with the committed baseline. Mandatory secret scanning, push protection, Dependabot security updates, and merged-branch cleanup are enabled. | +| Documentation links | [Link Validation for PR #346](https://github.com/AsiBackbone/Learning/actions/runs/35387079538) | Passed against the final API and compatibility content. The release-readiness pull request must rerun this check for the added record and release-note links. | +| Workflow security | [GitHub Actions security analysis](https://github.com/AsiBackbone/Learning/actions/runs/35443722855) | Passed on the `main` commit incorporated into the release branch. | +| Code scanning | [CodeQL Analysis](https://github.com/AsiBackbone/Learning/actions/runs/35443346982) | Passed on the `main` commit incorporated into the release branch. | +| Dependency analysis | [OWASP Dependency-Check](https://github.com/AsiBackbone/Learning/actions/runs/35443736826) | Passed on the `main` commit incorporated into the release branch. | +| Supply-chain posture | [OpenSSF Scorecard](https://github.com/AsiBackbone/Learning/actions/runs/35443729922) | Passed on the `main` commit incorporated into the release branch. | + +## Release Evidence and Publication Boundary + +The repository's [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE.md) requires a clean commit on protected `main`. Its local evidence harness verifies SPDX generation, release-note capture, manifest generation, component hashes, and tamper rejection before release. + +The final evidence assets and GitHub provenance attestations cannot exist before the GitHub Release is published. The `Publish Stable Release Evidence` workflow must run against the exact `v1.0.0` tag and publish: + +- `learning-samples-1.0.0.spdx.json`; +- `learning-1.0.0-release-notes.md`; +- `release-evidence-manifest.json`. + +Publication-time generation, attestation, upload, anonymous-download verification, and tag-to-commit verification are deliberately deferred to that release-triggered workflow because performing them earlier would not bind evidence to the final tag or published release notes. + +## Known Limitations + +- Learning releases are archival, citable educational snapshots. They do not create package or runtime support lines. +- Executable samples use local framework-neutral teaching types; they are not package-integration tests for `AsiBackbone.*` binaries. +- Exact implementation behavior remains owned by AsiBackbone 6.0 documentation and source. External links can change independently and continue to require scheduled link validation. +- Experimental pages remain explicitly labeled and should not be interpreted as standardized protocols or production-ready implementations. +- GitHub reports the optional non-provider secret patterns and secret-scanning validity checks as disabled for this repository or plan. Mandatory secret scanning and push protection are enabled, and the repository security-control audit passes. +- Final tag identity, GitHub Release notes, evidence assets, and provenance can only be verified after the release candidate is merged to `main` and `v1.0.0` is published. + +## Release Approval Checklist + +- [x] Learning 1.0 milestone implementation issues are complete or have an explicit administrative deferral rationale. +- [x] Terminology and API-facing examples align with the AsiBackbone 6.0 production surface. +- [x] Current production pages are protected from removed 6.0 APIs by repository validation. +- [x] Getting Started, primary navigation, and project-status messaging identify Learning 1.0 as the production baseline. +- [x] Local DocFX, metadata, API-reference, sample, formatting, and release-evidence tests pass. +- [x] Current security, workflow-analysis, dependency-analysis, and supply-chain checks are green on the `main` history incorporated into the release branch. +- [ ] The release-readiness pull request passes Documentation Validation, Link Validation, Sample Validation, and required branch checks. +- [ ] The approved release candidate is merged to protected `main`. +- [ ] `v1.0.0` is created from the approved `main` commit and the GitHub Release uses the reviewed [release notes](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE-NOTES-1.0.0.md). +- [ ] The release-triggered evidence workflow publishes, attests, and verifies all three durable assets. + +The unchecked items are publication controls, not known documentation defects. Do not publish Learning 1.0.0 until they are complete. diff --git a/docs/getting-started/toc.yml b/docs/getting-started/toc.yml index 3781ca0..502bbaa 100644 --- a/docs/getting-started/toc.yml +++ b/docs/getting-started/toc.yml @@ -6,6 +6,8 @@ href: find-your-path.md - name: Learning 1.0 / AsiBackbone 6.0 Compatibility href: learning-1-asibackbone-6-compatibility.md +- name: Learning 1.0.0 Release Readiness + href: learning-1-release-readiness.md - name: AsiBackbone 6.0 API Boundary href: asibackbone-6-api-boundary.md - name: Adoption Personas and Entry Points diff --git a/docs/index.md b/docs/index.md index ca14158..8a94ec3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -153,7 +153,7 @@ The goal is to make the reasoning visible—not to prove that one framework or a ## Recently added -This is a living project under active development. Recent publications include: +Learning 1.0 is the production documentation baseline aligned with AsiBackbone 6.0, and it remains a living project under evidence-driven maintenance. Recent publications include: - [A Passing Agent Diff Is Not Project Authority](articles/2026/a-passing-agent-diff-is-not-project-authority.md) - [Why an AI Tool Call Is Only a Proposal](articles/2026/why-ai-tool-call-is-only-a-proposal.md) From 2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 14:07:52 -0500 Subject: [PATCH 07/10] fix(release): finalize Learning 1.0 metadata and redirects Update citation, Zenodo, changelog, release notes, and readiness metadata for 1.0.0. Replace release-branch links with durable links and preserve renamed documentation and sample paths with redirects and compatibility pointers. Refs #339, #340, #341, #342 --- .zenodo.json | 2 +- CHANGELOG.md | 5 ++++- CITATION.cff | 4 ++-- RELEASE-NOTES-1.0.0.md | 14 +++++++++++++- ...ms-infrastructure-and-governed-execution.md | 5 +++++ .../learning-1-release-readiness.md | 18 ++++++++++-------- docs/labs/acknowledgment-and-audit-residue.md | 5 +++++ .../acknowledgment-and-audit-residue.md | 5 +++++ .../acknowledgment-and-audit-residue/README.md | 5 +++++ 9 files changed, 50 insertions(+), 13 deletions(-) create mode 100644 docs/architecture/accountable-systems-infrastructure-and-governed-execution.md create mode 100644 docs/labs/acknowledgment-and-audit-residue.md create mode 100644 docs/tutorials/acknowledgment-and-audit-residue.md create mode 100644 samples/acknowledgment-and-audit-residue/README.md diff --git a/.zenodo.json b/.zenodo.json index dd9559b..cde0ec1 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,6 +1,6 @@ { "title": "AsiBackbone Learning", - "version": "0.15.0", + "version": "1.0.0", "upload_type": "lesson", "description": "AsiBackbone Learning is the educational layer of the AsiBackbone organization: an open, community-oriented, DocFX-published collection of tutorials and architectural comparisons covering practical .NET architecture for governed execution, secure applications, AI integration, and policy-driven systems. Material connects conceptual explanations to working implementations in the AsiBackbone and NetCoreApplicationTemplate repositories. Learning is an educational and architectural resource; it is not a compliance certification, legal standard, security guarantee, or AI/AGI/ASI implementation. Documentation and educational material are licensed under CC BY 4.0. Executable sample code added under samples/ is licensed under the MIT License. See LICENSING.md for component-specific licensing terms.", "creators": [ diff --git a/CHANGELOG.md b/CHANGELOG.md index 29bb081..e84725c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ Learning releases are archival and citation snapshots of educational material. T ## [Unreleased] +## [1.0.0] - 2026-09-19 + ### Added - Learning 1.0 production compatibility, API-boundary, release-readiness, and release-note guidance aligned with AsiBackbone 6.0. @@ -41,5 +43,6 @@ Learning releases are archival and citation snapshots of educational material. T - Obsolete dependency-check suppressions for packages not used by Learning. -[Unreleased]: https://github.com/AsiBackbone/Learning/compare/v0.15.0...HEAD +[Unreleased]: https://github.com/AsiBackbone/Learning/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/AsiBackbone/Learning/compare/v0.15.0...v1.0.0 [0.15.0]: https://github.com/AsiBackbone/Learning/releases/tag/v0.15.0 diff --git a/CITATION.cff b/CITATION.cff index 87f9fb3..0175db0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -66,5 +66,5 @@ references: orcid: "https://orcid.org/0009-0002-2113-0245" doi: "10.5281/zenodo.20373042" repository-code: "https://github.com/AsiBackbone/NetCoreApplicationTemplate" -version: "0.15.0" -date-released: "2026-09-11" +version: "1.0.0" +date-released: "2026-09-19" diff --git a/RELEASE-NOTES-1.0.0.md b/RELEASE-NOTES-1.0.0.md index 433801e..8fbb682 100644 --- a/RELEASE-NOTES-1.0.0.md +++ b/RELEASE-NOTES-1.0.0.md @@ -2,6 +2,8 @@ AsiBackbone Learning 1.0.0 is the first production documentation baseline for the AsiBackbone ecosystem. It is the educational companion to the AsiBackbone 6.0.0 implementation release. +The version advances from 0.15.0 to 1.0.0 because the foundational curriculum, public navigation, compatibility boundary, validation gates, and release evidence are now established as a stable documentation contract. Published page URLs are treated as durable; future moves should retain redirects from their previous addresses. + ## Highlights - Aligns current terminology with the finalized AsiBackbone 6.0 vocabulary, including decision receipts, acknowledgment, capability grants, host-owned execution, and familiar outbox terminology. @@ -29,6 +31,16 @@ The 6.0 vocabulary and API refinements do not change Learning's central architec - the host retains ownership of side effects and execution; - decision, acknowledgment, authority, delivery, and execution evidence remain distinct. +## Renamed Pages and Sample + +Learning 1.0 adopts the finalized 6.0 terminology while preserving the previously published documentation URLs as redirects: + +- `architecture/accountable-systems-infrastructure-and-governed-execution` → `architecture/asibackbone-and-governed-execution`; +- `tutorials/acknowledgment-and-audit-residue` → `tutorials/decision-receipts-and-acknowledgment`; +- `labs/acknowledgment-and-audit-residue` → `labs/decision-receipts-and-acknowledgment`. + +The companion sample moved from `samples/acknowledgment-and-audit-residue` to `samples/decision-receipts-and-acknowledgment`. The old sample directory retains a pointer README for repository links and historical references. + ## Known Limitations - Learning is educational documentation, not a package or runtime support line, compliance certification, or security guarantee. @@ -38,4 +50,4 @@ The 6.0 vocabulary and API refinements do not change Learning's central architec ## Release Evidence -The GitHub Release includes an SPDX 2.3 inventory of sample source and locked dependencies, these exact release notes, and a SHA-256 evidence manifest. GitHub provenance attestations bind each evidence asset to the release workflow. See the [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE.md) for scope and verification commands. +The GitHub Release includes an SPDX 2.3 inventory of sample source and locked dependencies, these exact release notes, and a SHA-256 evidence manifest. GitHub provenance attestations bind each evidence asset to the release workflow. See the [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/main/RELEASE.md) for scope and verification commands. diff --git a/docs/architecture/accountable-systems-infrastructure-and-governed-execution.md b/docs/architecture/accountable-systems-infrastructure-and-governed-execution.md new file mode 100644 index 0000000..3c512ca --- /dev/null +++ b/docs/architecture/accountable-systems-infrastructure-and-governed-execution.md @@ -0,0 +1,5 @@ +--- +redirect_url: asibackbone-and-governed-execution.html +--- + +# Accountable Systems Infrastructure and Governed Execution diff --git a/docs/getting-started/learning-1-release-readiness.md b/docs/getting-started/learning-1-release-readiness.md index 088f655..9d34b1d 100644 --- a/docs/getting-started/learning-1-release-readiness.md +++ b/docs/getting-started/learning-1-release-readiness.md @@ -6,10 +6,11 @@ description: Review the dated validation evidence, compatibility boundary, known **Review date:** 2026-09-19 **Review outcome:** Approved as a release candidate, subject to the final pull-request checks, merge to protected `main`, and tag-bound publication checks described below. -**Learning source reviewed:** [`539d982ea81f584d6ee2c1542a13a77d6cab9fbe`](https://github.com/AsiBackbone/Learning/commit/539d982ea81f584d6ee2c1542a13a77d6cab9fbe) on `release/1.0.0` +**Learning content baseline reviewed:** [`9f26c55b2adce2476c2b92c3e3bc9679cb1bf334`](https://github.com/AsiBackbone/Learning/commit/9f26c55b2adce2476c2b92c3e3bc9679cb1bf334) on `release/1.0.0` + **Aligned implementation baseline:** AsiBackbone `6.0.0`, using the authoritative [`release/6.0.0`](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0) source and [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) -This record captures the final pre-release review of Learning 1.0.0. The record, accompanying release notes, and production-status wording are documentation-only changes to the reviewed source. The pull request containing them must rerun the same protected checks so the resulting merge commit, rather than this pre-record commit alone, becomes the release candidate. +This record captures the final pre-release review of Learning 1.0.0. Follow-up changes after the reviewed content baseline update release metadata, add permanent redirect stubs, replace release-branch links with durable default-branch links, and correct this record. The pull request containing those changes must pass the required documentation, link, sample, formatting, security, and workflow checks; the resulting merge commit, rather than the baseline commit alone, becomes the release candidate. ## Compatibility Statement @@ -24,7 +25,7 @@ Learning owns educational definitions, progressive explanations, tutorials, labs | [#339 — Align canonical terminology](https://github.com/AsiBackbone/Learning/issues/339) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #343](https://github.com/AsiBackbone/Learning/pull/343), the [canonical glossary](../architecture/glossary.md), and progressive terminology across current content. | | [#340 — Update API references and examples](https://github.com/AsiBackbone/Learning/issues/340) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #344](https://github.com/AsiBackbone/Learning/pull/344), the [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md), and the repository API-reference validator. | | [#341 — Publish compatibility and migration guidance](https://github.com/AsiBackbone/Learning/issues/341) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #345](https://github.com/AsiBackbone/Learning/pull/345), [PR #346](https://github.com/AsiBackbone/Learning/pull/346), and the [Learning 1.0 / AsiBackbone 6.0 Compatibility Guide](learning-1-asibackbone-6-compatibility.md). | -| [#342 — Complete the release-readiness review](https://github.com/AsiBackbone/Learning/issues/342) | This dated record and the [Learning 1.0.0 release notes](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE-NOTES-1.0.0.md) complete the pre-release review deliverables. | Local validation listed below plus current security and workflow evidence. | +| [#342 — Complete the release-readiness review](https://github.com/AsiBackbone/Learning/issues/342) | This dated record and the [Learning 1.0.0 release notes](https://github.com/AsiBackbone/Learning/blob/main/RELEASE-NOTES-1.0.0.md) complete the pre-release review deliverables. | Local validation listed below plus current security and workflow evidence. | The three implementation issues remain open because their closing pull requests were merged into `release/1.0.0`, not the default branch. No implementation work from those issues is deferred. Administrative closure is intentionally left to the merge or explicit issue-closing step that places the completed work on `main`. @@ -34,6 +35,7 @@ The three implementation issues remain open because their closing pull requests - Current package-facing guidance uses the finalized 6.0 names and distinguishes historical 5.x names from current syntax. - The API-reference validator rejects removed 5.x APIs and implementation links that do not target `release/6.0.0`, except in the two explicitly historical migration/reference pages. - Learning-owned samples are framework-neutral teaching models. Their indexes and README files identify that boundary and direct readers to the exact 6.0 API guide. +- Previously published pages renamed for 6.0 terminology retain redirect stubs, and the renamed sample retains a pointer at its former repository path. - Getting Started, the root README, and primary navigation identify Learning 1.0 as the production documentation baseline aligned with AsiBackbone 6.0. ## Validation Record @@ -44,12 +46,12 @@ The following commands were run from the reviewed release branch on 2026-09-19: | --- | --- | --- | | Repository diff | `git diff --check` | Passed. | | DocFX template baseline | `dotnet run --file tools/validate-docfx-template-baseline.cs` | Passed against pinned DocFX 2.78.5. | -| AsiBackbone 6.0 API references | `dotnet run --file tools/validate-asibackbone-6-api-references.cs` | Passed across 351 instructional files; samples contain no AsiBackbone package references. | +| AsiBackbone 6.0 API references | `dotnet run --file tools/validate-asibackbone-6-api-references.cs` | Passed across 355 instructional files; samples contain no AsiBackbone package references. | | Documentation metadata | `dotnet run --file tools/validate-doc-metadata.cs` | Passed. | | DocFX | `dotnet tool run docfx docs/docfx.json --warningsAsErrors` | Passed with zero warnings and zero errors. | -| Samples | Locked restore, build, `dotnet format --verify-no-changes`, and test commands from `samples-validation.yml` | Passed; 300 tests succeeded, with zero failures or skips. | +| Samples | Solution inventory, locked restore, clean non-incremental build, `dotnet format --verify-no-changes`, and test commands from `samples-validation.yml` | Passed; the renamed sample and test projects were listed and rebuilt from cleaned outputs, and all 300 tests succeeded with zero failures or skips. | | Release evidence tooling | `./scripts/Test-ReleaseEvidence.ps1` | Passed, including SBOM generation, manifest generation, and tamper rejection. | -| Learning 1.0.0 evidence rehearsal | `New-LearningSamplesSbom.ps1` and `New-ReleaseEvidence.ps1` in an isolated temporary clone tagged `v1.0.0` | Generated and hash-verified all three evidence files for the reviewed commit: 159 tracked sample files, 32 lock files, and 25 resolved NuGet packages. Temporary rehearsal assets were removed; the release workflow must regenerate them from the final tag. | +| Learning 1.0.0 evidence rehearsal | `New-LearningSamplesSbom.ps1` and `New-ReleaseEvidence.ps1` in an isolated temporary clone tagged `v1.0.0` | Generated and hash-verified all three evidence files for the final working tree: 160 tracked sample files, 32 lock files, and 25 resolved NuGet packages. Temporary rehearsal assets were removed; the release workflow must regenerate them from the final tag. | | Repository-host security controls | `./scripts/Manage-RepositorySecurityControls.ps1` | Passed after reconciling the main-branch ruleset with the committed baseline. Mandatory secret scanning, push protection, Dependabot security updates, and merged-branch cleanup are enabled. | | Documentation links | [Link Validation for PR #346](https://github.com/AsiBackbone/Learning/actions/runs/35387079538) | Passed against the final API and compatibility content. The release-readiness pull request must rerun this check for the added record and release-note links. | | Workflow security | [GitHub Actions security analysis](https://github.com/AsiBackbone/Learning/actions/runs/35443722855) | Passed on the `main` commit incorporated into the release branch. | @@ -59,7 +61,7 @@ The following commands were run from the reviewed release branch on 2026-09-19: ## Release Evidence and Publication Boundary -The repository's [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE.md) requires a clean commit on protected `main`. Its local evidence harness verifies SPDX generation, release-note capture, manifest generation, component hashes, and tamper rejection before release. +The repository's [Stable Release Evidence Runbook](https://github.com/AsiBackbone/Learning/blob/main/RELEASE.md) requires a clean commit on protected `main`. Its local evidence harness verifies SPDX generation, release-note capture, manifest generation, component hashes, and tamper rejection before release. The final evidence assets and GitHub provenance attestations cannot exist before the GitHub Release is published. The `Publish Stable Release Evidence` workflow must run against the exact `v1.0.0` tag and publish: @@ -88,7 +90,7 @@ Publication-time generation, attestation, upload, anonymous-download verificatio - [x] Current security, workflow-analysis, dependency-analysis, and supply-chain checks are green on the `main` history incorporated into the release branch. - [ ] The release-readiness pull request passes Documentation Validation, Link Validation, Sample Validation, and required branch checks. - [ ] The approved release candidate is merged to protected `main`. -- [ ] `v1.0.0` is created from the approved `main` commit and the GitHub Release uses the reviewed [release notes](https://github.com/AsiBackbone/Learning/blob/release/1.0.0/RELEASE-NOTES-1.0.0.md). +- [ ] `v1.0.0` is created from the approved `main` commit and the GitHub Release uses the reviewed [release notes](https://github.com/AsiBackbone/Learning/blob/main/RELEASE-NOTES-1.0.0.md). - [ ] The release-triggered evidence workflow publishes, attests, and verifies all three durable assets. The unchecked items are publication controls, not known documentation defects. Do not publish Learning 1.0.0 until they are complete. diff --git a/docs/labs/acknowledgment-and-audit-residue.md b/docs/labs/acknowledgment-and-audit-residue.md new file mode 100644 index 0000000..55d5433 --- /dev/null +++ b/docs/labs/acknowledgment-and-audit-residue.md @@ -0,0 +1,5 @@ +--- +redirect_url: decision-receipts-and-acknowledgment.html +--- + +# Lab — Acknowledgment and Audit Residue diff --git a/docs/tutorials/acknowledgment-and-audit-residue.md b/docs/tutorials/acknowledgment-and-audit-residue.md new file mode 100644 index 0000000..6a35b48 --- /dev/null +++ b/docs/tutorials/acknowledgment-and-audit-residue.md @@ -0,0 +1,5 @@ +--- +redirect_url: decision-receipts-and-acknowledgment.html +--- + +# Acknowledgment and Audit Residue diff --git a/samples/acknowledgment-and-audit-residue/README.md b/samples/acknowledgment-and-audit-residue/README.md new file mode 100644 index 0000000..6ebd6bd --- /dev/null +++ b/samples/acknowledgment-and-audit-residue/README.md @@ -0,0 +1,5 @@ +# Acknowledgment and Audit Residue Sample Moved + +This sample moved to [Decision Receipts and Acknowledgment](../decision-receipts-and-acknowledgment/README.md) for Learning 1.0 terminology alignment. + +The old directory is retained as a pointer for historical repository links. Use the new directory for the executable sample, tests, and current guidance. From eb30f8884645af609b1a86252ee4f0f5df0b20bd Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 14:17:05 -0500 Subject: [PATCH 08/10] fix(release): prepare validation for main merge --- .github/workflows/docs-validation.yml | 1 - .github/workflows/link-validation.yml | 1 - .github/workflows/samples-validation.yml | 1 - docs/getting-started/learning-1-release-readiness.md | 12 ++++++------ docs/labs/decision-receipts-and-acknowledgment.md | 2 +- .../decision-receipts-and-acknowledgment.md | 2 +- 6 files changed, 8 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml index 072f03c..20473f0 100644 --- a/.github/workflows/docs-validation.yml +++ b/.github/workflows/docs-validation.yml @@ -9,7 +9,6 @@ on: pull_request: branches: - main - - release/1.0.0 push: branches: diff --git a/.github/workflows/link-validation.yml b/.github/workflows/link-validation.yml index edf04be..bf4d0b4 100644 --- a/.github/workflows/link-validation.yml +++ b/.github/workflows/link-validation.yml @@ -6,7 +6,6 @@ on: pull_request: branches: - main - - release/1.0.0 push: branches: diff --git a/.github/workflows/samples-validation.yml b/.github/workflows/samples-validation.yml index ad395b8..0985465 100644 --- a/.github/workflows/samples-validation.yml +++ b/.github/workflows/samples-validation.yml @@ -6,7 +6,6 @@ on: pull_request: branches: - main - - release/1.0.0 push: branches: diff --git a/docs/getting-started/learning-1-release-readiness.md b/docs/getting-started/learning-1-release-readiness.md index 9d34b1d..708460a 100644 --- a/docs/getting-started/learning-1-release-readiness.md +++ b/docs/getting-started/learning-1-release-readiness.md @@ -4,13 +4,13 @@ description: Review the dated validation evidence, compatibility boundary, known # Learning 1.0.0 Release Readiness -**Review date:** 2026-09-19 -**Review outcome:** Approved as a release candidate, subject to the final pull-request checks, merge to protected `main`, and tag-bound publication checks described below. -**Learning content baseline reviewed:** [`9f26c55b2adce2476c2b92c3e3bc9679cb1bf334`](https://github.com/AsiBackbone/Learning/commit/9f26c55b2adce2476c2b92c3e3bc9679cb1bf334) on `release/1.0.0` +**Review date:** 2026-09-19\ +**Review outcome:** Approved as a release candidate, subject to the final pull-request checks, merge to protected `main`, and tag-bound publication checks described below.\ +**Learning content baseline reviewed:** [`2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a`](https://github.com/AsiBackbone/Learning/commit/2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a) on `release/1.0.0` **Aligned implementation baseline:** AsiBackbone `6.0.0`, using the authoritative [`release/6.0.0`](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0) source and [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) -This record captures the final pre-release review of Learning 1.0.0. Follow-up changes after the reviewed content baseline update release metadata, add permanent redirect stubs, replace release-branch links with durable default-branch links, and correct this record. The pull request containing those changes must pass the required documentation, link, sample, formatting, security, and workflow checks; the resulting merge commit, rather than the baseline commit alone, becomes the release candidate. +This record captures the final pre-release review of Learning 1.0.0. Follow-up changes after the reviewed content baseline update release metadata, add permanent redirect stubs, replace release-branch links with durable default-branch or commit-permalink links, and correct this record. The pull request containing those changes must pass the required documentation, link, sample, formatting, security, and workflow checks; the resulting merge commit, rather than the baseline commit alone, becomes the release candidate. ## Compatibility Statement @@ -25,7 +25,7 @@ Learning owns educational definitions, progressive explanations, tutorials, labs | [#339 — Align canonical terminology](https://github.com/AsiBackbone/Learning/issues/339) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #343](https://github.com/AsiBackbone/Learning/pull/343), the [canonical glossary](../architecture/glossary.md), and progressive terminology across current content. | | [#340 — Update API references and examples](https://github.com/AsiBackbone/Learning/issues/340) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #344](https://github.com/AsiBackbone/Learning/pull/344), the [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md), and the repository API-reference validator. | | [#341 — Publish compatibility and migration guidance](https://github.com/AsiBackbone/Learning/issues/341) | Implementation complete; administrative closure is deferred until the release work reaches the default branch. | [PR #345](https://github.com/AsiBackbone/Learning/pull/345), [PR #346](https://github.com/AsiBackbone/Learning/pull/346), and the [Learning 1.0 / AsiBackbone 6.0 Compatibility Guide](learning-1-asibackbone-6-compatibility.md). | -| [#342 — Complete the release-readiness review](https://github.com/AsiBackbone/Learning/issues/342) | This dated record and the [Learning 1.0.0 release notes](https://github.com/AsiBackbone/Learning/blob/main/RELEASE-NOTES-1.0.0.md) complete the pre-release review deliverables. | Local validation listed below plus current security and workflow evidence. | +| [#342 — Complete the release-readiness review](https://github.com/AsiBackbone/Learning/issues/342) | This dated record and the [Learning 1.0.0 release notes](https://github.com/AsiBackbone/Learning/blob/2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a/RELEASE-NOTES-1.0.0.md) complete the pre-release review deliverables. | Local validation listed below plus current security and workflow evidence. | The three implementation issues remain open because their closing pull requests were merged into `release/1.0.0`, not the default branch. No implementation work from those issues is deferred. Administrative closure is intentionally left to the merge or explicit issue-closing step that places the completed work on `main`. @@ -90,7 +90,7 @@ Publication-time generation, attestation, upload, anonymous-download verificatio - [x] Current security, workflow-analysis, dependency-analysis, and supply-chain checks are green on the `main` history incorporated into the release branch. - [ ] The release-readiness pull request passes Documentation Validation, Link Validation, Sample Validation, and required branch checks. - [ ] The approved release candidate is merged to protected `main`. -- [ ] `v1.0.0` is created from the approved `main` commit and the GitHub Release uses the reviewed [release notes](https://github.com/AsiBackbone/Learning/blob/main/RELEASE-NOTES-1.0.0.md). +- [ ] `v1.0.0` is created from the approved `main` commit and the GitHub Release uses the reviewed [release notes](https://github.com/AsiBackbone/Learning/blob/2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a/RELEASE-NOTES-1.0.0.md). - [ ] The release-triggered evidence workflow publishes, attests, and verifies all three durable assets. The unchecked items are publication controls, not known documentation defects. Do not publish Learning 1.0.0 until they are complete. diff --git a/docs/labs/decision-receipts-and-acknowledgment.md b/docs/labs/decision-receipts-and-acknowledgment.md index 8c6dd89..e52f40e 100644 --- a/docs/labs/decision-receipts-and-acknowledgment.md +++ b/docs/labs/decision-receipts-and-acknowledgment.md @@ -6,7 +6,7 @@ description: Practice acknowledgment as a narrowly bound governance event, re-ev **Learning objective:** Practice treating acknowledgment as a narrowly bound governance event rather than permission, preserving re-evaluation after acknowledgment, and maintaining a correlated audit timeline that distinguishes decisions, acknowledgments, and execution outcomes. -**Difficulty:** Intermediate +**Difficulty:** Intermediate\ **Prerequisites:** Complete the [Decision Receipts and Acknowledgment tutorial](../tutorials/decision-receipts-and-acknowledgment.md) and run the [Decision Receipts and Acknowledgment sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-receipts-and-acknowledgment/README.md). diff --git a/docs/tutorials/decision-receipts-and-acknowledgment.md b/docs/tutorials/decision-receipts-and-acknowledgment.md index 5213a34..64203dd 100644 --- a/docs/tutorials/decision-receipts-and-acknowledgment.md +++ b/docs/tutorials/decision-receipts-and-acknowledgment.md @@ -8,7 +8,7 @@ description: Learn how operations pause for bound acknowledgment, re-evaluate cu **Pattern classification:** Canonical Pattern -**Difficulty:** Intermediate +**Difficulty:** Intermediate\ **Prerequisites:** [Decision Before Execution](decision-before-execution.md) and [Policy Context and Explicit Decision Outcomes](policy-context-and-explicit-decision-outcomes.md) From 62bf862e9b9189717b28056136e85bb9d1f47164 Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 14:24:36 -0500 Subject: [PATCH 09/10] fix(docs): target AsiBackbone main branch --- RELEASE-NOTES-1.0.0.md | 2 +- ...-ledgers-and-cryptographic-audit-chains.md | 8 ++-- ...ts-and-multi-agent-execution-boundaries.md | 10 ++--- .../regional-and-tenant-policy-overlays.md | 4 +- .../agent-memory-and-governance-boundaries.md | 8 ++-- ...ability-and-end-to-end-decision-tracing.md | 6 +-- ...-tool-workflows-and-recovery-boundaries.md | 12 +++--- ...intent-and-schema-validation-boundaries.md | 4 +- ...query-separation-and-governed-execution.md | 4 +- docs/architecture/glossary.md | 2 +- ...pine-and-capability-validation-diagrams.md | 6 +-- ...-badge-does-not-prove-package-integrity.md | 2 +- ...ss-boundaries-and-transaction-reasoning.md | 6 +-- ...d-logging-without-sensitive-data-sprawl.md | 2 +- .../asibackbone-6-api-boundary.md | 14 +++---- .../learning-1-asibackbone-6-compatibility.md | 20 ++++----- .../learning-1-release-readiness.md | 4 +- ...raint-composition-and-policy-precedence.md | 12 +++--- ...obabilistic-inputs-in-policy-evaluation.md | 14 +++---- ...escalation-patterns-in-governed-systems.md | 14 +++---- .../human-in-the-loop-governance-workflows.md | 12 +++--- ...licy-versioning-and-decision-provenance.md | 8 ++-- ...y-testing-and-decision-table-strategies.md | 4 +- ...isk-based-decisions-in-governed-systems.md | 10 ++--- docs/labs/decision-before-execution.md | 8 ++-- .../decision-receipts-and-acknowledgment.md | 10 ++--- docs/labs/governed-ai-tool-gateway.md | 6 +-- docs/labs/hidden-execution-side-effect.md | 6 +-- ...-context-and-explicit-decision-outcomes.md | 8 ++-- ...y-simulation-and-change-impact-analysis.md | 12 +++--- .../labs/replay-protection-and-bounded-use.md | 6 +-- ...ped-capability-and-host-owned-execution.md | 8 ++-- .../replay-protection-and-bounded-use.md | 16 +++---- ...secret-handling-across-trust-boundaries.md | 2 +- .../secure-logging-across-trust-boundaries.md | 2 +- ...ication-key-custody-and-tamper-evidence.md | 12 +++--- ...chain-integrity-for-dotnet-repositories.md | 8 ++-- .../trust-boundaries-and-least-privilege.md | 4 +- docs/tutorials/decision-before-execution.md | 14 +++---- .../decision-receipts-and-acknowledgment.md | 42 +++++++++---------- docs/tutorials/governed-ai-tool-gateway.md | 14 +++---- ...-context-and-explicit-decision-outcomes.md | 32 +++++++------- ...ped-capability-and-host-owned-execution.md | 32 +++++++------- samples/decision-before-execution/README.md | 8 ++-- .../README.md | 12 +++--- samples/governed-ai-tool-gateway/README.md | 18 ++++---- .../README.md | 8 ++-- .../README.md | 10 ++--- .../README.md | 20 ++++----- .../validate-asibackbone-6-api-references.cs | 4 +- 50 files changed, 255 insertions(+), 255 deletions(-) diff --git a/RELEASE-NOTES-1.0.0.md b/RELEASE-NOTES-1.0.0.md index 8fbb682..6c527c7 100644 --- a/RELEASE-NOTES-1.0.0.md +++ b/RELEASE-NOTES-1.0.0.md @@ -19,7 +19,7 @@ The version advances from 0.15.0 to 1.0.0 because the foundational curriculum, p Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. -Use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](https://asibackbone.github.io/Learning/getting-started/learning-1-asibackbone-6-compatibility.html) to translate older material. Use the [AsiBackbone 6.0 API Boundary](https://asibackbone.github.io/Learning/getting-started/asibackbone-6-api-boundary.html) for current high-frequency names and examples. The AsiBackbone [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) remains authoritative for complete implementation migration details. +Use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](https://asibackbone.github.io/Learning/getting-started/learning-1-asibackbone-6-compatibility.html) to translate older material. Use the [AsiBackbone 6.0 API Boundary](https://asibackbone.github.io/Learning/getting-started/asibackbone-6-api-boundary.html) for current high-frequency names and examples. The AsiBackbone [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) remains authoritative for complete implementation migration details. ## Stable Architectural Boundaries diff --git a/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md b/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md index a8cfe41..096cda9 100644 --- a/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md +++ b/docs/advanced/durable-decision-ledgers-and-cryptographic-audit-chains.md @@ -1347,10 +1347,10 @@ The current `AsiBackbone/AsiBackbone` repository contains working primitives tha | Learning concept | Source / test reference | What to inspect | | --- | --- | --- | -| Deterministic canonical payload construction | [`CanonicalPayloadBuilder.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/CanonicalPayloadBuilder.cs) and [`CanonicalPayloadBuilderBranchTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/CanonicalPayloadBuilderBranchTests.cs) | Stable field construction, canonicalization rules, branch coverage, and payload identity. | -| Signed-artifact construction | [`GovernanceArtifactSigner.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/GovernanceArtifactSigner.cs) and [`GovernanceArtifactSignerTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/GovernanceArtifactSignerTests.cs) | How canonical hashes become signing requests and provider-neutral signed-artifact metadata. | -| Verification as a policy outcome | [`GovernanceArtifactVerifier.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Signing/GovernanceArtifactVerifier.cs) and [`VerificationPolicyHandlingTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Signing/VerificationPolicyHandlingTests.cs) | Preflight checks, explicit verification categories, and host policy mapping instead of one trusted boolean. | -| Audit-ledger evidence model | [`AuditLedgerRecord.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`AuditLedgerRecordTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) | The current audit-ledger record shape and its limits; this is adjacent evidence plumbing, not proof of a complete chained ledger. | +| Deterministic canonical payload construction | [`CanonicalPayloadBuilder.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/CanonicalPayloadBuilder.cs) and [`CanonicalPayloadBuilderBranchTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/CanonicalPayloadBuilderBranchTests.cs) | Stable field construction, canonicalization rules, branch coverage, and payload identity. | +| Signed-artifact construction | [`GovernanceArtifactSigner.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/GovernanceArtifactSigner.cs) and [`GovernanceArtifactSignerTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/GovernanceArtifactSignerTests.cs) | How canonical hashes become signing requests and provider-neutral signed-artifact metadata. | +| Verification as a policy outcome | [`GovernanceArtifactVerifier.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Signing/GovernanceArtifactVerifier.cs) and [`VerificationPolicyHandlingTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Signing/VerificationPolicyHandlingTests.cs) | Preflight checks, explicit verification categories, and host policy mapping instead of one trusted boolean. | +| Audit-ledger evidence model | [`AuditLedgerRecord.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`AuditLedgerRecordTests.cs`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) | The current audit-ledger record shape and its limits; this is adjacent evidence plumbing, not proof of a complete chained ledger. | For the broader implementation wording and lifecycle guidance, the existing AsiBackbone articles on signing-ready receipts, verification policy, key rotation, signed audit/outbox records, and cryptographic production posture remain useful context. The source/test links above demonstrate primitives; they still do not prove protected checkpoints, independent witnesses, trusted timestamping, or a production-grade append chain in any deployment. diff --git a/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md b/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md index 03b5aa0..72ccc4e 100644 --- a/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md +++ b/docs/advanced/governed-agent-to-agent-requests-and-multi-agent-execution-boundaries.md @@ -1912,11 +1912,11 @@ The working `AsiBackbone` repository provides useful governance primitives and e Useful implementation specimens include: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — establishes the single-agent boundary where the agent proposes and the host owns policy context, execution, and operational safeguards. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — provides provider-neutral capability metadata that can be studied for subject, operation, resource, audience, scope, policy, and time bindings. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — covers proof, binding, failure, time, and bounded-use concerns at the execution boundary. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provides structured governance evidence that can participate in a larger host-owned decision chain. -- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — reinforces that governance artifacts do not themselves perform the protected side effect. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — establishes the single-agent boundary where the agent proposes and the host owns policy context, execution, and operational safeguards. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — provides provider-neutral capability metadata that can be studied for subject, operation, resource, audience, scope, policy, and time bindings. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — covers proof, binding, failure, time, and bounded-use concerns at the execution boundary. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provides structured governance evidence that can participate in a larger host-owned decision chain. +- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — reinforces that governance artifacts do not themselves perform the protected side effect. These references provide building blocks to inspect. diff --git a/docs/advanced/regional-and-tenant-policy-overlays.md b/docs/advanced/regional-and-tenant-policy-overlays.md index 4855bd5..0bda434 100644 --- a/docs/advanced/regional-and-tenant-policy-overlays.md +++ b/docs/advanced/regional-and-tenant-policy-overlays.md @@ -1242,7 +1242,7 @@ The current `AsiBackbone` repository provides useful specimens for several piece ### Custom Decision Policy Examples -[Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) includes a regional overlay example that preserves an existing block and applies additional local restrictions or acknowledgment requirements. +[Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) includes a regional overlay example that preserves an existing block and applies additional local restrictions or acknowledgment requirements. That example demonstrates one **narrowing-overlay** model. @@ -1250,7 +1250,7 @@ It should not be read as a complete universal global/region/tenant hierarchy. ### Policy Evaluator Pipeline -[Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) shows the distinction between constraint evaluation, base composition, an optional decision policy, and host-owned execution. +[Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) shows the distinction between constraint evaluation, base composition, an optional decision policy, and host-owned execution. Those seams can participate in a host-defined overlay architecture, but the host still needs to define the authority relationship among independently versioned policy layers. diff --git a/docs/ai-integration/agent-memory-and-governance-boundaries.md b/docs/ai-integration/agent-memory-and-governance-boundaries.md index 2522605..9e31e2e 100644 --- a/docs/ai-integration/agent-memory-and-governance-boundaries.md +++ b/docs/ai-integration/agent-memory-and-governance-boundaries.md @@ -1229,10 +1229,10 @@ This article describes a host architecture boundary. It does not imply that `Asi Existing governance primitives remain useful reference points for preserving the distinction between remembered information and current authority: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured current governance outcomes should remain distinct from remembered historical decisions. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — governance evidence has a different lifecycle and purpose from model-visible memory. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — narrow authority should remain an explicit capability concern rather than being reconstructed from memory. -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — reinforces the boundary in which the model proposes and the host owns context, policy, and execution. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured current governance outcomes should remain distinct from remembered historical decisions. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — governance evidence has a different lifecycle and purpose from model-visible memory. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — narrow authority should remain an explicit capability concern rather than being reconstructed from memory. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — reinforces the boundary in which the model proposes and the host owns context, policy, and execution. The host remains responsible for the memory store, retention model, source validation, isolation strategy, retrieval policy, and any product-specific user controls. diff --git a/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md b/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md index bea6833..9e9dcc9 100644 --- a/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md +++ b/docs/ai-integration/ai-governance-observability-and-end-to-end-decision-tracing.md @@ -569,9 +569,9 @@ The working `AsiBackbone` repository contains an `AsiBackbone.OpenTelemetry` pac Useful implementation references include: -- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/README.md) -- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) -- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) +- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/README.md) +- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) +- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) The working package exposes activity events/tags, metrics, stable governance attributes, trace/span identifiers, decision metadata, lifecycle information, and emission outcomes. diff --git a/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md b/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md index 2f8d11b..8a67136 100644 --- a/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md +++ b/docs/ai-integration/governed-multi-tool-workflows-and-recovery-boundaries.md @@ -1372,8 +1372,8 @@ foreach (ProposedWorkflowStep step in workflow.Steps) > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to keep the execution-boundary concept distinct from the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). This sketch intentionally leaves out acknowledgment, escalation, retries, durable persistence, and distributed coordination details. @@ -1681,10 +1681,10 @@ The working `AsiBackbone` repository provides governance artifacts that can part Useful references include: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) Those abstractions do not make `AsiBackbone` a model runtime or workflow engine. diff --git a/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md b/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md index 556829d..0df518a 100644 --- a/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md +++ b/docs/ai-integration/typed-ai-proposed-intent-and-schema-validation-boundaries.md @@ -1824,8 +1824,8 @@ The Learning repository already contains an executable capstone that demonstrate The `AsiBackbone/AsiBackbone` repository provides fuller governance references: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — keeps AI-proposed action separate from host-owned execution. -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — demonstrates acknowledgment as a separate boundary before consequential tool execution. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — keeps AI-proposed action separate from host-owned execution. +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — demonstrates acknowledgment as a separate boundary before consequential tool execution. These working references do not make raw model output authoritative. diff --git a/docs/architecture/cqrs-command-query-separation-and-governed-execution.md b/docs/architecture/cqrs-command-query-separation-and-governed-execution.md index 0747e7d..ab7fa1a 100644 --- a/docs/architecture/cqrs-command-query-separation-and-governed-execution.md +++ b/docs/architecture/cqrs-command-query-separation-and-governed-execution.md @@ -322,8 +322,8 @@ A compact teaching shape might separate the original command from the later exec > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to show the architectural boundary without reproducing the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). ```csharp public sealed record ExecuteDeployment( diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md index e6a9a73..4004cb9 100644 --- a/docs/architecture/glossary.md +++ b/docs/architecture/glossary.md @@ -257,7 +257,7 @@ An allowlist blocks unknown or unapproved tool names from reaching handlers. Mem ## Current AsiBackbone Implementation Correspondence -The Learning glossary is architectural first. The current [`AsiBackbone/AsiBackbone` implementation glossary](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/glossary.md) provides the implementation-side vocabulary and API cross-references. +The Learning glossary is architectural first. The current [`AsiBackbone/AsiBackbone` implementation glossary](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/glossary.md) provides the implementation-side vocabulary and API cross-references. The most direct correspondences are: diff --git a/docs/architecture/governance-spine-and-capability-validation-diagrams.md b/docs/architecture/governance-spine-and-capability-validation-diagrams.md index b2d4056..cdbbeb1 100644 --- a/docs/architecture/governance-spine-and-capability-validation-diagrams.md +++ b/docs/architecture/governance-spine-and-capability-validation-diagrams.md @@ -96,9 +96,9 @@ Use the diagrams as orientation, then follow the corresponding lessons for reaso The Learning diagrams are intentionally framework-neutral. The current AsiBackbone implementation repository contains fuller implementation-facing references: -- [Core Governance Flow Diagrams](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/core-governance-flow-diagrams.md) -- [Core Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +- [Core Governance Flow Diagrams](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/core-governance-flow-diagrams.md) +- [Core Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) Those implementation references may use concrete package types and validation profiles. This Learning page keeps the architectural lesson independent of any one API surface. diff --git a/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md b/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md index 0007443..9bd71bf 100644 --- a/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md +++ b/docs/articles/2026/ci-badge-does-not-prove-package-integrity.md @@ -229,6 +229,6 @@ When the unresolved question is what a hash, signature, or attestation actually If publication authority depends on CI/CD credentials or federated identities, [Secret Handling Across Trust Boundaries](../../security/secret-handling-across-trust-boundaries.md) addresses scope, exposure, rotation, revocation, and compromise response at that boundary. -To compare those ideas with a working package pipeline, inspect the [AsiBackbone package repository workflows](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/.github/workflows). They are an optional specimen for package validation, artifact handoff, SBOM, provenance, and publication-boundary patterns; they are not a specimen for NuGet author signing. +To compare those ideas with a working package pipeline, inspect the [AsiBackbone package repository workflows](https://github.com/AsiBackbone/AsiBackbone/tree/main/.github/workflows). They are an optional specimen for package validation, artifact handoff, SBOM, provenance, and publication-boundary patterns; they are not a specimen for NuGet author signing. The point is not to copy one repository's release stack. The point is to explain, narrowly and verifiably, how reviewed source became the artifact a consumer received. diff --git a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md b/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md index c51a545..13be91c 100644 --- a/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md +++ b/docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md @@ -1493,9 +1493,9 @@ The `AsiBackbone` repository provides the governance-side abstractions that make Relevant references include: -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — carries policy identity and structured outcomes without owning persistence. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provider-neutral governance evidence that can be persisted by a host-selected durable store. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — carries scoped authority metadata while leaving storage and execution ownership to the host. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — carries policy identity and structured outcomes without owning persistence. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — provider-neutral governance evidence that can be persisted by a host-selected durable store. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — carries scoped authority metadata while leaving storage and execution ownership to the host. The architectural bridge is: diff --git a/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md b/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md index 4f2ff9d..632fd83 100644 --- a/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md +++ b/docs/aspnetcore/structured-logging-without-sensitive-data-sprawl.md @@ -947,7 +947,7 @@ Learning keeps the examples provider-neutral and intentionally small. | Repository decision behind the current logging provider | [ADR-0001: Use Structured Serilog Logging](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/docs/adr/0001-use-structured-serilog-logging.md) | Review why the template chose Serilog for its own structured-logging baseline, including the alternatives and tradeoffs it recorded. The Learning guidance remains provider-neutral. | | Tracing and metrics as separate observability concerns | [`OpenTelemetryServiceExtensions.cs`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/Extensions/OpenTelemetryServiceExtensions.cs) | Independent tracing/metrics enablement, ASP.NET Core and `HttpClient` instrumentation, service resource identity, and optional OTLP export. | | Governance evidence rather than ordinary telemetry | [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) | The Learning boundary between operational logs and structured decision/acknowledgment/execution evidence. | -| Production-oriented audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | How the governance implementation discusses safe metadata handling across audit and telemetry surfaces without collapsing them into one store. | +| Production-oriented audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | How the governance implementation discusses safe metadata handling across audit and telemetry surfaces without collapsing them into one store. | Use these repositories as working specimens rather than as package requirements for the tutorial. diff --git a/docs/getting-started/asibackbone-6-api-boundary.md b/docs/getting-started/asibackbone-6-api-boundary.md index 2337d88..601d947 100644 --- a/docs/getting-started/asibackbone-6-api-boundary.md +++ b/docs/getting-started/asibackbone-6-api-boundary.md @@ -7,11 +7,11 @@ description: Distinguish Learning teaching models from the finalized AsiBackbone 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. +2. **AsiBackbone 6.0 API examples** use the finalized public names and namespaces from the implementation repository's `main` 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. +> **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/main/docs/articles/upgrade-500-to-600.md) for exact package syntax. ## Executable Sample Package Policy @@ -27,7 +27,7 @@ If a future sample adds an `AsiBackbone.*` package reference, it must pin a rele ## 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 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/main/docs/articles/public-api-naming-600.md). The names most often used by Learning material are: @@ -88,7 +88,7 @@ var evaluator = new DefaultGovernancePolicyEvaluator( For dependency injection, prefer a factory that resolves the host's configured constraints, contributors, decision policy, `IOptions.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). +Inspect the exact implementation in [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs), its [`CreateBuilder` factory](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.Factory.cs), and [`GovernancePolicyEvaluatorBuilder`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/GovernancePolicyEvaluatorBuilder.cs). ## Mark Endpoint Policy Metadata @@ -106,7 +106,7 @@ 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. +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/main/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceRouteBuilderExtensions.cs) behavior. For attribute-based endpoint metadata, the 5.x `RequireGovernancePolicyAttribute` type was renamed to `GovernancePolicyAttribute` in 6.0. @@ -130,7 +130,7 @@ The 5.x `RequireGovernancePolicyAttribute` type was renamed to `GovernancePolicy `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. +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/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) and [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) source before adopting a package integration. ## Review Checklist @@ -141,7 +141,7 @@ Before publishing an API-facing Learning change: - use finalized 6.0 names and namespaces; - use `GovernancePolicyAttribute`, not the 5.x `RequireGovernancePolicyAttribute`, for attribute-based endpoint metadata; - 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; +- link implementation source to `main`, 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. diff --git a/docs/getting-started/learning-1-asibackbone-6-compatibility.md b/docs/getting-started/learning-1-asibackbone-6-compatibility.md index 0bc8a42..d922bd5 100644 --- a/docs/getting-started/learning-1-asibackbone-6-compatibility.md +++ b/docs/getting-started/learning-1-asibackbone-6-compatibility.md @@ -6,7 +6,7 @@ description: Understand the Learning 1.0 and AsiBackbone 6.0 baseline, changes f > **Production baseline:** Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. -Learning 1.0 is the educational companion to AsiBackbone 6.0. That alignment means current Learning terminology, API-facing examples, and implementation links are interpreted against the `release/6.0.0` product baseline. +Learning 1.0 is the educational companion to AsiBackbone 6.0. That alignment means current Learning terminology, API-facing examples, and implementation links are interpreted against the `main` product baseline. It does **not** mean that Learning depends on the AsiBackbone packages. Most Learning samples remain framework-neutral teaching models, and the architecture lessons are intended to remain useful even when you implement them without AsiBackbone. @@ -25,7 +25,7 @@ The ownership rule is intentionally simple: > **Learning teaches the architecture. AsiBackbone defines the released API and runtime truth.** -The implementation repository documents the same boundary in its [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/documentation-ownership.md) guidance. +The implementation repository documents the same boundary in its [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/documentation-ownership.md) guidance. ## What Changed Conceptually @@ -77,7 +77,7 @@ Examples include: | `IAsiBackboneAcknowledgmentChallengeService` | `IAcknowledgmentChallengeService` | | `RequireGovernancePolicyAttribute` | `GovernancePolicyAttribute` | -This is a representative teaching-oriented subset, not the complete rename inventory. Use the authoritative [6.0 public API naming convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md) for the full list. +This is a representative teaching-oriented subset, not the complete rename inventory. Use the authoritative [6.0 public API naming convention](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/public-api-naming-600.md) for the full list. ### Learning can stay simpler than the product surface @@ -114,7 +114,7 @@ AsiBackbone 6.0 removes exactly seven public members whose obsolete compatibilit The 5.x `RequireGovernancePolicyAttribute` type was also renamed to `GovernancePolicyAttribute` in 6.0 so the attribute and route-builder paths use the same marker terminology. That type rename is separate from the seven obsolete-member removals. -Do not use this page as the complete implementation migration checklist. The authoritative [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) guide contains the exact removed-member inventory, replacement guidance, dependency-injection notes, and complete public type rename table. +Do not use this page as the complete implementation migration checklist. The authoritative [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) guide contains the exact removed-member inventory, replacement guidance, dependency-injection notes, and complete public type rename table. ## What Did Not Change @@ -176,11 +176,11 @@ Use these sources in order, depending on the question: 1. [Learning Architecture Glossary](../architecture/glossary.md) — canonical Learning definitions and teaching vocabulary. 2. [AsiBackbone 6.0 API Boundary](asibackbone-6-api-boundary.md) — the high-frequency 6.0 package names and examples that Learning readers are most likely to copy. -3. [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) — authoritative breaking-change and migration guidance. -4. [6.0 Public API Naming Convention](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/public-api-naming-600.md) — complete public type rename inventory and retained-name decisions. -5. [AsiBackbone API Terminology Map](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/terminology-map.md) — mapping from Learning concepts to concrete product APIs. -6. [AsiBackbone API Glossary](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/glossary.md) — implementation-specific meanings, invariants, and host responsibilities. -7. [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/documentation-ownership.md) — the source-of-truth boundary between the two repositories. +3. [Upgrade from 5.x to 6.0](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) — authoritative breaking-change and migration guidance. +4. [6.0 Public API Naming Convention](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/public-api-naming-600.md) — complete public type rename inventory and retained-name decisions. +5. [AsiBackbone API Terminology Map](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/terminology-map.md) — mapping from Learning concepts to concrete product APIs. +6. [AsiBackbone API Glossary](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/glossary.md) — implementation-specific meanings, invariants, and host responsibilities. +7. [Documentation Ownership](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/documentation-ownership.md) — the source-of-truth boundary between the two repositories. When those sources overlap, exact API/runtime behavior belongs to `AsiBackbone/AsiBackbone`; architecture teaching and canonical Learning terminology belong to `AsiBackbone/Learning`. @@ -196,7 +196,7 @@ If you are moving a code example or internal document from an AsiBackbone 5.x ba - [ ] Replace 5.x `RequireGovernancePolicyAttribute` usage with `GovernancePolicyAttribute`. - [ ] Use **decision receipt** in current teaching prose while preserving historical wording in historical release material. - [ ] Use **acknowledgment** as the ordinary teaching term and reserve **handshake** for the actual protocol or exact retained type names. -- [ ] Keep implementation links pinned to `release/6.0.0` when documenting the Learning 1.0 production baseline. +- [ ] Keep implementation links pinned to `main` when documenting the Learning 1.0 production baseline. - [ ] Verify exact behavior in the implementation repository instead of copying a second runtime contract into Learning. ## Continue diff --git a/docs/getting-started/learning-1-release-readiness.md b/docs/getting-started/learning-1-release-readiness.md index 708460a..6145409 100644 --- a/docs/getting-started/learning-1-release-readiness.md +++ b/docs/getting-started/learning-1-release-readiness.md @@ -8,7 +8,7 @@ description: Review the dated validation evidence, compatibility boundary, known **Review outcome:** Approved as a release candidate, subject to the final pull-request checks, merge to protected `main`, and tag-bound publication checks described below.\ **Learning content baseline reviewed:** [`2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a`](https://github.com/AsiBackbone/Learning/commit/2aa3f8bb487809bc2bcd0fc83baffc4c4256c62a) on `release/1.0.0` -**Aligned implementation baseline:** AsiBackbone `6.0.0`, using the authoritative [`release/6.0.0`](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0) source and [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-500-to-600.md) +**Aligned implementation baseline:** AsiBackbone `6.0.0`, using the authoritative [`main`](https://github.com/AsiBackbone/AsiBackbone/tree/main) source and [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) This record captures the final pre-release review of Learning 1.0.0. Follow-up changes after the reviewed content baseline update release metadata, add permanent redirect stubs, replace release-branch links with durable default-branch or commit-permalink links, and correct this record. The pull request containing those changes must pass the required documentation, link, sample, formatting, security, and workflow checks; the resulting merge commit, rather than the baseline commit alone, becomes the release candidate. @@ -33,7 +33,7 @@ The three implementation issues remain open because their closing pull requests - The [canonical glossary](../architecture/glossary.md) introduces context, constraints, decisions, decision receipts, acknowledgment, capability grants, outbox delivery, signing, and advanced controls progressively. - Current package-facing guidance uses the finalized 6.0 names and distinguishes historical 5.x names from current syntax. -- The API-reference validator rejects removed 5.x APIs and implementation links that do not target `release/6.0.0`, except in the two explicitly historical migration/reference pages. +- The API-reference validator rejects removed 5.x APIs and implementation links that do not target `main`, except in the two explicitly historical migration/reference pages. - Learning-owned samples are framework-neutral teaching models. Their indexes and README files identify that boundary and direct readers to the exact 6.0 API guide. - Previously published pages renamed for 6.0 terminology retain redirect stubs, and the renamed sample retains a pointer at its former repository path. - Getting Started, the root README, and primary navigation identify Learning 1.0 as the production documentation baseline aligned with AsiBackbone 6.0. diff --git a/docs/governance/constraint-composition-and-policy-precedence.md b/docs/governance/constraint-composition-and-policy-precedence.md index bbed2c0..1e48451 100644 --- a/docs/governance/constraint-composition-and-policy-precedence.md +++ b/docs/governance/constraint-composition-and-policy-precedence.md @@ -1229,12 +1229,12 @@ The `AsiBackbone/AsiBackbone` repository provides a fuller implementation of the | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Core policy vocabulary | [Core Domain Language](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/core-domain-language.md) | Context, constraints, active policy structure, decisions, and host boundary | -| Constraint evaluation and base composition | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) | Deny/warning/allow composition, empty-policy behavior, short-circuiting, exception posture, and reason handling | -| Post-composition policy | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Warning preservation, regional overlays, acknowledgment, escalation, and host-owned execution | -| Concrete evaluator | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Source-level evaluation and composition behavior | -| Decision-policy contract | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | Boundary between base composition and host/domain decision transformation | -| End-to-end behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable policy-evaluator invariants | +| Core policy vocabulary | [Core Domain Language](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/core-domain-language.md) | Context, constraints, active policy structure, decisions, and host boundary | +| Constraint evaluation and base composition | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) | Deny/warning/allow composition, empty-policy behavior, short-circuiting, exception posture, and reason handling | +| Post-composition policy | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Warning preservation, regional overlays, acknowledgment, escalation, and host-owned execution | +| Concrete evaluator | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Source-level evaluation and composition behavior | +| Decision-policy contract | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | Boundary between base composition and host/domain decision transformation | +| End-to-end behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable policy-evaluator invariants | The Learning article remains framework-neutral on purpose. diff --git a/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md b/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md index 010bf6d..a630e2c 100644 --- a/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md +++ b/docs/governance/deterministic-and-probabilistic-inputs-in-policy-evaluation.md @@ -2214,13 +2214,13 @@ The `AsiBackbone/AsiBackbone` repository provides useful implementation surfaces | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Policy-context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimal context boundary consumed by constraints. | -| Concrete host-provided context | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation, policy identity, and normalized metadata supplied by the host. | -| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation and base decision composition. | -| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A host/domain boundary where broader policy can interpret composed results and context. | -| Structured governance result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity returned to the host. | -| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Examples of host-provided risk metadata influencing a final decision while execution remains host-owned. | -| Execution enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | The boundary that keeps decisions and context separate from the protected side effect. | +| Policy-context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimal context boundary consumed by constraints. | +| Concrete host-provided context | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation, policy identity, and normalized metadata supplied by the host. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation and base decision composition. | +| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A host/domain boundary where broader policy can interpret composed results and context. | +| Structured governance result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity returned to the host. | +| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Examples of host-provided risk metadata influencing a final decision while execution remains host-owned. | +| Execution enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | The boundary that keeps decisions and context separate from the protected side effect. | The implementation does not require a particular ML platform, scoring service, probability representation, or calibration method. diff --git a/docs/governance/escalation-patterns-in-governed-systems.md b/docs/governance/escalation-patterns-in-governed-systems.md index ed33dc7..56f2816 100644 --- a/docs/governance/escalation-patterns-in-governed-systems.md +++ b/docs/governance/escalation-patterns-in-governed-systems.md @@ -2031,13 +2031,13 @@ The `AsiBackbone/AsiBackbone` repository already exposes the structured outcome | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Escalation outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework outcome that includes `EscalationRecommended`. | -| Structured decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reason codes, correlation/trace identifiers, and policy identity that a host can preserve before routing. | -| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The host/domain boundary where broader policy can refine a composed result. | -| Escalation example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | A gateway-readiness example that can return escalation without performing the protected action. | -| Audit evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | Structured evidence that can preserve decision outcome, reasons, policy identity, and correlation. | -| Host execution boundary | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why a governance result still requires explicit host enforcement before side effects. | -| High-consequence scenario | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | A scenario where escalation-recommended outcomes remain non-executable and host-controlled. | +| Escalation outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework outcome that includes `EscalationRecommended`. | +| Structured decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reason codes, correlation/trace identifiers, and policy identity that a host can preserve before routing. | +| Post-composition decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The host/domain boundary where broader policy can refine a composed result. | +| Escalation example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | A gateway-readiness example that can return escalation without performing the protected action. | +| Audit evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | Structured evidence that can preserve decision outcome, reasons, policy identity, and correlation. | +| Host execution boundary | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why a governance result still requires explicit host enforcement before side effects. | +| High-consequence scenario | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | A scenario where escalation-recommended outcomes remain non-executable and host-controlled. | A host may implement escalation persistence and routing using: diff --git a/docs/governance/human-in-the-loop-governance-workflows.md b/docs/governance/human-in-the-loop-governance-workflows.md index b413a12..649d8d2 100644 --- a/docs/governance/human-in-the-loop-governance-workflows.md +++ b/docs/governance/human-in-the-loop-governance-workflows.md @@ -1741,12 +1741,12 @@ The `AsiBackbone/AsiBackbone` repository contains implementation material that s | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Decision policy boundary | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | How host-owned decision policy can require acknowledgment or escalation without performing the protected action. | -| High-consequence administrative flow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | Host ownership of identity, authorization, UI, persistence, decision handling, acknowledgment, audit, and execution. | -| Audit lifecycle evidence | [Decision Receipt Observability Schema](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/decision-receipt-observability-schema.md) | Structured decision and execution evidence suitable for correlation across lifecycle stages. | -| Host enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why decisions and policy results do not themselves perform the protected operation. | -| Governance decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The structured outcome consumed by a host-controlled workflow. | -| Audit lifecycle vocabulary | [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | Lifecycle-oriented audit stages that can participate in broader host-owned workflow evidence. | +| Decision policy boundary | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | How host-owned decision policy can require acknowledgment or escalation without performing the protected action. | +| High-consequence administrative flow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | Host ownership of identity, authorization, UI, persistence, decision handling, acknowledgment, audit, and execution. | +| Audit lifecycle evidence | [Decision Receipt Observability Schema](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/decision-receipt-observability-schema.md) | Structured decision and execution evidence suitable for correlation across lifecycle stages. | +| Host enforcement | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why decisions and policy results do not themselves perform the protected operation. | +| Governance decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The structured outcome consumed by a host-controlled workflow. | +| Audit lifecycle vocabulary | [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | Lifecycle-oriented audit stages that can participate in broader host-owned workflow evidence. | The implementation references do not require a particular human-review UI, queue, workflow engine, or persistence product. diff --git a/docs/governance/policy-versioning-and-decision-provenance.md b/docs/governance/policy-versioning-and-decision-provenance.md index b97cd9f..b2969ba 100644 --- a/docs/governance/policy-versioning-and-decision-provenance.md +++ b/docs/governance/policy-versioning-and-decision-provenance.md @@ -1385,7 +1385,7 @@ The current `AsiBackbone` implementation provides several useful working referen ### GovernanceDecision -[`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) carries optional `PolicyVersion` and `PolicyHash` values on the decision itself. +[`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) carries optional `PolicyVersion` and `PolicyHash` values on the decision itself. That demonstrates the important boundary that policy evidence can travel with the result rather than remaining only in transient evaluation context. @@ -1393,17 +1393,17 @@ The current type does not define a dedicated `PolicyId` property. A host that ne ### DecisionReceipt -[`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) carries optional policy version/hash evidence and preserves those values when receipt is created from a `GovernanceDecision`. +[`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) carries optional policy version/hash evidence and preserves those values when receipt is created from a `GovernanceDecision`. That is an example of policy evidence propagating into later governance evidence. ### CapabilityTokenGrant -[`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) can carry optional `PolicyVersion` and `PolicyHash` bindings into short-lived execution authority. +[`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) can carry optional `PolicyVersion` and `PolicyHash` bindings into short-lived execution authority. ### CapabilityGrantValidationOptions -[`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) allows an execution boundary to state expected policy version/hash values during capability validation. +[`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) allows an execution boundary to state expected policy version/hash values during capability validation. These references show concrete implementation seams. diff --git a/docs/governance/practical-policy-testing-and-decision-table-strategies.md b/docs/governance/practical-policy-testing-and-decision-table-strategies.md index 0e9f41b..824b79a 100644 --- a/docs/governance/practical-policy-testing-and-decision-table-strategies.md +++ b/docs/governance/practical-policy-testing-and-decision-table-strategies.md @@ -1563,8 +1563,8 @@ The Learning repository and the `AsiBackbone` implementation repository contain | --- | --- | --- | | Explicit outcome assertions | [`DecisionOutcomeTests`](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/Tests/DecisionOutcomeTests.cs) | Direct assertions for `Denied`, `Deferred`, `AcknowledgmentRequired`, and `Allowed` | | Table-like scenario coverage | [Policy Context sample program](https://github.com/AsiBackbone/Learning/blob/main/samples/policy-context-and-explicit-decision-outcomes/Sample/Program.cs) | Named policy scenarios covering all major disable-account outcomes | -| Composition invariants | [`DefaultAsiBackbonePolicyEvaluatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/DefaultAsiBackbonePolicyEvaluatorTests.cs) | Compatibility-retained test fixture covering the 6.0 `DefaultGovernancePolicyEvaluator`: empty-policy behavior, warning/denial composition, exception posture, short-circuiting, and decision-policy interaction | -| End-to-end evaluator behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Policy-evaluator invariants across the real implementation pipeline | +| Composition invariants | [`DefaultAsiBackbonePolicyEvaluatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/DefaultAsiBackbonePolicyEvaluatorTests.cs) | Compatibility-retained test fixture covering the 6.0 `DefaultGovernancePolicyEvaluator`: empty-policy behavior, warning/denial composition, exception posture, short-circuiting, and decision-policy interaction | +| End-to-end evaluator behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Policy-evaluator invariants across the real implementation pipeline | | Policy provenance | [Policy Versioning and Decision Provenance](policy-versioning-and-decision-provenance.md) | Historical identity, drift, freshness, and version/hash boundaries | | Bounded execution authority | [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) | Replay/use-state validation at the execution boundary | diff --git a/docs/governance/risk-based-decisions-in-governed-systems.md b/docs/governance/risk-based-decisions-in-governed-systems.md index fbaea09..64a9890 100644 --- a/docs/governance/risk-based-decisions-in-governed-systems.md +++ b/docs/governance/risk-based-decisions-in-governed-systems.md @@ -1567,11 +1567,11 @@ This tutorial is framework-neutral, but the `AsiBackbone/AsiBackbone` repository | Learning concept | Working implementation reference | What to inspect | | --- | --- | --- | -| Host/domain decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary where host policy can refine a decision without executing the protected action. | -| Risk-aware policy example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | The regional overlay example reads host-provided `risk` metadata and can require acknowledgment while preserving host-owned execution. | -| High-risk workflow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/high-risk-administrative-action.md) | A concrete scenario where actor, target, risk, policy metadata, acknowledgment, decision receipt, and host execution remain separate responsibilities. | -| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The outcome and reason structure consumed by the host. | -| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation, base composition, and the optional decision-policy boundary. | +| Host/domain decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary where host policy can refine a decision without executing the protected action. | +| Risk-aware policy example | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | The regional overlay example reads host-provided `risk` metadata and can require acknowledgment while preserving host-owned execution. | +| High-risk workflow | [High-Risk Administrative Action Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/high-risk-administrative-action.md) | A concrete scenario where actor, target, risk, policy metadata, acknowledgment, decision receipt, and host execution remain separate responsibilities. | +| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | The outcome and reason structure consumed by the host. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Constraint evaluation, base composition, and the optional decision-policy boundary. | The implementation repository does not require every host to adopt the qualitative model used in this tutorial. diff --git a/docs/labs/decision-before-execution.md b/docs/labs/decision-before-execution.md index 530df89..f157d1f 100644 --- a/docs/labs/decision-before-execution.md +++ b/docs/labs/decision-before-execution.md @@ -346,10 +346,10 @@ Use `git status` before restoring anything so that you understand which local ch - [Decision Before Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-before-execution/README.md) — return to the known executable baseline. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — continue into richer policy facts and structured outcomes. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) - compare your lab behavior with fuller evaluator tests. -- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) - follow the complete documented lifecycle from proposal toward execution. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) - examine the fuller execution-authority boundary. -- [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) - inspect a concrete ASP.NET Core enforcement layer. +- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) - compare your lab behavior with fuller evaluator tests. +- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) - follow the complete documented lifecycle from proposal toward execution. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) - examine the fuller execution-authority boundary. +- [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) - inspect a concrete ASP.NET Core enforcement layer. --- diff --git a/docs/labs/decision-receipts-and-acknowledgment.md b/docs/labs/decision-receipts-and-acknowledgment.md index e52f40e..ae71483 100644 --- a/docs/labs/decision-receipts-and-acknowledgment.md +++ b/docs/labs/decision-receipts-and-acknowledgment.md @@ -651,11 +651,11 @@ Use `git status` first so you understand which local work will be affected. - [Policy Context and Explicit Decision Outcomes lab](policy-context-and-explicit-decision-outcomes.md) — revisit explicit decision inputs, reason codes, and precedence. - [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) — continue from acknowledged governance requirements into narrow execution authority. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — compare the teaching challenge with the fuller framework handshake request. -- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the working accepted/rejected acknowledgment model. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — compare the lab's small evidence model with the framework's richer decision receipt. -- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) — review the fuller handshake lifecycle. -- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) — study production-oriented durability and delivery concerns after completing the in-memory exercise. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — compare the teaching challenge with the fuller framework handshake request. +- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the working accepted/rejected acknowledgment model. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — compare the lab's small evidence model with the framework's richer decision receipt. +- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) — review the fuller handshake lifecycle. +- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) — study production-oriented durability and delivery concerns after completing the in-memory exercise. --- diff --git a/docs/labs/governed-ai-tool-gateway.md b/docs/labs/governed-ai-tool-gateway.md index f028794..e83a29d 100644 --- a/docs/labs/governed-ai-tool-gateway.md +++ b/docs/labs/governed-ai-tool-gateway.md @@ -950,9 +950,9 @@ git restore samples/governed-ai-tool-gateway - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — distinguish capability replay protection from request idempotency, external retry semantics, and exactly-once execution claims. - [Safe Degraded Mode and Fail-Safe Governance](safe-degraded-mode-and-fail-safe-governance.md) — continue from the gateway's single fail-open exercise into explicit policy, replay, verification, acknowledgment, evidence, and executor failure behavior. - [Decision Receipts and Acknowledgment lab](decision-receipts-and-acknowledgment.md) — revisit responsibility and evidence boundaries before they are composed into AI tool execution. -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — compare the teaching gateway with the working framework's scenario documentation. -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — compare acknowledgment handling with the implementation-oriented guidance. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — examine production-oriented proof, replay, time, binding, and failure considerations. +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — compare the teaching gateway with the working framework's scenario documentation. +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — compare acknowledgment handling with the implementation-oriented guidance. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — examine production-oriented proof, replay, time, binding, and failure considerations. - [Foundational Tutorial Index](../tutorials/index.md) — revisit the complete five-tutorial sequence. --- diff --git a/docs/labs/hidden-execution-side-effect.md b/docs/labs/hidden-execution-side-effect.md index a85ab63..cb3c9ad 100644 --- a/docs/labs/hidden-execution-side-effect.md +++ b/docs/labs/hidden-execution-side-effect.md @@ -574,9 +574,9 @@ Then answer: - [Decision Before Execution sample](https://github.com/AsiBackbone/Learning/blob/main/samples/decision-before-execution/README.md) — compare the corrected sample flow with the flawed starter code in this exercise. - [Decision Before Execution lab](decision-before-execution.md) — practice deliberately breaking and repairing the host execution guard. - [Policy Context and Explicit Decision Outcomes](../tutorials/policy-context-and-explicit-decision-outcomes.md) — continue into richer context and non-boolean outcomes. -- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — inspect the fuller lifecycle from proposal through execution. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) — compare the teaching boundary with the fuller implementation guidance. -- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) — inspect tests that make policy/execution behavior observable in the implementation repository. +- [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — inspect the fuller lifecycle from proposal through execution. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) — compare the teaching boundary with the fuller implementation guidance. +- [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) — inspect tests that make policy/execution behavior observable in the implementation repository. --- diff --git a/docs/labs/policy-context-and-explicit-decision-outcomes.md b/docs/labs/policy-context-and-explicit-decision-outcomes.md index e7f0475..869adc3 100644 --- a/docs/labs/policy-context-and-explicit-decision-outcomes.md +++ b/docs/labs/policy-context-and-explicit-decision-outcomes.md @@ -463,10 +463,10 @@ Use `git status` before restoring anything so that you understand which local ch - [Decision Before Execution lab](decision-before-execution.md) — practice the earlier boundary between decision and host-owned execution. - [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) — continue from structured outcomes into acknowledgment, lineage, and governance evidence. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. -- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) — compare the teaching vocabulary with the working framework. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the fuller decision model and reason metadata. -- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — compare the explicit teaching snapshot with the framework context surface. -- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — inspect fuller constraint evaluation and decision composition. +- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) — compare the teaching vocabulary with the working framework. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the fuller decision model and reason metadata. +- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — compare the explicit teaching snapshot with the framework context surface. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — inspect fuller constraint evaluation and decision composition. --- diff --git a/docs/labs/policy-simulation-and-change-impact-analysis.md b/docs/labs/policy-simulation-and-change-impact-analysis.md index a50105a..ffc2a5d 100644 --- a/docs/labs/policy-simulation-and-change-impact-analysis.md +++ b/docs/labs/policy-simulation-and-change-impact-analysis.md @@ -1389,12 +1389,12 @@ This lab is framework-neutral. | Learning concern | Reference | What to inspect | | --- | --- | --- | -| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | A concrete evaluation pipeline that returns governance decisions without performing host side effects. | -| Structured decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity that can participate in comparison evidence. | -| Host-specific decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A boundary where candidate host/domain decision behavior can be evaluated separately from execution. | -| Policy pipeline explanation | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) | Evaluation and composition boundaries useful when designing replayable policy inputs. | -| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) | Examples of host policy variations that could be compared in a simulation corpus. | -| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Why evaluating an allowed result does not require or imply performing the protected action. | +| Policy evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | A concrete evaluation pipeline that returns governance decisions without performing host side effects. | +| Structured decisions | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, reasons, correlation, and policy identity that can participate in comparison evidence. | +| Host-specific decision policy | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | A boundary where candidate host/domain decision behavior can be evaluated separately from execution. | +| Policy pipeline explanation | [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) | Evaluation and composition boundaries useful when designing replayable policy inputs. | +| Decision-policy examples | [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) | Examples of host policy variations that could be compared in a simulation corpus. | +| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Why evaluating an allowed result does not require or imply performing the protected action. | Learning does not require a particular simulation service, policy-management product, event store, data warehouse, or deployment controller. diff --git a/docs/labs/replay-protection-and-bounded-use.md b/docs/labs/replay-protection-and-bounded-use.md index 2851468..0b4ffa7 100644 --- a/docs/labs/replay-protection-and-bounded-use.md +++ b/docs/labs/replay-protection-and-bounded-use.md @@ -712,9 +712,9 @@ Use `git status` first so you understand which local work will be affected. - [Scoped Capability and Host-Owned Execution lab](scoped-capability-and-host-owned-execution.md) — revisit the broader capability boundary and its introductory single-use exercise. - [Data Access Boundaries and Transaction Reasoning](../aspnetcore/data-access-boundaries-and-transaction-reasoning.md) — bridge `TryConsumeAsync` semantics into durable transaction and persistence design. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — see bounded authority inside a larger AI-assisted execution boundary. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab contract with the working framework seam. -- [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — inspect the working local reference provider and its limitations. -- [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) — compare local concurrency invariant coverage. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab contract with the working framework seam. +- [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — inspect the working local reference provider and its limitations. +- [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) — compare local concurrency invariant coverage. --- diff --git a/docs/labs/scoped-capability-and-host-owned-execution.md b/docs/labs/scoped-capability-and-host-owned-execution.md index eb0fdc2..61d6ce3 100644 --- a/docs/labs/scoped-capability-and-host-owned-execution.md +++ b/docs/labs/scoped-capability-and-host-owned-execution.md @@ -538,10 +538,10 @@ Use `git status` first so you understand which local work will be affected. - [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) — continue into the end-to-end composition where AI may propose and the host retains execution authority. - [Replay Protection and Bounded-Use Authority](../security/replay-protection-and-bounded-use.md) — connect this lab's in-memory single-use exercise to durable, atomic, multi-instance replay protection and idempotency boundaries. - [Replay Protection and Bounded-Use Authority lab](replay-protection-and-bounded-use.md) — continue from the introductory single-use exercise into a dedicated concurrency race, atomic consume repair, bounded-use contention, and failure-window analysis. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — compare the teaching capability with the working framework model. -- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — inspect fuller execution-boundary validation. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab's in-memory replay exercise with the provider-neutral production seam. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — review proof, binding, replay, time, and failure-handling guidance. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — compare the teaching capability with the working framework model. +- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — inspect fuller execution-boundary validation. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) — compare the lab's in-memory replay exercise with the provider-neutral production seam. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — review proof, binding, replay, time, and failure-handling guidance. - [Foundational Tutorial Index](../tutorials/index.md) — view the complete foundational learning path. --- diff --git a/docs/security/replay-protection-and-bounded-use.md b/docs/security/replay-protection-and-bounded-use.md index 1147a89..19fa151 100644 --- a/docs/security/replay-protection-and-bounded-use.md +++ b/docs/security/replay-protection-and-bounded-use.md @@ -1214,8 +1214,8 @@ A host-owned gateway can make the state transition explicit: > `IllustrativeCapabilityCheckResult`, and `CheckAsync` are teaching-only names used > here to keep the replay-protection discussion independent of the released package API. > For the current `AsiBackbone` capability-grant validation surface, see -> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) -> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/upgrade-400-to-500.md). +> [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +> and the [4.0 to 5.0 upgrade guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-400-to-500.md). ```csharp public sealed class ProtectedOperationGateway( @@ -1382,12 +1382,12 @@ The current `AsiBackbone/AsiBackbone` repository contains a fuller capability-us | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Provider-neutral bounded-use state | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | `TryConsumeAsync` combines checking and consumption; Core explicitly leaves durable state, distributed locking, cache consistency, database schema, and replay-window guarantees to the host/provider. | -| Teaching/local in-memory provider | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe in-process use counts and stopped/cancelled state, with explicit documentation that the provider is non-durable, non-distributed, and not production replay protection. | -| Execution validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Proof checks, metadata/binding checks, then optional use-store consumption; missing or unavailable replay state maps to an explicit non-success validation outcome instead of silent execution. | -| Use-check configuration | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | `RequireUseCheck`, `MaxUseCount`, validation time, scope, policy, binding, and proof options. | -| Broader capability guidance | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Proof, issuer/audience/scope, replay/use limits, cancellation/revocation, time windows, and the host-owned security boundary. | -| Executable use-store behavior | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | In-process accepted use, use-limit, stopped/cancelled, and local concurrency behavior. | +| Provider-neutral bounded-use state | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | `TryConsumeAsync` combines checking and consumption; Core explicitly leaves durable state, distributed locking, cache consistency, database schema, and replay-window guarantees to the host/provider. | +| Teaching/local in-memory provider | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe in-process use counts and stopped/cancelled state, with explicit documentation that the provider is non-durable, non-distributed, and not production replay protection. | +| Execution validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Proof checks, metadata/binding checks, then optional use-store consumption; missing or unavailable replay state maps to an explicit non-success validation outcome instead of silent execution. | +| Use-check configuration | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | `RequireUseCheck`, `MaxUseCount`, validation time, scope, policy, binding, and proof options. | +| Broader capability guidance | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Proof, issuer/audience/scope, replay/use limits, cancellation/revocation, time windows, and the host-owned security boundary. | +| Executable use-store behavior | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | In-process accepted use, use-limit, stopped/cancelled, and local concurrency behavior. | The implementation repository is a specimen, not a universal storage prescription. diff --git a/docs/security/secret-handling-across-trust-boundaries.md b/docs/security/secret-handling-across-trust-boundaries.md index c11f33f..6d3219d 100644 --- a/docs/security/secret-handling-across-trust-boundaries.md +++ b/docs/security/secret-handling-across-trust-boundaries.md @@ -1961,7 +1961,7 @@ The organization repositories provide useful specimens for specific boundaries w | CI/workflow authority | [Software Supply-Chain Integrity for .NET Repositories](software-supply-chain-integrity-for-dotnet-repositories.md) | Workflow permissions, checkout credentials, OIDC identity, environment secrets, package credentials, cloud credentials, and the separation between validation and publication authority. | | AI host-owned credential boundary | [Governed AI Tool Gateway](../tutorials/governed-ai-tool-gateway.md) | Why a model proposes an action while the host-owned tool handler keeps infrastructure credentials outside model-visible context. | | Narrow follow-on authority | [Scoped Capability and Host-Owned Execution](../tutorials/scoped-capability-and-host-owned-execution.md) | Actor, operation, resource, audience, time, and use bindings that provide an architectural analogue for reducing credential authority. | -| Audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | Host responsibility for keeping credentials, tokens, connection strings, prompts, and uncontrolled payloads out of durable governance and telemetry paths. | +| Audit/telemetry hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | Host responsibility for keeping credentials, tokens, connection strings, prompts, and uncontrolled payloads out of durable governance and telemetry paths. | Use these as working specimens rather than as a claim that every deployment needs the same secret manager, identity provider, or credential type. diff --git a/docs/security/secure-logging-across-trust-boundaries.md b/docs/security/secure-logging-across-trust-boundaries.md index baf88d9..e543495 100644 --- a/docs/security/secure-logging-across-trust-boundaries.md +++ b/docs/security/secure-logging-across-trust-boundaries.md @@ -1557,7 +1557,7 @@ The organization repositories provide fuller specimens where the same boundaries | Provider levels, local file behavior, and bounded retention | [`appsettings.json`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/appsettings.json) | Logging configuration, correlation/trace properties, file rolling, retention, size limits, and request-logging options. Treat concrete settings as one implementation choice rather than universal security defaults. | | Remote tracing/metrics export boundary | [`OpenTelemetryServiceExtensions.cs`](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/src/ProjectTemplate.Web/Extensions/OpenTelemetryServiceExtensions.cs) | Separate instrumentation and optional OTLP export surfaces that make the remote telemetry boundary visible. | | Governance evidence versus ordinary telemetry | [Decision Receipts and Acknowledgment](../tutorials/decision-receipts-and-acknowledgment.md) | Distinct decision, acknowledgment, execution, persistence, and operational-logging responsibilities. | -| Audit and telemetry metadata hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) | Allowlisted metadata, bounded codes, prompt/body/secret avoidance, provider emission review, retention, access control, and host-owned data-safety responsibility. | +| Audit and telemetry metadata hygiene | [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) | Allowlisted metadata, bounded codes, prompt/body/secret avoidance, provider emission review, retention, access control, and host-owned data-safety responsibility. | | Tamper-evidence boundaries | [Signing, Verification, Key Custody, and Tamper Evidence](signing-verification-key-custody-and-tamper-evidence.md) | Why signing, verification, key custody, and tamper evidence establish narrower properties than confidentiality, authorization, or safe collection. | Use these as specimens, not as proof that every application needs the same provider, collector, storage topology, or governance framework. diff --git a/docs/security/signing-verification-key-custody-and-tamper-evidence.md b/docs/security/signing-verification-key-custody-and-tamper-evidence.md index 2a80ede..0ab102a 100644 --- a/docs/security/signing-verification-key-custody-and-tamper-evidence.md +++ b/docs/security/signing-verification-key-custody-and-tamper-evidence.md @@ -2199,12 +2199,12 @@ The current `AsiBackbone/AsiBackbone` repository provides useful working referen | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Canonical payloads, hashes, signing metadata, and provider-neutral interfaces | [Signing-Ready Receipts and Key Handling](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signing-ready-receipts-and-key-handling.md) | Deterministic canonical payloads, key ID/version metadata, signing seams, and explicit wording limits. | -| Signed is not verified | [Verification Policy and Result Handling](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/verification-policy-and-result-handling.md) | Verification categories, host policy actions, trust-context checks, and failure handling. | -| Rotation and historical verification | [Key Rotation and Retired-Key Verification](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/key-rotation-and-retired-key-verification.md) | Active, retired, revoked, expired, disabled, and unknown key states plus historical verification guidance. | -| Signed governance artifacts | [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signed-audit-and-outbox-records.md) | Signing points for audit and outbox artifacts and the boundary between signed records and tamper-evident trails. | -| Narrow proof authority | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-proof-trust-pinning.md) | Why a cryptographically valid proof can still fail when key, version, provider, algorithm, or policy expectations do not match. | -| Production security wording and non-goals | [Cryptographic Security Posture and Production Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/cryptographic-security-posture.md) | Host responsibilities, provider boundaries, security non-goals, and safe production claims. | +| Canonical payloads, hashes, signing metadata, and provider-neutral interfaces | [Signing-Ready Receipts and Key Handling](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signing-ready-receipts-and-key-handling.md) | Deterministic canonical payloads, key ID/version metadata, signing seams, and explicit wording limits. | +| Signed is not verified | [Verification Policy and Result Handling](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/verification-policy-and-result-handling.md) | Verification categories, host policy actions, trust-context checks, and failure handling. | +| Rotation and historical verification | [Key Rotation and Retired-Key Verification](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/key-rotation-and-retired-key-verification.md) | Active, retired, revoked, expired, disabled, and unknown key states plus historical verification guidance. | +| Signed governance artifacts | [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signed-audit-and-outbox-records.md) | Signing points for audit and outbox artifacts and the boundary between signed records and tamper-evident trails. | +| Narrow proof authority | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-proof-trust-pinning.md) | Why a cryptographically valid proof can still fail when key, version, provider, algorithm, or policy expectations do not match. | +| Production security wording and non-goals | [Cryptographic Security Posture and Production Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/cryptographic-security-posture.md) | Host responsibilities, provider boundaries, security non-goals, and safe production claims. | These references are implementation specimens rather than universal prescriptions. diff --git a/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md b/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md index c9871f8..5d22d0c 100644 --- a/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md +++ b/docs/security/software-supply-chain-integrity-for-dotnet-repositories.md @@ -2083,10 +2083,10 @@ Pinned DocFX tool manifest ### AsiBackbone - [AsiBackbone repository](https://github.com/AsiBackbone/AsiBackbone) -- [AsiBackbone workflow directory](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/.github/workflows) -- [Directory.Build.props](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/Directory.Build.props) -- [Directory.Packages.props](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/Directory.Packages.props) -- [Dependabot configuration](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/.github/dependabot.yml) +- [AsiBackbone workflow directory](https://github.com/AsiBackbone/AsiBackbone/tree/main/.github/workflows) +- [Directory.Build.props](https://github.com/AsiBackbone/AsiBackbone/blob/main/Directory.Build.props) +- [Directory.Packages.props](https://github.com/AsiBackbone/AsiBackbone/blob/main/Directory.Packages.props) +- [Dependabot configuration](https://github.com/AsiBackbone/AsiBackbone/blob/main/.github/dependabot.yml) Inspect it for: diff --git a/docs/security/trust-boundaries-and-least-privilege.md b/docs/security/trust-boundaries-and-least-privilege.md index aa760d0..e2a2293 100644 --- a/docs/security/trust-boundaries-and-least-privilege.md +++ b/docs/security/trust-boundaries-and-least-privilege.md @@ -1127,8 +1127,8 @@ The organization repositories provide fuller specimens where the same reasoning | Learning concept | Working reference | What to inspect | | --- | --- | --- | -| Trusted actor claims | [`HttpGovernanceActorContextOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Actors/HttpGovernanceActorContextOptions.cs) | Privileged software actor types require explicit host opt-in, and the actor-type claim is expected to come from a trusted identity-provider-issued or host-generated source rather than user-controlled request data. | -| Narrow execution authority | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Grants are scoped by issuer, audience, operation-related scopes, policy state, acknowledgment, gateway/resource bindings, time, and bounded use, while host authentication and authorization remain separate responsibilities. | +| Trusted actor claims | [`HttpGovernanceActorContextOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Actors/HttpGovernanceActorContextOptions.cs) | Privileged software actor types require explicit host opt-in, and the actor-type claim is expected to come from a trusted identity-provider-issued or host-generated source rather than user-controlled request data. | +| Narrow execution authority | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Grants are scoped by issuer, audience, operation-related scopes, policy state, acknowledgment, gateway/resource bindings, time, and bounded use, while host authentication and authorization remain separate responsibilities. | | Proxy trust boundary | [Forwarded Headers and Proxy Support](https://github.com/AsiBackbone/NetCoreApplicationTemplate/blob/main/docs/articles/forwarded-headers.md) | Production deployments can configure trusted proxies/networks; application code should not treat raw forwarded headers as authoritative client identity. | Use these as specimens, not as proof that every application requires the same implementation. diff --git a/docs/tutorials/decision-before-execution.md b/docs/tutorials/decision-before-execution.md index 4b04935..8a1ec52 100644 --- a/docs/tutorials/decision-before-execution.md +++ b/docs/tutorials/decision-before-execution.md @@ -699,13 +699,13 @@ Use these references as an implementation map rather than as required dependenci | Tutorial concept | Working reference | What to inspect | | --- | --- | --- | -| Explicit governance decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) and [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | Compare the tutorial's small decision record and outcome enum with the framework's fuller decision model and outcome vocabulary. | -| Context and constraint evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Inspect how the working framework evaluates policy and composes governance decisions without turning the evaluator into the host operation itself. | -| Decision behavior under tests | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Follow concrete tests that exercise the evaluator and verify decision behavior through the policy pipeline. | -| Intent through execution | [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | Compare the tutorial's Request -> Intent -> Context -> Decision -> Execution flow with the fuller documented lifecycle. | -| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) | Examine the framework guidance for keeping execution authority with the host after governance evaluation. | -| Concrete ASP.NET Core host | [`SampleGovernanceController`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/samples/PlainAspNetCoreHost/SampleGovernanceController.cs) | See a working host consume governance behavior in an ASP.NET Core application rather than treating the evaluator as the side-effect owner. | -| ASP.NET Core enforcement layer | [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) and [`AsiBackboneEndpointGovernanceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Endpoints/AsiBackboneEndpointGovernanceTests.cs) | Inspect one concrete request-pipeline enforcement boundary together with the tests that exercise it. | +| Explicit governance decision | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) and [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | Compare the tutorial's small decision record and outcome enum with the framework's fuller decision model and outcome vocabulary. | +| Context and constraint evaluation | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | Inspect how the working framework evaluates policy and composes governance decisions without turning the evaluator into the host operation itself. | +| Decision behavior under tests | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Follow concrete tests that exercise the evaluator and verify decision behavior through the policy pipeline. | +| Intent through execution | [Intent-to-Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | Compare the tutorial's Request -> Intent -> Context -> Decision -> Execution flow with the fuller documented lifecycle. | +| Host-owned execution | [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) | Examine the framework guidance for keeping execution authority with the host after governance evaluation. | +| Concrete ASP.NET Core host | [`SampleGovernanceController`](https://github.com/AsiBackbone/AsiBackbone/blob/main/samples/PlainAspNetCoreHost/SampleGovernanceController.cs) | See a working host consume governance behavior in an ASP.NET Core application rather than treating the evaluator as the side-effect owner. | +| ASP.NET Core enforcement layer | [`EndpointGovernanceMiddleware`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Endpoints/EndpointGovernanceMiddleware.cs) and [`AsiBackboneEndpointGovernanceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Endpoints/AsiBackboneEndpointGovernanceTests.cs) | Inspect one concrete request-pipeline enforcement boundary together with the tests that exercise it. | ### Suggested Reading Order diff --git a/docs/tutorials/decision-receipts-and-acknowledgment.md b/docs/tutorials/decision-receipts-and-acknowledgment.md index 64203dd..e9e05ec 100644 --- a/docs/tutorials/decision-receipts-and-acknowledgment.md +++ b/docs/tutorials/decision-receipts-and-acknowledgment.md @@ -1177,35 +1177,35 @@ The Learning example keeps acknowledgment and decision receipt in one small work | Tutorial concept | Working implementation | What to inspect | | --- | --- | --- | -| Decision-derived acknowledgment request | [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) | `FromDecision` carries the decision's reason, correlation ID, trace ID, policy version, and policy hash into a framework-neutral handshake request. | -| Accepted or rejected actor response | [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) | The separate acknowledgment record preserves handshake identity, responding actor, acknowledgment code, accepted/rejected state, timestamp, and correlation metadata without becoming execution authority. | -| ASP.NET Core challenge boundary | [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) | How an `AcknowledgmentRequired` decision becomes a host-facing challenge and how response handshake IDs and acknowledgment codes are checked before an acknowledgment record is produced. | -| Challenge behavior under tests | [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) | Executable examples for challenge creation, accepted and rejected responses, mismatch handling, correlation, trace, and policy metadata. | -| Structured governance evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | The richer evidence model for actor, operation, outcome, reason codes, correlation/trace data, decision stage, policy identity, and optional observability fields. | -| Append-style lifecycle evidence | [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | How acknowledgment, capability, gateway, and emission progress can be represented as separate correlated events without rewriting the original decision receipt. | -| Lifecycle behavior under tests | [`AuditResidueLifecycleEventTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditResidueLifecycleEventTests.cs) | This compatibility-retained test fixture name exercises the 6.0 `DecisionReceiptLifecycleEvent` stages and shows that later progress can be recorded without mutating the original receipt. | -| Persistence-ready audit record | [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) | The persistence-oriented projection that adds recording time, handshake and acknowledgment references, optional hash/signature metadata, and other durable-record fields. | -| Host-owned audit persistence | [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) | The provider-neutral append and query contract for durable host-owned audit ledger storage. | -| Audit model and persistence tests | [`AuditLedgerRecordTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) and [`IAsiBackboneAuditLedgerStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Audit/IAsiBackboneAuditLedgerStoreTests.cs) | Executable coverage for persistence-ready records and the `IGovernanceAuditLedgerStore` contract; the latter test fixture retains its pre-6.0 filename. | +| Decision-derived acknowledgment request | [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) | `FromDecision` carries the decision's reason, correlation ID, trace ID, policy version, and policy hash into a framework-neutral handshake request. | +| Accepted or rejected actor response | [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) | The separate acknowledgment record preserves handshake identity, responding actor, acknowledgment code, accepted/rejected state, timestamp, and correlation metadata without becoming execution authority. | +| ASP.NET Core challenge boundary | [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) | How an `AcknowledgmentRequired` decision becomes a host-facing challenge and how response handshake IDs and acknowledgment codes are checked before an acknowledgment record is produced. | +| Challenge behavior under tests | [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) | Executable examples for challenge creation, accepted and rejected responses, mismatch handling, correlation, trace, and policy metadata. | +| Structured governance evidence | [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) | The richer evidence model for actor, operation, outcome, reason codes, correlation/trace data, decision stage, policy identity, and optional observability fields. | +| Append-style lifecycle evidence | [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) | How acknowledgment, capability, gateway, and emission progress can be represented as separate correlated events without rewriting the original decision receipt. | +| Lifecycle behavior under tests | [`AuditResidueLifecycleEventTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditResidueLifecycleEventTests.cs) | This compatibility-retained test fixture name exercises the 6.0 `DecisionReceiptLifecycleEvent` stages and shows that later progress can be recorded without mutating the original receipt. | +| Persistence-ready audit record | [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) | The persistence-oriented projection that adds recording time, handshake and acknowledgment references, optional hash/signature metadata, and other durable-record fields. | +| Host-owned audit persistence | [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) | The provider-neutral append and query contract for durable host-owned audit ledger storage. | +| Audit model and persistence tests | [`AuditLedgerRecordTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/AuditLedgerRecordTests.cs) and [`IAsiBackboneAuditLedgerStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Audit/IAsiBackboneAuditLedgerStoreTests.cs) | Executable coverage for persistence-ready records and the `IGovernanceAuditLedgerStore` contract; the latter test fixture retains its pre-6.0 filename. | ### Follow the Acknowledgment and Evidence Path For a code-first inspection, follow these references in order: -1. [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — begin where an acknowledgment-required governance decision is projected into an explicit responsibility-handshake request. -2. [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the separate accepted/rejected actor response. -3. [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) — see one host-integration boundary for challenge creation and response handling. -4. [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) — compare the integration behavior with executable challenge and mismatch scenarios. -5. [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — inspect the evidence object that can retain outcome, reason, correlation, trace, policy, and stage information. -6. [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) — follow how later acknowledgment and execution progress remains separate from the original decision record. -7. [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) — continue from in-memory evidence shape into persistence-ready records and host-owned durable storage. +1. [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — begin where an acknowledgment-required governance decision is projected into an explicit responsibility-handshake request. +2. [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) — inspect the separate accepted/rejected actor response. +3. [`DefaultAcknowledgmentChallengeService`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Handshakes/DefaultAcknowledgmentChallengeService.cs) — see one host-integration boundary for challenge creation and response handling. +4. [`AsiBackboneAcknowledgmentChallengeServiceTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.AspNetCore.Tests/Handshakes/AsiBackboneAcknowledgmentChallengeServiceTests.cs) — compare the integration behavior with executable challenge and mismatch scenarios. +5. [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — inspect the evidence object that can retain outcome, reason, correlation, trace, policy, and stage information. +6. [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) and [`DecisionReceiptLifecycleStage`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleStage.cs) — follow how later acknowledgment and execution progress remains separate from the original decision record. +7. [`AuditLedgerRecord`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/AuditLedgerRecord.cs) and [`IGovernanceAuditLedgerStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/IGovernanceAuditLedgerStore.cs) — continue from in-memory evidence shape into persistence-ready records and host-owned durable storage. For architectural explanation rather than source code, see: -- [Dynamic Liability Handshake](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) — documents the broader acknowledgment/responsibility-handshake lifecycle and explicitly keeps execution policy host-owned. -- [Durable Audit and Outbox Persistence](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) — explains why local durable evidence should precede optional downstream emission and distinguishes append-style audit evidence from outbox delivery state. -- [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/safe-audit-telemetry-data.md) — connects the tutorial's evidence-minimization guidance to production-oriented metadata hygiene. -- [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/signed-audit-and-outbox-records.md) — shows the implemented signing seams while preserving the important distinction between signing and stronger immutability or tamper-evidence claims. +- [Dynamic Liability Handshake](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) — documents the broader acknowledgment/responsibility-handshake lifecycle and explicitly keeps execution policy host-owned. +- [Durable Audit and Outbox Persistence](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) — explains why local durable evidence should precede optional downstream emission and distinguishes append-style audit evidence from outbox delivery state. +- [Safe Audit and Telemetry Data Guidance](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/safe-audit-telemetry-data.md) — connects the tutorial's evidence-minimization guidance to production-oriented metadata hygiene. +- [Signed Audit and Outbox Records](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/signed-audit-and-outbox-records.md) — shows the implemented signing seams while preserving the important distinction between signing and stronger immutability or tamper-evidence claims. The production framework carries considerably more metadata and persistence/signing seams than the teaching model because it supports broader integration, observability, and governance scenarios. The Learning records are teaching-specific shapes rather than copies of framework production types. diff --git a/docs/tutorials/governed-ai-tool-gateway.md b/docs/tutorials/governed-ai-tool-gateway.md index a01cdbb..e169e6c 100644 --- a/docs/tutorials/governed-ai-tool-gateway.md +++ b/docs/tutorials/governed-ai-tool-gateway.md @@ -1574,13 +1574,13 @@ This tutorial is framework-neutral, but the working `AsiBackbone` repository doc Useful references include: -- [`AI Agent Gateway Scenario`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) — positions AsiBackbone as a governance checkpoint between an AI-proposed action and host-owned execution. -- [`Human Approval Before AI Tool Execution`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — focuses on acknowledgment before an AI-proposed consequential action proceeds. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured decision outcomes and reason data. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — structured governance evidence. -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — framework-neutral acknowledgment/handshake request. -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — short-lived, provider-neutral capability metadata for governed follow-on execution. -- [`Capability Grant Hardening`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — execution-boundary validation, proof handling, bindings, failure behavior, and bounded-use guidance. +- [`AI Agent Gateway Scenario`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) — positions AsiBackbone as a governance checkpoint between an AI-proposed action and host-owned execution. +- [`Human Approval Before AI Tool Execution`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) — focuses on acknowledgment before an AI-proposed consequential action proceeds. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — structured decision outcomes and reason data. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) — structured governance evidence. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) — framework-neutral acknowledgment/handshake request. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — short-lived, provider-neutral capability metadata for governed follow-on execution. +- [`Capability Grant Hardening`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — execution-boundary validation, proof handling, bindings, failure behavior, and bounded-use guidance. The working project makes the responsibility boundary explicit: diff --git a/docs/tutorials/policy-context-and-explicit-decision-outcomes.md b/docs/tutorials/policy-context-and-explicit-decision-outcomes.md index 8844b42..e3d2b2f 100644 --- a/docs/tutorials/policy-context-and-explicit-decision-outcomes.md +++ b/docs/tutorials/policy-context-and-explicit-decision-outcomes.md @@ -1076,14 +1076,14 @@ The Learning example intentionally compresses the architecture so the policy bou | Tutorial concept | Working implementation | What to inspect | | --- | --- | --- | -| Framework-neutral policy context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimum context surface shared by evaluators and constraints. | -| Concrete context snapshot | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation ID, policy version/hash, and normalized host-provided metadata. | -| Explicit outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework's allowed, warning, denied, deferred, acknowledgment-required, and escalation-recommended states. | -| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, stable reason codes, correlation and trace identifiers, policy identity, and `CanProceed`. | -| Constraint composition | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | How constraint results are accumulated and composed into a governance decision. | -| Domain- or host-specific final decision rules | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary that can introduce deferred, acknowledgment-required, or escalation-recommended outcomes. | -| Transport mapping | [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) | How a governance decision is translated into HTTP without moving transport concerns into the Core decision model. | -| End-to-end policy behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable examples of evaluator behavior and decision composition. | +| Framework-neutral policy context contract | [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) | The minimum context surface shared by evaluators and constraints. | +| Concrete context snapshot | [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) | Correlation ID, policy version/hash, and normalized host-provided metadata. | +| Explicit outcome vocabulary | [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) | The framework's allowed, warning, denied, deferred, acknowledgment-required, and escalation-recommended states. | +| Structured decision result | [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) | Outcome, stable reason codes, correlation and trace identifiers, policy identity, and `CanProceed`. | +| Constraint composition | [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) | How constraint results are accumulated and composed into a governance decision. | +| Domain- or host-specific final decision rules | [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) | The post-composition boundary that can introduce deferred, acknowledgment-required, or escalation-recommended outcomes. | +| Transport mapping | [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) | How a governance decision is translated into HTTP without moving transport concerns into the Core decision model. | +| End-to-end policy behavior | [`PolicyEvaluatorEndToEndTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/Evaluation/PolicyEvaluatorEndToEndTests.cs) | Executable examples of evaluator behavior and decision composition. | The framework currently distinguishes these outcomes: @@ -1102,17 +1102,17 @@ The Learning example uses the same vocabulary so the conceptual model maps clean For a code-first inspection, follow these references in order: -1. [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — begin with the context contract. -2. [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) — inspect the default concrete context snapshot. -3. [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — follow constraint evaluation and composition. -4. [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) — see where broader host or domain policy can refine the composed result. -5. [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the final structured decision contract. -6. [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) — observe transport mapping after the governance decision exists. +1. [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) — begin with the context contract. +2. [`GovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/GovernanceEvaluationContext.cs) — inspect the default concrete context snapshot. +3. [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) — follow constraint evaluation and composition. +4. [`IGovernanceDecisionPolicy`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/IGovernanceDecisionPolicy.cs) — see where broader host or domain policy can refine the composed result. +5. [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) — inspect the final structured decision contract. +6. [`GovernanceHttpResultMappingExtensions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.AspNetCore/Results/GovernanceHttpResultMappingExtensions.cs) — observe transport mapping after the governance decision exists. For architectural explanation rather than source code, see: -- [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/policy-evaluator-pipeline.md) — explains the evaluator flow and composition boundary. -- [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/custom-decision-policy-examples.md) — shows how host-specific policy can transform a composed result without pushing those rules into individual constraints. +- [Policy Evaluator Pipeline](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/policy-evaluator-pipeline.md) — explains the evaluator flow and composition boundary. +- [Custom Decision Policy Examples](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/custom-decision-policy-examples.md) — shows how host-specific policy can transform a composed result without pushing those rules into individual constraints. The Learning records such as `ActorContext`, `AccountContext`, and `EnvironmentContext` are teaching-specific shapes. They are not copies of framework production types. The important mapping is architectural: **explicit facts enter evaluation, policy interprets those facts, and a structured decision leaves evaluation**. diff --git a/docs/tutorials/scoped-capability-and-host-owned-execution.md b/docs/tutorials/scoped-capability-and-host-owned-execution.md index a91b262..59ef736 100644 --- a/docs/tutorials/scoped-capability-and-host-owned-execution.md +++ b/docs/tutorials/scoped-capability-and-host-owned-execution.md @@ -1351,27 +1351,27 @@ Use these references as an implementation map rather than as required dependenci | Tutorial concept | Working reference | What to inspect | | --- | --- | --- | -| Narrow, short-lived execution authority | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | Compare the tutorial's compact `ExecutionCapability` with the provider-neutral grant metadata for issuer, audience, scopes, time bounds, subject, operation, policy identity, acknowledgment/handshake references, gateway binding, and resource binding. | -| Execution-boundary versus metadata-only validation | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | Compare `CreateExecutionBoundary(...)`, which requires proof and bounded-use validation by default, with the deliberately weaker `CreateMetadataValidation(...)` profile. | -| Capability validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Follow proof verification, issuer/audience checks, time bounds, scopes, policy identity, acknowledgment/handshake references, gateway/resource bindings, and optional bounded-use state before a result can allow continuation. | -| Execution-profile behavior under tests | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | Inspect executable cases for strict execution-boundary defaults, metadata-only behavior, proof failure, unavailable use-state, binding mismatches, expiration, policy evidence, and validation outcomes. | -| Bounded-use and replay-state seam | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Compare the provider-neutral host contract with the explicitly local in-memory reference implementation. Durable, distributed, atomic replay guarantees remain host-owned. | -| Bounded-use behavior under tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Follow first-use, reuse-limit, stopped/cancelled, and local-state behavior without mistaking the in-memory store for distributed replay protection. | -| Production-oriented capability hardening | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) | Review execution-boundary profiles, proof handling, binding checks, clock skew, failure behavior, bounded use, and the explicit boundary between capability validation and host authorization/execution. | -| Proof trust narrowing | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-proof-trust-pinning.md) | See how a host can narrow which otherwise valid signing authority is acceptable for a particular capability-validation context. | -| Host-owned execution lifecycle | [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | Follow the broader governed lifecycle and observe that execution remains deliberately outside the governance spine and under host control. | +| Narrow, short-lived execution authority | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | Compare the tutorial's compact `ExecutionCapability` with the provider-neutral grant metadata for issuer, audience, scopes, time bounds, subject, operation, policy identity, acknowledgment/handshake references, gateway binding, and resource binding. | +| Execution-boundary versus metadata-only validation | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) | Compare `CreateExecutionBoundary(...)`, which requires proof and bounded-use validation by default, with the deliberately weaker `CreateMetadataValidation(...)` profile. | +| Capability validation pipeline | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Follow proof verification, issuer/audience checks, time bounds, scopes, policy identity, acknowledgment/handshake references, gateway/resource bindings, and optional bounded-use state before a result can allow continuation. | +| Execution-profile behavior under tests | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | Inspect executable cases for strict execution-boundary defaults, metadata-only behavior, proof failure, unavailable use-state, binding mismatches, expiration, policy evidence, and validation outcomes. | +| Bounded-use and replay-state seam | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Compare the provider-neutral host contract with the explicitly local in-memory reference implementation. Durable, distributed, atomic replay guarantees remain host-owned. | +| Bounded-use behavior under tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Follow first-use, reuse-limit, stopped/cancelled, and local-state behavior without mistaking the in-memory store for distributed replay protection. | +| Production-oriented capability hardening | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) | Review execution-boundary profiles, proof handling, binding checks, clock skew, failure behavior, bounded use, and the explicit boundary between capability validation and host authorization/execution. | +| Proof trust narrowing | [Capability Proof Trust Pinning](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-proof-trust-pinning.md) | See how a host can narrow which otherwise valid signing authority is acceptable for a particular capability-validation context. | +| Host-owned execution lifecycle | [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | Follow the broader governed lifecycle and observe that execution remains deliberately outside the governance spine and under host control. | ### Follow the Capability Path For a code-first inspection, follow these references in order: -1. [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — begin with the provider-neutral description of narrow follow-on authority. -2. [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) — inspect how the host declares whether it is performing strict execution-boundary validation or intentionally weaker metadata validation. -3. [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — follow the configured proof, time, scope, policy, acknowledgment, gateway, resource, and use-state checks. -4. [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) — compare the API surface with executable allow, deny, and defer behavior. -5. [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — continue into bounded-use state while keeping production persistence and concurrency guarantees host-owned. -6. [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) — put those source types back into their production-oriented security and failure-handling context. -7. [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) — finish at the broader lifecycle and the boundary where the host performs the real side effect. +1. [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) — begin with the provider-neutral description of narrow follow-on authority. +2. [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) — inspect how the host declares whether it is performing strict execution-boundary validation or intentionally weaker metadata validation. +3. [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) — follow the configured proof, time, scope, policy, acknowledgment, gateway, resource, and use-state checks. +4. [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) — compare the API surface with executable allow, deny, and defer behavior. +5. [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) and [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) — continue into bounded-use state while keeping production persistence and concurrency guarantees host-owned. +6. [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) — put those source types back into their production-oriented security and failure-handling context. +7. [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) — finish at the broader lifecycle and the boundary where the host performs the real side effect. ### Teaching Model Versus Working Framework diff --git a/samples/decision-before-execution/README.md b/samples/decision-before-execution/README.md index fd0271c..945a35a 100644 --- a/samples/decision-before-execution/README.md +++ b/samples/decision-before-execution/README.md @@ -99,10 +99,10 @@ Useful experiments include: - [Decision Before Execution tutorial](../../docs/tutorials/decision-before-execution.md) - [Decision Before Execution beginner lab](../../docs/labs/decision-before-execution.md) - [Policy Context and Explicit Decision Outcomes](../../docs/tutorials/policy-context-and-explicit-decision-outcomes.md) -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - compare the teaching decision model with the fuller framework decision type. -- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller policy and constraint evaluation. -- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/host-owned-execution-enforcement.md) - follow the production-oriented execution-boundary guidance. -- [Plain ASP.NET Core Host](https://github.com/AsiBackbone/AsiBackbone/tree/release/6.0.0/samples/PlainAspNetCoreHost) - inspect a concrete host integration. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - compare the teaching decision model with the fuller framework decision type. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller policy and constraint evaluation. +- [Host-Owned Execution Enforcement](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/host-owned-execution-enforcement.md) - follow the production-oriented execution-boundary guidance. +- [Plain ASP.NET Core Host](https://github.com/AsiBackbone/AsiBackbone/tree/main/samples/PlainAspNetCoreHost) - inspect a concrete host integration. ## License diff --git a/samples/decision-receipts-and-acknowledgment/README.md b/samples/decision-receipts-and-acknowledgment/README.md index c0bc894..c1872ae 100644 --- a/samples/decision-receipts-and-acknowledgment/README.md +++ b/samples/decision-receipts-and-acknowledgment/README.md @@ -249,12 +249,12 @@ Useful experiments include: - [Decision Receipts and Acknowledgment intermediate lab](../../docs/labs/decision-receipts-and-acknowledgment.md) - [Policy Context and Explicit Decision Outcomes sample](../policy-context-and-explicit-decision-outcomes/README.md) - [Scoped Capability and Host-Owned Execution](../../docs/tutorials/scoped-capability-and-host-owned-execution.md) -- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) - compare the teaching challenge with the fuller working handshake request. -- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) - inspect the working acknowledgment model. -- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) - compare the small teaching receipt with the framework's decision-outcome record. -- [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) - compare the sample's correlated lifecycle events with the framework's acknowledgment, capability, gateway, and emission stages. -- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/dynamic-liability-handshake.md) - review the fuller handshake lifecycle. -- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/durable-audit-outbox-persistence.md) - review production-oriented persistence and delivery concerns. +- [`LiabilityHandshakeRequest`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeRequest.cs) - compare the teaching challenge with the fuller working handshake request. +- [`LiabilityHandshakeAcknowledgment`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Handshakes/LiabilityHandshakeAcknowledgment.cs) - inspect the working acknowledgment model. +- [`DecisionReceipt`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) - compare the small teaching receipt with the framework's decision-outcome record. +- [`DecisionReceiptLifecycleEvent`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceiptLifecycleEvent.cs) - compare the sample's correlated lifecycle events with the framework's acknowledgment, capability, gateway, and emission stages. +- [`Dynamic Liability Handshake`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/dynamic-liability-handshake.md) - review the fuller handshake lifecycle. +- [`Durable Audit Outbox Persistence`](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/durable-audit-outbox-persistence.md) - review production-oriented persistence and delivery concerns. ## License diff --git a/samples/governed-ai-tool-gateway/README.md b/samples/governed-ai-tool-gateway/README.md index 4ce6b82..a3e8499 100644 --- a/samples/governed-ai-tool-gateway/README.md +++ b/samples/governed-ai-tool-gateway/README.md @@ -489,15 +489,15 @@ The sample exists to make the **ordering and ownership of authority** observable Compare the small teaching implementation with the fuller working `AsiBackbone` repository: -- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/ai-agent-gateway.md) -- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) -- [GovernanceDecision](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) -- [DecisionReceipt](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) -- [CapabilityTokenGrant](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) -- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/README.md) -- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) -- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) +- [AI Agent Gateway Scenario](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/ai-agent-gateway.md) +- [Human Approval Before AI Tool Execution](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/scenarios/human-approval-before-ai-tool-execution.md) +- [GovernanceDecision](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) +- [DecisionReceipt](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Audit/DecisionReceipt.cs) +- [CapabilityTokenGrant](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) +- [`AsiBackbone.OpenTelemetry` README](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/README.md) +- [`OpenTelemetryGovernanceInstrumentation`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceInstrumentation.cs) +- [`OpenTelemetryGovernanceAttributes`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.OpenTelemetry/OpenTelemetryGovernanceAttributes.cs) The Learning sample remains framework-neutral so the architectural pattern can be studied independently of package adoption. diff --git a/samples/policy-context-and-explicit-decision-outcomes/README.md b/samples/policy-context-and-explicit-decision-outcomes/README.md index 3d5392e..33a794e 100644 --- a/samples/policy-context-and-explicit-decision-outcomes/README.md +++ b/samples/policy-context-and-explicit-decision-outcomes/README.md @@ -159,10 +159,10 @@ Useful experiments include: - [Policy Context and Explicit Decision Outcomes learner exercise](../../docs/labs/policy-context-and-explicit-decision-outcomes.md) - [Decision Before Execution sample](../decision-before-execution/README.md) - [Decision Receipts and Acknowledgment](../../docs/tutorials/decision-receipts-and-acknowledgment.md) -- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) - compare the teaching outcome vocabulary with the working framework. -- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - inspect the fuller decision model, reason metadata, correlation, and policy identity. -- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) - compare the sample snapshot with the framework's constraint-evaluation context surface. -- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller constraint composition and decision evaluation. +- [`GovernanceDecisionOutcome`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecisionOutcome.cs) - compare the teaching outcome vocabulary with the working framework. +- [`GovernanceDecision`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs) - inspect the fuller decision model, reason metadata, correlation, and policy identity. +- [`IGovernanceEvaluationContext`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Constraints/IGovernanceEvaluationContext.cs) - compare the sample snapshot with the framework's constraint-evaluation context surface. +- [`DefaultGovernancePolicyEvaluator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/Evaluation/DefaultGovernancePolicyEvaluator.cs) - inspect fuller constraint composition and decision evaluation. ## License diff --git a/samples/replay-protection-and-bounded-use/README.md b/samples/replay-protection-and-bounded-use/README.md index c7e3f6f..9150ba7 100644 --- a/samples/replay-protection-and-bounded-use/README.md +++ b/samples/replay-protection-and-bounded-use/README.md @@ -395,10 +395,10 @@ The sample stays framework-neutral so the atomic state transition remains easy t | Teaching sample | Working reference | What to inspect | | --- | --- | --- | -| `ICapabilityUseStore` | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | Provider-neutral `TryConsumeAsync` semantics and the boundary between Core behavior and host-owned durable state. | -| `AtomicInMemoryCapabilityUseStore` | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe local use counts and explicit non-durable/non-distributed limitations. | -| Concurrent invariant tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Accepted use, use limits, stop/cancel state, and local concurrency behavior. | -| `ProtectedOperationGateway` | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Static/proof validation composed with optional stateful use checking before host-owned execution. | +| `ICapabilityUseStore` | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) | Provider-neutral `TryConsumeAsync` semantics and the boundary between Core behavior and host-owned durable state. | +| `AtomicInMemoryCapabilityUseStore` | [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs) | Thread-safe local use counts and explicit non-durable/non-distributed limitations. | +| Concurrent invariant tests | [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | Accepted use, use limits, stop/cancel state, and local concurrency behavior. | +| `ProtectedOperationGateway` | [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | Static/proof validation composed with optional stateful use checking before host-owned execution. | The framework implementation remains a specimen. Durable replay guarantees are still defined by the host and selected provider. @@ -422,7 +422,7 @@ Continue with the [Replay Protection and Bounded-Use Authority lab](../../docs/l - [Scoped Capability and Host-Owned Execution sample](../scoped-capability-and-host-owned-execution/README.md) - [Data Access Boundaries and Transaction Reasoning](../../docs/aspnetcore/data-access-boundaries-and-transaction-reasoning.md) - [Governed AI Tool Gateway](../../docs/tutorials/governed-ai-tool-gateway.md) -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) ## License diff --git a/samples/scoped-capability-and-host-owned-execution/README.md b/samples/scoped-capability-and-host-owned-execution/README.md index 5129a9c..c35df0f 100644 --- a/samples/scoped-capability-and-host-owned-execution/README.md +++ b/samples/scoped-capability-and-host-owned-execution/README.md @@ -205,11 +205,11 @@ This sample exposes the capability boundary with intentionally small, determinis | Teaching sample | Working reference | Important difference | | --- | --- | --- | -| `ExecutionCapability` | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | The framework grant is provider-neutral metadata and adds fields such as not-before time, policy hash, handshake reference, gateway binding, resource binding, metadata, and schema version. It is explicitly not a bearer-token format. | -| `ExecutionCapabilityValidator` | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) and [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | The framework distinguishes strict execution-boundary validation from intentionally weaker metadata validation and can add proof verification plus bounded-use checks. | -| Deterministic validation scenarios | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | The framework tests cover the richer validation surface, including proof, use-state availability, time, scope, policy, acknowledgment, gateway, and resource behavior. | -| Replay deliberately omitted from the baseline | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs), [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs), and [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | The framework provides a bounded-use seam and a local reference store, while durable distributed replay protection remains a host responsibility. | -| `DisableAccountGateway` owns the simulated side effect | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) and [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) | The framework validates governance authority but deliberately does not become the external account, robotics, deployment, or tool executor. The host still owns the real action. | +| `ExecutionCapability` | [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) | The framework grant is provider-neutral metadata and adds fields such as not-before time, policy hash, handshake reference, gateway binding, resource binding, metadata, and schema version. It is explicitly not a bearer-token format. | +| `ExecutionCapabilityValidator` | [`CapabilityGrantValidationOptions`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidationOptions.cs) and [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) | The framework distinguishes strict execution-boundary validation from intentionally weaker metadata validation and can add proof verification plus bounded-use checks. | +| Deterministic validation scenarios | [`CapabilityGrantValidationProfileTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidationProfileTests.cs) and [`CapabilityGrantValidatorTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/CapabilityGrantValidatorTests.cs) | The framework tests cover the richer validation surface, including proof, use-state availability, time, scope, policy, acknowledgment, gateway, and resource behavior. | +| Replay deliberately omitted from the baseline | [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs), [`InMemoryCapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Storage.InMemory/CapabilityTokens/InMemoryCapabilityGrantUseStore.cs), and [`InMemoryCapabilityGrantUseStoreTests`](https://github.com/AsiBackbone/AsiBackbone/blob/main/tests/AsiBackbone.Core.Tests/CapabilityTokens/InMemoryCapabilityGrantUseStoreTests.cs) | The framework provides a bounded-use seam and a local reference store, while durable distributed replay protection remains a host responsibility. | +| `DisableAccountGateway` owns the simulated side effect | [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) and [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) | The framework validates governance authority but deliberately does not become the external account, robotics, deployment, or tool executor. The host still owns the real action. | The sample's `ResourceVersion` deserves special attention. It exists so a learner can observe state drift directly: @@ -241,11 +241,11 @@ Useful experiments include: - [Scoped Capability and Host-Owned Execution tutorial](../../docs/tutorials/scoped-capability-and-host-owned-execution.md) - [Scoped Capability and Host-Owned Execution intermediate lab](../../docs/labs/scoped-capability-and-host-owned-execution.md) - [Decision Receipts and Acknowledgment sample](../decision-receipts-and-acknowledgment/README.md) -- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) - compare the teaching capability with the working framework's provider-neutral grant metadata. -- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) - inspect fuller execution-context validation. -- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) - review the working seam for bounded-use and replay-state enforcement. -- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/capability-grant-hardening.md) - review production-oriented proof, binding, time, replay, and failure guidance. -- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/release/6.0.0/docs/articles/intent-to-execution-pattern.md) - place capability validation in the fuller governed flow. +- [`CapabilityTokenGrant`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityTokenGrant.cs) - compare the teaching capability with the working framework's provider-neutral grant metadata. +- [`CapabilityGrantValidator`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/CapabilityGrantValidator.cs) - inspect fuller execution-context validation. +- [`ICapabilityGrantUseStore`](https://github.com/AsiBackbone/AsiBackbone/blob/main/src/AsiBackbone.Core/CapabilityTokens/ICapabilityGrantUseStore.cs) - review the working seam for bounded-use and replay-state enforcement. +- [Capability Grant Hardening](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/capability-grant-hardening.md) - review production-oriented proof, binding, time, replay, and failure guidance. +- [Intent to Execution Pattern](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/intent-to-execution-pattern.md) - place capability validation in the fuller governed flow. ## License diff --git a/tools/validate-asibackbone-6-api-references.cs b/tools/validate-asibackbone-6-api-references.cs index b1ca2d3..6650584 100644 --- a/tools/validate-asibackbone-6-api-references.cs +++ b/tools/validate-asibackbone-6-api-references.cs @@ -149,7 +149,7 @@ static partial class AsiBackboneApiReferenceValidator private static partial Regex IdentifierRegex(); [GeneratedRegex( - @"https://github\.com/AsiBackbone/AsiBackbone/(?:blob|tree)/(?!release/6\.0\.0(?:/|\b))[^\s)\]'>]+", + @"https://github\.com/AsiBackbone/AsiBackbone/(?:blob|tree)/(?!main(?:/|\b))[^\s)\]'>]+", RegexOptions.CultureInvariant | RegexOptions.IgnoreCase)] private static partial Regex StaleImplementationLinkRegex(); @@ -237,7 +237,7 @@ private static void ValidateCurrentSymbolsAndLinks( { int lineNumber = GetLineNumber(text, linkMatch.Index); errors.Add( - $"{relativePath}:{lineNumber} links implementation source outside release/6.0.0: {linkMatch.Value}"); + $"{relativePath}:{lineNumber} links implementation source outside main: {linkMatch.Value}"); } } } From 702815607e1983a03605735de0e31ad10a44772a Mon Sep 17 00:00:00 2001 From: Chris Cavell Date: Sat, 19 Sep 2026 14:27:16 -0500 Subject: [PATCH 10/10] fix(release): validate prerelease links --- RELEASE-NOTES-1.0.0.md | 2 +- lychee.toml | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/RELEASE-NOTES-1.0.0.md b/RELEASE-NOTES-1.0.0.md index 6c527c7..ed8ec48 100644 --- a/RELEASE-NOTES-1.0.0.md +++ b/RELEASE-NOTES-1.0.0.md @@ -19,7 +19,7 @@ The version advances from 0.15.0 to 1.0.0 because the foundational curriculum, p Learning 1.0 documents and teaches the AsiBackbone 6.0 production surface. Earlier Learning releases remain historical educational records and may reference APIs or terminology that were valid in earlier AsiBackbone release lines. -Use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](https://asibackbone.github.io/Learning/getting-started/learning-1-asibackbone-6-compatibility.html) to translate older material. Use the [AsiBackbone 6.0 API Boundary](https://asibackbone.github.io/Learning/getting-started/asibackbone-6-api-boundary.html) for current high-frequency names and examples. The AsiBackbone [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) remains authoritative for complete implementation migration details. +Use the [Learning 1.0 and AsiBackbone 6.0 Compatibility Guide](https://github.com/AsiBackbone/Learning/blob/main/docs/getting-started/learning-1-asibackbone-6-compatibility.md) to translate older material. Use the [AsiBackbone 6.0 API Boundary](https://github.com/AsiBackbone/Learning/blob/main/docs/getting-started/asibackbone-6-api-boundary.md) for current high-frequency names and examples. The AsiBackbone [5.x-to-6.0 migration guide](https://github.com/AsiBackbone/AsiBackbone/blob/main/docs/articles/upgrade-500-to-600.md) remains authoritative for complete implementation migration details. ## Stable Architectural Boundaries diff --git a/lychee.toml b/lychee.toml index 255bcec..077fe42 100644 --- a/lychee.toml +++ b/lychee.toml @@ -33,7 +33,11 @@ exclude = [ # return 404 to automated or unauthenticated link checkers. '^https://github\.com/AsiBackbone/Learning/security/advisories/new$', + # These comparisons become resolvable only after the approved merge commit + # is tagged v1.0.0. Keep the canonical changelog targets during PR checks. + '^https://github\.com/AsiBackbone/Learning/compare/v0\.15\.0\.\.\.v1\.0\.0$', + '^https://github\.com/AsiBackbone/Learning/compare/v1\.0\.0\.\.\.HEAD$', # Zenodo DOI occasionally times out for automated link validation. '^https://doi\.org/10\.5281/zenodo\.21938556$' -] \ No newline at end of file +]