Table of Contents

Core API Domain Model

This article documents the concrete domain model of AsiBackbone.Core and the host-neutral API boundary that the rest of the package family builds on.

For canonical architecture definitions, use the ASI Backbone Learning Architecture Glossary. This page owns the product mapping: exact Core types, current outcome semantics, package boundaries, and implementation invariants.

Important

Learning terminology explains the architecture. The released AsiBackbone.Core API defines how this package implements that architecture. If a teaching example is intentionally smaller than the product surface, the product API and runtime documentation remain authoritative for implementation behavior.

Core technical lane

AsiBackbone.Core supports this host-neutral decision lane:

Proposed operation
  -> host builds policy/evaluation context
  -> constraints evaluate
  -> policy evaluator composes GovernanceDecision
  -> optional acknowledgment workflow
  -> decision receipt / lifecycle evidence
  -> optional capability grant
  -> host or gateway decides whether to execute

Core defines the governance primitives for this lane. It does not own the external side effect.

Architecture concept to Core API

Learning concept Core API mapping Core contract
Actor context IGovernanceActorContext Framework-neutral actor data supplied by the host. Core does not authenticate the actor.
Policy context IGovernanceEvaluationContext, GovernanceEvaluationContext Carries the decision-relevant input used by constraints and evaluation.
Constraint IGovernanceConstraint<TContext> Evaluates one policy condition without performing the governed side effect.
Constraint result ConstraintEvaluationResult Carries the constraint's product result/reasons into decision composition.
Policy evaluation IGovernancePolicyEvaluator<TContext> Composes constraint results into a governance decision.
Decision policy IGovernanceDecisionPolicy<TContext> Optional post-composition policy hook that can reshape or raise the final decision.
Decision outcome GovernanceDecision, GovernanceDecisionOutcome Structured product outcome, policy identity metadata, reason data, and correlation information.
Acknowledgment AcknowledgmentRequest, AcknowledgmentResponse Product acknowledgment request/response primitives. The names describe the request/response protocol and do not create legal protection.
Decision receipt DecisionReceipt Structured evidence of the governance decision.
Audit ledger AuditLedgerRecord, IGovernanceAuditLedgerStore Storage-ready record and provider-neutral persistence contract.
Decision receipt sink IDecisionReceiptSink Provider-neutral boundary for receiving decision receipt.
Scoped capability CapabilityGrant, CapabilityGrantValidator Bounded grant data plus product validation logic.
Operation result OperationResult Package-operation success/failure, deliberately separate from governance outcome.

Not every architecture term maps to one class. Policy decision pipeline, host-owned execution, operational gateway, decision provenance, active policy structure, and similar terms describe relationships among APIs and host responsibilities rather than a required universal type.

Decision outcome contract

The current GovernanceDecisionOutcome surface is:

Outcome Product runtime meaning
Allowed Governance permits continuation. The host still decides whether and how to execute.
Warning Governance permits continuation while retaining warning reasons.
Denied The governed operation must not proceed through the protected path.
Deferred The host should pause or route the operation for later evaluation rather than treating the current decision as permission.
AcknowledgmentRequired The host must complete the configured acknowledgment workflow before any later execution path that requires it.
EscalationRecommended The request should move to a higher review/authority path before execution.

Learning may omit Warning from a foundational example. That teaching simplification does not change the released enum.

Core implementation invariants

Decision is not execution

Policy evaluation produces GovernanceDecision; Core does not perform the protected external action. Hosts and gateways own the transition from decision data into real side effects.

Acknowledgment is not authorization

AcknowledgmentResponse records acknowledgment state. It does not authenticate an actor, override authorization, certify compliance, or automatically create execution authority.

Capability grant is bounded authority data

CapabilityGrant is not a general-purpose command channel. Hosts remain responsible for validating the grant at the relevant execution boundary under the configured capability-validation policy.

Audit evidence does not imply storage guarantees

DecisionReceipt, AuditLedgerRecord, and sink/store contracts define evidence shapes and persistence seams. Durability, retention, cryptographic signing, immutability, and tamper evidence depend on the selected implementation and host operations.

Governance outcome is not operation result

A GovernanceDecision can deny or defer before execution begins. An OperationResult describes whether a package operation itself succeeded. The two result families must not be treated as interchangeable.

Core remains host-neutral

Core does not depend on ASP.NET Core, EF Core, a specific identity provider, a database, a cloud platform, or an AI model runtime.

Policy identity and explainability

The product decision model carries policy and correlation metadata so a host can explain which policy state produced a decision.

Current product concepts include:

  • policy version through GovernanceDecision.PolicyVersion;
  • policy fingerprint through GovernanceDecision.PolicyHash;
  • reason codes and reason messages;
  • correlation identifiers that connect decision, audit, lifecycle, and host records.

A policy version is a readable generation label. A policy hash/fingerprint identifies effective policy material more precisely. The product keeps them separate.

Core boundary

In scope for AsiBackbone.Core

  • framework-neutral actor and evaluation-context abstractions;
  • constraint contracts and constraint results;
  • policy evaluation and decision-policy contracts;
  • GovernanceDecision and GovernanceDecisionOutcome;
  • operation-result primitives;
  • acknowledgment/handshake primitives;
  • decision receipt, audit ledger record, sink/store, and lifecycle primitives;
  • capability-grant primitives and validation;
  • policy identity/version/hash and reason metadata;
  • correlation support and shared value objects.

Out of scope for AsiBackbone.Core

  • ASP.NET Core middleware, endpoint metadata, HTTP result mapping, or challenge presentation;
  • EF Core mappings, migrations, and concrete durable database behavior;
  • concrete cloud/provider integrations;
  • production key custody and host trust policy;
  • application authentication and authorization systems;
  • direct AI model hosting, training, inference, or orchestration;
  • host startup logic;
  • robotics or other physical-control implementation;
  • the protected side effect itself.
Edit this page