Coject.Workshop.Metadata 1.4.4

Coject.Workshop.Metadata

Coject.Workshop.Metadata is the ASP.NET-independent, generation-time library owned by Coject Workshop. It provides Workshop audit metadata, explicit custom-procedure contract validation, deterministic generation plans, and C# source-artifact helpers for controller and model audit workflows.

This is generation-time metadata/source-generation support. It is not runtime Controller integration: it does not register controllers, provide middleware or request handling, or execute audit logging at runtime. The package owns explicit custom-procedure metadata and generation; it does not infer business semantics from generated source or transport details.

Target framework

• net8.0

Installation and package boundary

<PackageReference Include="Coject.Workshop.Metadata" Version="1.4.4" />

The package depends exactly on the provider-neutral Coject.Core.Logging.Contracts version 3.1.0. It does not depend on Coject.Core.Logging or Coject.Core.Logging.AspNetCore, and it has no ASP.NET Core framework reference.

Application logging configuration generation

WorkshopApplicationLoggingConfigurationGenerator renders one application-owned CojectLogging JSON block. RenderJson uses fixed property ordering and sorted lists, while Regenerate writes the validated output atomically so repeated generation produces byte-identical content. The default configuration keeps diagnostic storage and typed failure-payload capture disabled; applications opt into those bounded lanes explicitly at their edge.

var configuration = WorkshopApplicationLoggingConfigurationGenerator.Default with
{
    Diagnostics = new WorkshopDiagnosticsConfiguration
    {
        Enabled = true
    }
};

WorkshopApplicationLoggingConfigurationGenerator.Regenerate(
    "appsettings.Sprint108Diagnostics.example.json",
    configuration);

The generator does not create diagnostic, log, or audit controller variants and does not place secrets or persistence-layer values in the generated block. It also does not emit a second diagnostic service name, root path, or file prefix. Diagnostics inherit the Core logging service/environment/instance identity and the Local.Storage.Paths.DiagnosticRoot and Local.Storage.Files.DiagnosticSegment templates.

When an enabled generated Custom controller artifact is compiled into an ASP.NET Core application, that artifact has conditional generated-artifact dependencies on all three runtime packages:

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Coject.Core.Logging.Contracts" Version="3.1.0" />
  <PackageReference Include="Coject.Core.Logging" Version="1.5.4" />
  <PackageReference Include="Coject.Core.Logging.AspNetCore" Version="1.8.4" />
</ItemGroup>

These are dependencies of the generated artifact when it is included in the consuming application, not dependencies to add to the Workshop Metadata package. Contracts supplies the generated event/action, contract-shape, and authentication metadata; Core supplies the generated custom-procedure descriptor; and AspNetCore supplies the generated controller base class. The local source baseline has these aligned runtime assemblies; the Metadata package itself declares none of them.

An Operation controller composition generated by WorkshopStandardOperationControllerTemplate instead declares the released Coject.Core.Controller 1.3.1 package as its runtime dependency.

Minimal usage

The following uses the public metadata, planning, and generation APIs to render an inline model audit contract:

using Coject.Workshop.Metadata;

var metadata = new WorkshopModelAuditMetadata
{
    ModelType = "Acme.Models.Order",
    MutableAuditable = true,
    Fields =
    [
        new WorkshopModelFieldMetadata
        {
            PropertyName = "Id",
            ScalarKind = WorkshopAuditScalarKind.Int32,
            Identity = true
        },
        new WorkshopModelFieldMetadata
        {
            PropertyName = "Description",
            ScalarKind = WorkshopAuditScalarKind.String
        }
    ]
};

var plan = WorkshopModelAuditGenerationPlanner.CreatePlan(metadata);
var generatedSource = WorkshopModelAuditArtifactGenerator.RenderInlineModelSource(plan);

generatedSource is source text to apply to the model; the package does not add it to a project or deploy it for you.

Current scope and limitations

• Provides Workshop-owned metadata models, JSON metadata storage, validation, generation plans, and deterministic controller/model audit source artifacts.
• The current model planner supports the scalar kinds defined by WorkshopAuditScalarKind; mutable auditable models require exactly one supported identity field. Read/report models can opt out with MutableAuditable = false.
• The v2 metadata schema adds explicit custom-procedure contract shape, input/data-return declarations, authentication mode, and event/action policy. Legacy v1 operation-controller documents remain readable; legacy custom actions without these declarations are rejected rather than semantically inferred.
• Custom controller output selects one of the three explicit ASP.NET custom-procedure controller base classes from the declared contract shape.
• Generated custom descriptors are always created with FromPolicy(...) from saved metadata. Workshop emits no Fleet-specific descriptor factory.
• Generated output is intended to be consumed by the calling build or generation workflow. Operation artifacts can remain provider-neutral; a generated custom-controller artifact conditionally requires the runtime package set described above.
• Runtime Controller integration, Baha API runtime integration, hosting, and production deployment are outside this package's scope.

Standard-operation controller composition

The WorkshopStandardOperationControllerTemplate renders the smallest supported standard-operation composition: a deterministic partial controller whose base is the released Coject.Core.Controller 1.3.1 package. It never copies StandardOperationController or StandardAuditedOperationController source into the generated project. The consuming project must provide the explicit namespace and DAL type inputs, and an audited controller must declare compatible mutable model metadata so the typed snapshot contract can be generated separately.

The current repository has no supported Workshop route/action/authorization controller template and no independent generated consumer fixture. Therefore the artifact intentionally does not invent HTTP attributes, endpoint names, or authorization policy. The existing WorkshopAuditArtifactGenerator remains a policy artifact generator; wiring this composition into a full controller pipeline and proving an independent consumer remain open S06-013/S06-014 work until that upstream template/fixture is supplied.

Explicit custom-procedure semantics

For a Custom controller, metadata must explicitly declare the transport contract and business meaning. In addition to the required module, resource, operation, and target metadata, custom actions declare:

• contractShape with matching input and/or dataReturn declarations;
• intent, event, and action for business classification;
• authenticationMode and, when applicable, an explicit bounded userId;
• Single or Batch execution shape, success rule, audit mode, and identity provenance;
• explicit deletionMode for Delete actions; it is rejected for every other intent;
• optional filterMappings, each with database column, request property, procedure parameter, and persisted canonical telemetry field name.

Business event/action is never inferred from the procedure name, controller name, route, HTTP verb, CLR request type, CLR response type, or result count. For example, DeleteReport, a DELETE route, or a single-item result does not by itself select DataDeletion/Delete. Declare the pair explicitly, such as DataRead/Read, DataCreation/Create, or DataModification/Execute; Workshop validates compatibility with the declared intent and execution shape. Single/Batch is item cardinality and is separate from the transport contract shape.

An illustrative explicit fragment is:

{
  "actionName": "RunReport",
  "event": "DataCreation",
  "action": "Create",
  "intent": "Create",
  "contractShape": "ReturnsDataWithInput",
  "input": { "type": "Acme.Models.ReportRequest" },
  "dataReturn": { "type": "Acme.Models.Report" },
  "authenticationMode": "AuthenticatedUser",
  "telemetryMode": "Enabled"
}

The complete controller action also supplies the required audit, success, target, and identity metadata.

telemetryMode is an explicit action-level dispatch policy. Enabled is the default. Disabled keeps the descriptor and all execution/business metadata but suppresses the custom-procedure operational event, eligible audit action, and authorization-denial telemetry. A disabled action must also declare audit: false and auditMode: LogOnly; the procedure itself still executes through the same generated adapter.

Generated controller base classes

The generated custom-controller class inherits from one base selected by the declared contractShape:

These three base classes classify transport contract shape only. They do not classify read/create/modify/delete/workflow intent, choose the event/action pair, choose authentication, or determine Single versus Batch cardinality. All actions in one generated custom controller use one consistent declared contract shape, and the explicit input/data declarations must agree with it.

Authentication modes

authenticationMode is explicit:

• Anonymous means no authorizer and no user ID are required. Omit userId; Workshop preserves it as null and does not synthesize an identity from the request, route, or name. The ASP.NET Core adapter skips its authorizer hook for an anonymous descriptor.
• AuthenticatedUser is the authenticated-caller mode. The host can provide ICustomProcedureAuthorizer<TRequest> to enforce its authentication and authorization policy. An explicit bounded userId may be carried as metadata, but generation never infers or fabricates it.

Current aligned releases

Use this version set when Workshop metadata and a generated custom-controller artifact are consumed together:

Coject.Workshop.Metadata.Mapping is optional and is not a runtime dependency of the generated controller base classes.