tom_code_specs library
CodeSpecs framework for TomSpecs Phase 4.
This is the code home for CodeSpecs — the Cs* annotation family and
the code-side DocSpecs↔CodeSpecs link annotations (@CodeSpec, @DocSpec /
DocRef, codespecs_mapping.md §9.3). It is a code framework, not a
document model: the former tom_code_specs package that modelled Phase 4
as a DocSpec was deleted (see codespecs_mapping.md §1/§1.1).
The framework carries annotations only — no base classes, and every
annotation uses the Cs* prefix (codespecs_mapping.md §1.1 pillar
(a)). A CodeSpec is an ordinary class built on an existing
tom_core-family class
(tom_core_kernel / _flutter / _server / _d4rt / tom_flutter_ui)
and marked by these Cs* annotations (CsForm, CsTable, CsEndpoint,
…) together with the identity/trace annotations CodeSpec and @DocSpec.
The framework is owned by the tom_specs quest (the former code_spec
quest is retired).
The type-level forward link (@CodeSpecKind) and the shared kind
vocabulary (CodeSpecPart) annotate the SOM model and therefore live in
tom_specs_core; they are re-exported here for convenience so CodeSpecs
authors have one import.
Classes
- CodeSpec
- The CodeSpecs identity + forward-trace annotation (CE-TR).
- CodeSpecKind
-
The general, type-level half of the DocSpecs ↔ CodeSpecs link
(
codespecs_mapping.md§9.1). - CsAction
- CE-AC — a user action (a command the user can invoke).
- CsActionRef
- A reference to a CE-AC action (client locus).
- CsAudited
-
CE-LG — an audited element: an entity or endpoint whose access is recorded
in the audit trail (
codespecs_mapping.md§4.3). - CsAuth
- CE-AU — authentication / session: credential exchange, token, session.
- CsAuthorize
-
CE-AZ — an authorization rule: a modifier applied to the CsEndpoint it
gates (
codespecs_mapping.md§5.6.3, §5.15). - CsCallRef
- A reference to a CE-SC server call (client locus).
- CsClient
- CE-CL — a client application (which clients exist: Flutter app, CLI, other server). The client-application descriptor.
- CsClientConfig
- CE-CC — client configuration: per-machine settings of a client app (API base URL, device options, per-install toggles), keyed by (client app, machine).
- CsCollaborator
-
The abstract collaborator a form-3b body calls
(
codespecs_derivation_contract.md§3.0.1). - CsColumn
-
CE-DB — a table column: a stored field of a CsTable
(
codespecs_mapping.md§5.13). - CsDeviceSetting
-
CE-DS — a device setting: a user-specific setting of a user-owned device,
keyed by (user, device) and persisted on the device (window layout,
last-opened, machine-local cache preferences). See
codespecs_mapping.md§5.16 and §11. - CsElement
-
CE-EL — a UI element by semantic type (the generic element part,
codespecs_mapping.md§5.18). - CsElementRef
- A reference to a CE-EL screen element (client locus).
- CsEndpoint
-
CE-API — a server endpoint: an operation name plus its request/response and
error contract (
codespecs_mapping.md§5.6.1). All operations are POST (codespecs_mapping.md§7). - CsEnum
-
A domain enum — a member marker, not a part marker
(
codespecs_mapping.md§4.1): annotates a plain Dartenumdeclaration authored within its owning part (a data-access entity, a configuration/settings holder, a view model, or an API contract type). It keeps the@DocSpecback-trace to the enum's SOMDMENEentry and keeps the enum discoverable as an@OneOfdiscriminator source. Placement: the shared project iff a shared contract type references the enum, else the owning part's project. - CsError
- CE-ER — a processing error (a shared error type crossing the wire).
- CsErrorCode
- A reference to a CE-ER error code (shared locus).
- CsFeatureHook
-
CE-SU — the class implementing one hook of a framework protocol feature
(
codespecs_mapping.md§5.30,codespecs_derivation_contract.md§3.4.6). - CsFeatureHookSpec
-
One hook a CsProtocolFeature asks the application to implement
(
codespecs_derivation_contract.md§3.4.6). - CsFieldRule
-
CE-VA — a single-field validation rule (
codespecs_mapping.md§5.19). - CsFileReference
-
CE-DB — a file-reference column facet (
codespecs_mapping.md§5.13). - CsForm
- CE-FM — a form: the grouping of elements into forms and subforms.
- CsFormRef
- A reference to a CE-FM form (client locus).
- CsFormRule
-
CE-VA — a cross-field validation rule (
codespecs_mapping.md§5.19). - CsGradedAccess
-
CE-AZ — the graded requirement facet: a three-slot requirement tree
(
codespecs_mapping.md§5.15). - CsIdentity
-
CE-ID — the app's identity-extension declaration holder
(
codespecs_mapping.md§5.24). - CsIdentityAttribute
-
CE-ID — one declared identity-extension attribute; a member marker on a
CsIdentity holder, the same pattern as
@CsColumn(codespecs_mapping.md§5.24). - CsJob
-
CE-JB — a background-job definition (
codespecs_mapping.md§5.29). - CsJobRef
- A reference to a CE-JB background job (server locus).
- CsLayout
-
CE-LO — a screen layout (structural arrangement of elements,
codespecs_mapping.md§5.2, §5.12). - CsMessageKey
- A reference to a CE-TX message key (shared locus).
- CsMigration
-
CE-MG — a schema-migration artifact set (
codespecs_mapping.md§5.27). - CsNotification
-
CE-NT — a notification type: an outbound communication a system event emits
(
codespecs_mapping.md§4.3). - CsNotificationChannel
-
CE-NT — a notification channel: a declared delivery route
(
codespecs_mapping.md§4.3). - CsOperationBinding
-
CE-API — a protocol binding of one of the application's own operations: a
standard HTTP shape third-party callers reach the operation through
(
codespecs_mapping.md§5.30,codespecs_derivation_contract.md§3.4.5). - CsOperationRef
- A reference to a CE-API operation (shared locus).
- CsReport
-
CE-RP — a report: a grouped projection over the domain model, delivered as
a rendered artifact (
codespecs_mapping.md§5.28). - CsReportChart
-
CE-RP — a chart declared over a CsReport's projected columns
(
codespecs_mapping.md§5.28). - CsReportColumn
-
CE-RP — one projected output column of a CsReport (
codespecs_mapping.md§5.28). - CsReportParameter
-
CE-RP — a runtime input a CsReport takes when it is run
(
codespecs_mapping.md§5.28). - CsReportRef
- A reference to a CE-RP report definition (server locus).
- CsRepository
- CE-DB — a repository: the data-access surface over one or more CsTables.
- CsResourceKeyRef
- A reference to a CE-AZ resource key (shared locus).
- CsRoleRef
- A reference to a CE-AZ role (shared locus).
- CsRoute
-
CE-NV — a route: one navigable screen, identified by a stable route id
(
codespecs_mapping.md§5.11). - CsRouteRef
- A reference to a CE-NV route (client locus).
- CsScreenFlow
-
CE-NV — the screen-flow model: how screens are reached from one another
(
codespecs_mapping.md§5.11). - CsServerCall
- CE-SC — a server call made from the client.
- CsServerConfig
- CE-CF — server configuration (per-server settings).
- CsServiceUnit
- CE-SU — a service unit (a cohesive server-side service).
- CsServiceUnitRef
- A reference to a CE-SU service unit (server locus).
- CsTable
-
CE-DB — a persistent table (a stored entity type,
codespecs_mapping.md§5.13). - CsText
- CE-TX — a text element (labels, copy, messages).
- CsTrigger
-
CE-AC — a trigger: the event that fires a CsAction (
codespecs_mapping.md§5.10, §5.20). - CsUserSetting
-
CE-UP — a user setting / profile value, keyed by the user and persisted
server-side, so it follows the user onto any device they sign into
(theme, language, notification prefs). See
codespecs_mapping.md§11. - CsValidation
- CE-VA — a client-side validation rule.
- CsViewModel
- CE-ST — a view model: client-side presentation state.
- CsWidget
-
CE-EL — the concrete
tom_flutter_uiwidget realising a CsElement's semantic type (codespecs_mapping.md§5.7.1, §5.18). - DocRef
- A single (sectionId, description) back-trace entry held by DocSpec.
- DocSpec
-
The code-side back-trace half of the DocSpecs ↔ CodeSpecs link
(
codespecs_mapping.md§9.3).
Enums
- CodeSpecPart
-
The finalized catalogue of CodeSpecs "parts" (
codespecs_mapping.md§4.1). - CsAuthRequirement
-
What a CE-AZ authorization requirement demands
(
codespecs_mapping.md§5.15). - CsClientKind
-
Which kind of client application a CE-CL descriptor declares
(
codespecs_mapping.md§4.1). - CsElementKind
-
The closed CE-EL semantic element catalogue
(
codespecs_mapping.md§5.18). - CsErrorSeverity
-
How severe a CE-ER error code is (
codespecs_derivation_contract.md§3.1.2). - CsFormEvent
-
The form-event arm of an
inFormEventtrigger (codespecs_mapping.md§5.20). - CsGesture
-
The gesture arm of a
userGesturetrigger (codespecs_mapping.md§5.20). - CsIdentityAttributePlacement
-
Where a CE-ID identity attribute rides in the token payload
(
codespecs_mapping.md§5.24). - CsJobTrigger
-
What starts a CE-JB background job (
codespecs_mapping.md§5.29). - CsLifecyclePhase
-
The phase arm of a
lifecycletrigger (codespecs_mapping.md§5.20). - CsLifecycleScope
-
How long a scoped thing lives (
codespecs_mapping.md§5.4, §5.20). - CsMigrationKind
-
The three CE-MG artifact kinds (
codespecs_mapping.md§5.27). - CsOverridableBy
-
Which narrower configuration scope may shadow a setting
(
codespecs_mapping.md§5.16, §11). - CsProtocolFeature
-
A framework protocol feature: a
tom_core_serverstandard protocol server an application enables (codespecs_mapping.md§5.30). - CsSensitivityLevel
-
How sensitive a CE-DB column's stored value is
(
codespecs_mapping.md§5.13). - CsTextCategory
-
Which catalogue half a CE-TX message key belongs to
(
codespecs_mapping.md§5.21). - CsTextRole
-
What a CE-TX message key is copy for (
codespecs_mapping.md§5.21). - CsTriggerKind
-
How a CE-AC action is invoked (
codespecs_mapping.md§5.20).
Constants
-
csFeatureHooks
→ const List<
CsFeatureHookSpec> -
Every hook of every CsProtocolFeature (
codespecs_derivation_contract.md§3.4.6). -
csFeatureReservedPaths
→ const Map<
CsProtocolFeature, List< String> > -
The path prefixes the framework serves for each CsProtocolFeature
(
codespecs_mapping.md§5.30).