@oods/component-contracts 0.11.3 → 0.13.0

package/dist/index.d.cts

@@ -312,6 +312,8 @@ interface CollectionEvent {
     at: string;
     description: string;
     kind: 'state' | 'payment';
+    /** s244-m01 (#2829): who acted, for whom and who approved, when the history entry names them (historyAttribution). */
+    attribution?: string;
 }
 /** Invalid dates cannot participate in a chronological view; ties retain source order. */
 declare function chronologicalEvents(events: readonly CollectionEvent[]): CollectionEvent[];
@@ -350,6 +352,38 @@ declare function ownershipPhrase(ownerLabel?: unknown, ownerType?: unknown, role
 /** Keep authored record keys and the Transaction fallback; UUIDs belong in technical inspection. */
 declare function formatRecordLabel(value: unknown, readableIdentifier?: boolean): string;
 
+/**
+ * s244-m01 (#2829): every recorded change can name three parties, and every place history is printed says who in one
+ * phrase built here.
+ *
+ * A history entry (Stateful's state_history, Auditable's audit_log) may carry these optional fields beside its
+ * actor_id, following Relationship's source_id/source_name pattern:
+ *   actor_name, actor_id          who acted
+ *   actor_kind                    person, agent or system (the Actor trait's kinds)
+ *   on_behalf_of_name, _id        who it acted for
+ *   approved_by_name, _id         who approved it, when someone did
+ *
+ * Only a `*_name` field names a party: `actor` and `actor_id` are ids, and an entry that names no one renders exactly as
+ * it did before, its "Actor: <id>" line included.
+ *
+ * s245-m01: a change someone approved can also point at its approval and name its level of yes:
+ *   approval_id                   the Approval record the yes is kept in: a pointer kept in the record's data, never printed
+ *   approval_level                the level of yes, printed in the words a level is shown in on every screen
+ * "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi (level: Approval)". An entry without a level prints exactly
+ * what it printed before.
+ */
+interface HistoryAttribution {
+    /**
+     * "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi"; "Ruth Adeyemi" alone for a person acting for herself;
+     * "… · approved by Ruth Adeyemi (level: Approval)" when the entry names its level of yes.
+     */
+    text: string;
+    /** True when the entry names who acted, so its actor id is not printed beside the name. */
+    namesActor: boolean;
+}
+/** The phrase for an entry's named parties and its level of yes, or undefined when it names neither. */
+declare function historyAttribution(entry: unknown): HistoryAttribution | undefined;
+
 /** Preserve generated SVG bytes while admitting only passive, local SVG markup. */
 declare function assertStaticSvg(svg: string): string;
 /**
@@ -2775,11 +2809,12 @@ interface TraitEventValues {
 type TraitEventKind = 'archive' | 'cancellation' | 'transition';
 /** Missing timestamps stay disclosed; history order and authored actor/reason are preserved. */
 declare function traitEventRows(kind: TraitEventKind, values: TraitEventValues): {
+    actor: string | undefined;
+    reason: string | undefined;
+    attribution?: string | undefined;
     code: string | undefined;
     at: string | undefined;
     time: string;
-    actor: string | undefined;
-    reason: string | undefined;
     title: string;
 }[];
 /** Catalog rows can be strings or named records; never stringify objects into [object Object]. */
@@ -3402,4 +3437,4 @@ declare function getBaselineCapability(componentId: string): {
     };
 } | undefined;
 
-export { type AuditSummaryValues, BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, type BillingAmountResult, type BillingCycleValues, type BillingPaymentValues, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, type CollectionEvent, type ComponentBehavior, type ComponentClassification, type ComponentContract, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, type EmissionEligibilityEvidence, type EmissionEligibilityEvidenceClass, type EvidenceResult, type EvidenceStatus, FOUNDATION_V1_EVIDENCE_CLASSES, type FoundationV1Evidence, type FoundationV1EvidenceClass, GOVERNED_DEFINITION, GOVERNED_SURFACES, type GeoFieldMappingValue, type GovernedComponentId, type GovernedLedgerRow, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type NumberDisplayFormat, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, STATUS_DOMAINS, STATUS_ICON_SHAPES, STATUS_ICON_SVG_ATTRS, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, type StatusDomain, type StatusIconName, type StatusIconShape, type StatusPresentation, type StatusTokenSet, type StatusTone, type SubstitutionContractReport, type SubstitutionObligation, type TraitEventKind, type TraitEventValues, UI_WORKFLOW_STATES, type UiWorkflowState, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, VIZ_SVG_PROPS, VIZ_THEME_SVG_PROPS, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizPreviewLayer, type VizPreviewTheme, type VizRenderAttribute, type VizScale, type VizSummaryId, type VizThemeSvgProp, addressCollectionSummary, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingPeriodEnd, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatDeclaredNumber, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBannerToneTokenSet, getBaselineCapability, getStatusPresentation, getToneTokenSet, initialSort, isGovernedComponent, isVizIntentFragment, listStatuses, nextSort, ownershipPhrase, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, relativeTimestampEmptyScenario, resolveStatusIcon, restartedBillingPeriod, sharedScenarios, statusIconMarkup, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizPreviewLayers, vizSummaryRows };
+export { type AuditSummaryValues, BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, type BillingAmountResult, type BillingCycleValues, type BillingPaymentValues, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, type CollectionEvent, type ComponentBehavior, type ComponentClassification, type ComponentContract, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, type EmissionEligibilityEvidence, type EmissionEligibilityEvidenceClass, type EvidenceResult, type EvidenceStatus, FOUNDATION_V1_EVIDENCE_CLASSES, type FoundationV1Evidence, type FoundationV1EvidenceClass, GOVERNED_DEFINITION, GOVERNED_SURFACES, type GeoFieldMappingValue, type GovernedComponentId, type GovernedLedgerRow, type HistoryAttribution, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type NumberDisplayFormat, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, STATUS_DOMAINS, STATUS_ICON_SHAPES, STATUS_ICON_SVG_ATTRS, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, type StatusDomain, type StatusIconName, type StatusIconShape, type StatusPresentation, type StatusTokenSet, type StatusTone, type SubstitutionContractReport, type SubstitutionObligation, type TraitEventKind, type TraitEventValues, UI_WORKFLOW_STATES, type UiWorkflowState, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, VIZ_SVG_PROPS, VIZ_THEME_SVG_PROPS, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizPreviewLayer, type VizPreviewTheme, type VizRenderAttribute, type VizScale, type VizSummaryId, type VizThemeSvgProp, addressCollectionSummary, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingPeriodEnd, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatDeclaredNumber, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBannerToneTokenSet, getBaselineCapability, getStatusPresentation, getToneTokenSet, historyAttribution, initialSort, isGovernedComponent, isVizIntentFragment, listStatuses, nextSort, ownershipPhrase, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, relativeTimestampEmptyScenario, resolveStatusIcon, restartedBillingPeriod, sharedScenarios, statusIconMarkup, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizPreviewLayers, vizSummaryRows };

package/dist/index.d.ts

@@ -312,6 +312,8 @@ interface CollectionEvent {
     at: string;
     description: string;
     kind: 'state' | 'payment';
+    /** s244-m01 (#2829): who acted, for whom and who approved, when the history entry names them (historyAttribution). */
+    attribution?: string;
 }
 /** Invalid dates cannot participate in a chronological view; ties retain source order. */
 declare function chronologicalEvents(events: readonly CollectionEvent[]): CollectionEvent[];
@@ -350,6 +352,38 @@ declare function ownershipPhrase(ownerLabel?: unknown, ownerType?: unknown, role
 /** Keep authored record keys and the Transaction fallback; UUIDs belong in technical inspection. */
 declare function formatRecordLabel(value: unknown, readableIdentifier?: boolean): string;
 
+/**
+ * s244-m01 (#2829): every recorded change can name three parties, and every place history is printed says who in one
+ * phrase built here.
+ *
+ * A history entry (Stateful's state_history, Auditable's audit_log) may carry these optional fields beside its
+ * actor_id, following Relationship's source_id/source_name pattern:
+ *   actor_name, actor_id          who acted
+ *   actor_kind                    person, agent or system (the Actor trait's kinds)
+ *   on_behalf_of_name, _id        who it acted for
+ *   approved_by_name, _id         who approved it, when someone did
+ *
+ * Only a `*_name` field names a party: `actor` and `actor_id` are ids, and an entry that names no one renders exactly as
+ * it did before, its "Actor: <id>" line included.
+ *
+ * s245-m01: a change someone approved can also point at its approval and name its level of yes:
+ *   approval_id                   the Approval record the yes is kept in: a pointer kept in the record's data, never printed
+ *   approval_level                the level of yes, printed in the words a level is shown in on every screen
+ * "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi (level: Approval)". An entry without a level prints exactly
+ * what it printed before.
+ */
+interface HistoryAttribution {
+    /**
+     * "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi"; "Ruth Adeyemi" alone for a person acting for herself;
+     * "… · approved by Ruth Adeyemi (level: Approval)" when the entry names its level of yes.
+     */
+    text: string;
+    /** True when the entry names who acted, so its actor id is not printed beside the name. */
+    namesActor: boolean;
+}
+/** The phrase for an entry's named parties and its level of yes, or undefined when it names neither. */
+declare function historyAttribution(entry: unknown): HistoryAttribution | undefined;
+
 /** Preserve generated SVG bytes while admitting only passive, local SVG markup. */
 declare function assertStaticSvg(svg: string): string;
 /**
@@ -2775,11 +2809,12 @@ interface TraitEventValues {
 type TraitEventKind = 'archive' | 'cancellation' | 'transition';
 /** Missing timestamps stay disclosed; history order and authored actor/reason are preserved. */
 declare function traitEventRows(kind: TraitEventKind, values: TraitEventValues): {
+    actor: string | undefined;
+    reason: string | undefined;
+    attribution?: string | undefined;
     code: string | undefined;
     at: string | undefined;
     time: string;
-    actor: string | undefined;
-    reason: string | undefined;
     title: string;
 }[];
 /** Catalog rows can be strings or named records; never stringify objects into [object Object]. */
@@ -3402,4 +3437,4 @@ declare function getBaselineCapability(componentId: string): {
     };
 } | undefined;
 
-export { type AuditSummaryValues, BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, type BillingAmountResult, type BillingCycleValues, type BillingPaymentValues, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, type CollectionEvent, type ComponentBehavior, type ComponentClassification, type ComponentContract, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, type EmissionEligibilityEvidence, type EmissionEligibilityEvidenceClass, type EvidenceResult, type EvidenceStatus, FOUNDATION_V1_EVIDENCE_CLASSES, type FoundationV1Evidence, type FoundationV1EvidenceClass, GOVERNED_DEFINITION, GOVERNED_SURFACES, type GeoFieldMappingValue, type GovernedComponentId, type GovernedLedgerRow, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type NumberDisplayFormat, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, STATUS_DOMAINS, STATUS_ICON_SHAPES, STATUS_ICON_SVG_ATTRS, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, type StatusDomain, type StatusIconName, type StatusIconShape, type StatusPresentation, type StatusTokenSet, type StatusTone, type SubstitutionContractReport, type SubstitutionObligation, type TraitEventKind, type TraitEventValues, UI_WORKFLOW_STATES, type UiWorkflowState, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, VIZ_SVG_PROPS, VIZ_THEME_SVG_PROPS, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizPreviewLayer, type VizPreviewTheme, type VizRenderAttribute, type VizScale, type VizSummaryId, type VizThemeSvgProp, addressCollectionSummary, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingPeriodEnd, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatDeclaredNumber, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBannerToneTokenSet, getBaselineCapability, getStatusPresentation, getToneTokenSet, initialSort, isGovernedComponent, isVizIntentFragment, listStatuses, nextSort, ownershipPhrase, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, relativeTimestampEmptyScenario, resolveStatusIcon, restartedBillingPeriod, sharedScenarios, statusIconMarkup, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizPreviewLayers, vizSummaryRows };
+export { type AuditSummaryValues, BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, type BillingAmountResult, type BillingCycleValues, type BillingPaymentValues, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, type CollectionEvent, type ComponentBehavior, type ComponentClassification, type ComponentContract, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, type EmissionEligibilityEvidence, type EmissionEligibilityEvidenceClass, type EvidenceResult, type EvidenceStatus, FOUNDATION_V1_EVIDENCE_CLASSES, type FoundationV1Evidence, type FoundationV1EvidenceClass, GOVERNED_DEFINITION, GOVERNED_SURFACES, type GeoFieldMappingValue, type GovernedComponentId, type GovernedLedgerRow, type HistoryAttribution, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type NumberDisplayFormat, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, STATUS_DOMAINS, STATUS_ICON_SHAPES, STATUS_ICON_SVG_ATTRS, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, type StatusDomain, type StatusIconName, type StatusIconShape, type StatusPresentation, type StatusTokenSet, type StatusTone, type SubstitutionContractReport, type SubstitutionObligation, type TraitEventKind, type TraitEventValues, UI_WORKFLOW_STATES, type UiWorkflowState, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, VIZ_SVG_PROPS, VIZ_THEME_SVG_PROPS, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizPreviewLayer, type VizPreviewTheme, type VizRenderAttribute, type VizScale, type VizSummaryId, type VizThemeSvgProp, addressCollectionSummary, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingPeriodEnd, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatDeclaredNumber, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBannerToneTokenSet, getBaselineCapability, getStatusPresentation, getToneTokenSet, historyAttribution, initialSort, isGovernedComponent, isVizIntentFragment, listStatuses, nextSort, ownershipPhrase, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, relativeTimestampEmptyScenario, resolveStatusIcon, restartedBillingPeriod, sharedScenarios, statusIconMarkup, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizPreviewLayers, vizSummaryRows };