@oods/component-contracts 0.3.1 → 0.3.3

package/README.md

@@ -21,7 +21,7 @@ console.log(componentContracts.Button.accessibility);
 
 Use the contract when writing a component adapter. The `componentCapabilityBaseline` export and `@oods/component-contracts/registry/capabilities` contain the retained capability ledger. Its evidence is scoped to the recorded component scenarios; a declared obligation is not evidence that an arbitrary implementation meets it.
 
-Forge's mapped-component reports distinguish met, unmet and not-checked obligations. Read their reasons and source identities before using a report as evidence. The package does not certify an application, a third-party library or every possible component state.
+OODS Foundry's mapped-component reports distinguish met, unmet and not-checked obligations. Read their reasons and source identities before using a report as evidence. The package does not certify an application, a third-party library or every possible component state.
 
 ## Limits
 
@@ -29,4 +29,4 @@ Use matching versions of the OODS packages. These packages are separate from the
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Generated output belongs to its user; installed package dependencies retain their own licenses.
+Apache License 2.0. See [LICENSE](https://cdn.jsdelivr.net/npm/@oods/component-contracts@0.3.3/LICENSE) and [NOTICE](https://cdn.jsdelivr.net/npm/@oods/component-contracts@0.3.3/NOTICE). Generated output belongs to its user; installed package dependencies retain their own licenses.

package/dist/index.cjs

@@ -15373,7 +15373,7 @@ var authoredContracts = {
     states: ["subtle", "solid"],
     tokenRoles: ["badge.background", "badge.border", "badge.text"],
     accessibility: ["false remains visible", "archive is the badge variant"],
-    compatibility: "Mirrors renderArchivePill over renderBadgePrimitive: label/text/status/state/isArchived/value label precedence, status/state/isArchived/value status precedence, Archive fallback and archive variant. Boolean false and true remain literal scalar labels/status metadata; absent flags remain absent and authored labels or children win. field binds isArchived. archivedAtField is consumed unbound because the HTML pill has no date term. Noninteractive; no archive or restore action."
+    compatibility: "Mirrors renderArchivePill over renderBadgePrimitive: label/text/status/state/isArchived/value label precedence, status/state/isArchived/value status precedence, Archive fallback and archive variant. Boolean flags read Not archived / Archived while preserving their recorded status; absent flags remain absent and authored labels or children win. field binds isArchived. archivedAtField is consumed unbound because the HTML pill has no date term. Noninteractive; no archive or restore action."
   },
   ArchiveSummary: {
     id: "ArchiveSummary",
@@ -15412,22 +15412,17 @@ var authoredContracts = {
   AuditTimeline: {
     id: "AuditTimeline",
     version: COMPONENT_CONTRACT_VERSION,
-    props: [
-      "title",
-      "events",
-      "history",
-      "entries",
-      "auditLog",
+    props: ["title", "events", "history", "entries", "auditLog", "maxVisible", "showFromState", "showActorId", "showReason"],
+    directives: [
+      "field",
+      "historyField",
+      "statesParameter",
       "auditLogField",
       "createdField",
       "updatedField",
       "eventField",
       "eventTimestampField",
-      "eventOptionsParameter",
-      "maxVisible",
-      "showFromState",
-      "showActorId",
-      "showReason"
+      "eventOptionsParameter"
     ],
     slots: ["default"],
     events: [],
@@ -15539,18 +15534,8 @@ var authoredContracts = {
   CancellationSummary: {
     id: "CancellationSummary",
     version: COMPONENT_CONTRACT_VERSION,
-    props: [
-      "title",
-      "label",
-      "cancelAtPeriodEnd",
-      "requestedAt",
-      "reason",
-      "code",
-      "cancelAtPeriodEndField",
-      "requestedAtField",
-      "reasonField",
-      "codeField"
-    ],
+    props: ["title", "label", "cancelAtPeriodEnd", "requestedAt", "reason", "code"],
+    directives: ["field", "cancelAtPeriodEndField", "requestedAtField", "reasonField", "codeField"],
     slots: ["default"],
     events: [],
     states: ["scheduled", "not-scheduled"],
@@ -15841,7 +15826,9 @@ var authoredContracts = {
       "pageSizeOptions",
       "showPageSizeSelector",
       "showGotoPage",
-      "showItemRange",
+      "showItemRange"
+    ],
+    directives: [
       "pageField",
       "pageSizeField",
       "totalItemsField",
@@ -15937,12 +15924,9 @@ var authoredContracts = {
       "label",
       "value",
       "emphasis",
-      "amountField",
-      "currencyField",
-      "intervalField",
-      "minorUnitsParameter",
       "minorUnits"
     ],
+    directives: ["field", "amountField", "currencyField", "intervalField", "minorUnitsParameter"],
     slots: ["default"],
     events: [],
     states: ["priced", "missing-price"],
@@ -15959,7 +15943,7 @@ var authoredContracts = {
     states: ["populated", "empty"],
     tokenRoles: ["meta.text", "meta.label"],
     accessibility: ["model and interval have literal inline labels", "price metadata is noninteractive"],
-    compatibility: "Mirrors renderPriceCardMeta over renderMetaInline: title/label/heading/name (default Price), Model model/pricingModel and Interval interval/billingInterval inline terms. Children replace the entire body including its title. modelField and intervalField lower to their runtime keys. amountField, currencyField and minorUnitsParameter are consumed unbound because this HTML metadata renderer has no amount or currency term. Noninteractive."
+    compatibility: "Mirrors renderPriceCardMeta over renderMetaInline: title/label/heading/name (default Price), Model model/pricingModel and Interval interval/billingInterval inline terms, their codes read as PriceSummary reads them (formatPriceCode: one_time reads One Time). Children replace the entire body including its title. modelField and intervalField lower to their runtime keys. amountField, currencyField and minorUnitsParameter are consumed unbound because this HTML metadata renderer has no amount or currency term. Noninteractive."
   },
   PriceSummary: {
     id: "PriceSummary",
@@ -15986,10 +15970,9 @@ var authoredContracts = {
       "text",
       "timezone",
       "now",
-      "fallbackField",
-      "timezoneParameter",
       "hideWhenEmpty"
     ],
+    directives: ["field", "fallbackField", "timezoneParameter"],
     slots: ["default"],
     events: [],
     states: ["relative", "absolute", "empty"],
@@ -16032,12 +16015,9 @@ var authoredContracts = {
       "debounceMs",
       "debounce",
       "minQueryLength",
-      "disabled",
-      "placeholderParameter",
-      "debounceParameter",
-      "minQueryLengthParameter",
-      "clearableParameter"
+      "disabled"
     ],
+    directives: ["field", "placeholderParameter", "debounceParameter", "minQueryLengthParameter", "clearableParameter"],
     slots: [],
     events: ["valueChange", "update", "search", "clear"],
     states: ["empty", "valued", "disabled"],
@@ -16061,7 +16041,8 @@ var authoredContracts = {
   Stack: {
     id: "Stack",
     version: COMPONENT_CONTRACT_VERSION_1_1,
-    props: ["direction", "gap", "align", "justify", "wrap", "patternComponent", "fields"],
+    props: ["direction", "gap", "align", "justify", "wrap"],
+    directives: ["patternComponent", "fields"],
     slots: ["default"],
     events: [],
     states: ["row", "column", "wrapped"],
@@ -16083,11 +16064,10 @@ var authoredContracts = {
       "emphasis",
       "showIcon",
       "variant",
-      "statusField",
-      "domainField",
       "readOnly",
       "compact"
     ],
+    directives: ["field", "statusField", "domainField"],
     slots: ["default"],
     events: [],
     states: ["subtle", "solid"],
@@ -16118,12 +16098,21 @@ var authoredContracts = {
       "stateHistory",
       "status",
       "allowedTransitions",
-      "historyField",
-      "statesParameter",
       "showActorId",
       "showReason",
       "maxVisible"
     ],
+    directives: [
+      "field",
+      "historyField",
+      "statesParameter",
+      "auditLogField",
+      "createdField",
+      "updatedField",
+      "eventField",
+      "eventTimestampField",
+      "eventOptionsParameter"
+    ],
     slots: ["default"],
     events: [],
     states: ["populated", "empty"],
@@ -16348,7 +16337,7 @@ var viz_preview_samples_v1_default = {
       input: {
         name: "Example connected relationships",
         description: "Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data."},
-      svg: '<svg width="360" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" baseProfile="full" viewBox="0 0 360 200">\n<rect width="360" height="200" x="0" y="0" fill="#F9FAFC"></rect>\n<path d="M208.4 34Q249.7 88.3 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M221.2 150.3Q155.5 166.3 110.4 115.8" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M110.4 115.8Q176.1 99.8 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,110.3635,115.779)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,221.2255,150.2583)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,208.3976,33.9582)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(120.3635 115.779)" fill="#1A1D23">example-document</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(231.2255 150.2583)" fill="#1A1D23">example-project</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(218.3976 33.9582)" fill="#1A1D23">example-team</text>\n<path d="M-108.1 -5l216.2 0l0 24l-216.2 0Z" transform="translate(180 13)" fill="rgb(0,0,0)" fill-opacity="0" stroke="#3c3c41" stroke-width="0" class="oods-zr-2"></path>\n<text dominant-baseline="central" text-anchor="middle" style="font-size:14px;font-family:sans-serif;font-weight:600;" xml:space="preserve" y="7" transform="translate(180 13)" fill="#1A1D23">Example connected relationships</text>\n<style ><![CDATA[\n.oods-zr-0:hover {\ncursor:pointer;\nstroke-width:4;\n}\n.oods-zr-1:hover {\ncursor:pointer;\nfill:rgba(96,9,26,1);\n}\n.oods-zr-2:hover {\npointer-events:none;\n}\n\n]]>\n\n</style>\n</svg>'}
+      svg: '<svg width="360" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" baseProfile="full" viewBox="0 0 360 200" role="img" aria-label="Example connected relationships" aria-description="Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data."><title>Example connected relationships</title><desc>Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data.</desc>\n<rect width="360" height="200" x="0" y="0" fill="#F9FAFC"></rect>\n<path d="M208.4 34Q249.7 88.3 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M221.2 150.3Q155.5 166.3 110.4 115.8" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M110.4 115.8Q176.1 99.8 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,110.3635,115.779)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,221.2255,150.2583)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,208.3976,33.9582)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(120.3635 115.779)" fill="#1A1D23">example-document</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(231.2255 150.2583)" fill="#1A1D23">example-project</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(218.3976 33.9582)" fill="#1A1D23">example-team</text>\n<path d="M-108.1 -5l216.2 0l0 24l-216.2 0Z" transform="translate(180 13)" fill="rgb(0,0,0)" fill-opacity="0" stroke="#3c3c41" stroke-width="0" class="oods-zr-2"></path>\n<text dominant-baseline="central" text-anchor="middle" style="font-size:14px;font-family:sans-serif;font-weight:600;" xml:space="preserve" y="7" transform="translate(180 13)" fill="#1A1D23">Example connected relationships</text>\n<style ><![CDATA[\n.oods-zr-0:hover {\ncursor:pointer;\nstroke-width:4;\n}\n.oods-zr-1:hover {\ncursor:pointer;\nfill:rgba(96,9,26,1);\n}\n.oods-zr-2:hover {\npointer-events:none;\n}\n\n]]>\n\n</style>\n</svg>'}
   }
 };
 
@@ -16396,7 +16385,7 @@ var authoredScenarios = [
   { id: "address-editor-fields-and-change", oodsComponentId: "AddressEditor", props: { title: "Shipping address", street: "1 Main St", city: "Springfield", region: "IL", postalCode: "62701" }, slots: {}, initialState: { street: "1 Main St" }, renderExpectation: { name: "change", trigger: "type into the City input", expected: "change emitted with the current street/city/region/postalCode record" }, assertions: ["title is a real h2 heading", "four labelled inputs are prefilled", "change carries the whole address record", "submitting is a no-op"] },
   { id: "address-summary-badge-role", oodsComponentId: "AddressSummaryBadge", props: { label: "Billing address", role: "billing" }, slots: {}, initialState: { status: "billing" }, renderExpectation: { name: "render", trigger: "mount", expected: "visible Billing address label with data-badge-status billing and the address variant" }, assertions: ["label is visible text", "data-badge-status is billing", "data-badge-variant is address", "badge is noninteractive"] },
   { id: "address-validation-timeline-events", oodsComponentId: "AddressValidationTimeline", props: { title: "Address checks", validations: [{ label: "Postal code verified", timestamp: "2026-09-05T12:00:00Z", detail: "Matched carrier database" }, "Geocoded"] }, slots: {}, initialState: { events: 2 }, renderExpectation: { name: "render", trigger: "mount", expected: "a log region titled Address checks with two ordered events, the first timestamped and detailed" }, assertions: ["region has role log and an h2 title", "events are ordered list items", "the timestamp is a time element", "scalar entries render as text"] },
-  { id: "archive-pill-false", oodsComponentId: "ArchivePill", props: { "isArchived": false }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "false remains visible; archive is the badge variant" }, assertions: ["false remains visible", "archive is the badge variant"] },
+  { id: "archive-pill-false", oodsComponentId: "ArchivePill", props: { "isArchived": false }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "Not archived remains visible; machine status remains false; archive is the badge variant" }, assertions: ["Not archived remains visible; machine status remains false", "archive is the badge variant"] },
   { id: "archive-summary-false-and-reason", oodsComponentId: "ArchiveSummary", props: { "isArchived": false, "archivedAt": "2026-09-05T12:00:00Z", "reason": "Retention policy" }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "No remains visible in its named term; archive date and reason remain associated terms" }, assertions: ["No remains visible in its named term", "archive date and reason remain associated terms"] },
   { id: "archived-row-presentation", oodsComponentId: "ArchivedRowOverlay", props: { "isArchived": true, "showBadge": true, "separateTab": true, "tabLabel": "Archived", "label": "Team subscription" }, slots: {}, initialState: {}, renderExpectation: { name: "render", trigger: "mount", expected: "Archived row stays accessible and its badge and tab label agree" }, assertions: ["Archived row stays accessible and its badge and tab label agree"] },
   { id: "audit-event-type-and-timestamp", oodsComponentId: "AuditEvent", props: { event: "user.updated", timestamp: "2026-09-05T12:00:00Z", detail: "Display name changed" }, slots: {}, initialState: { timestamped: true }, renderExpectation: { name: "render", trigger: "mount", expected: "one audit article with a machine-readable time, the event label and the detail" }, assertions: ["article carries data-event-type audit", "time element has a datetime", "label and detail are visible text"] },
@@ -16608,6 +16597,28 @@ function billingCycle(values) {
   const announcement = `${percent === void 0 ? "Progress unavailable" : `${percent}% complete`} \xB7 ${remainingDays === void 0 ? "Remaining days unavailable" : `${remainingDays} ${remainingDays === 1 ? "day" : "days"} remaining`}`;
   return { percent, remainingDays, announcement, ended };
 }
+var PERIOD_MONTHS = { monthly: 1, quarterly: 3, yearly: 12, annual: 12 };
+function billingPeriodEnd(start, interval) {
+  const date = new Date(start);
+  if (!Number.isFinite(date.getTime())) return void 0;
+  if (interval === "weekly") return new Date(date.getTime() + 7 * 864e5).toISOString();
+  const months = interval ? PERIOD_MONTHS[interval] : void 0;
+  if (!months) return void 0;
+  const end = new Date(date);
+  end.setUTCDate(1);
+  end.setUTCMonth(end.getUTCMonth() + months);
+  end.setUTCDate(Math.min(date.getUTCDate(), new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth() + 1, 0)).getUTCDate()));
+  return end.toISOString();
+}
+function restartedBillingPeriod(at, interval) {
+  return {
+    current_period_start: at,
+    current_period_end: billingPeriodEnd(at, interval),
+    current_period_progress: void 0,
+    next_payment_due_at: at,
+    payment_status: "pending"
+  };
+}
 var NO_NEXT_PAYMENT = "No payment scheduled";
 var NO_LAST_PAYMENT = "No previous payment";
 function billingDate(value) {
@@ -16667,9 +16678,13 @@ function recordCollectionEvents(record2, options = {}) {
     if (typeof at !== "string" || typeof state !== "string") return [];
     return [{ id: "state-" + index, title: String(entry.title ?? state.split(/[_-]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ")), at, description: String(entry.reason ?? ""), kind: "state" }];
   }) : [];
+  const recorded = Array.isArray(record2.payment_history) ? record2.payment_history : [];
   for (const source2 of options.payments ?? []) {
     const at = record2[source2.field];
-    if (typeof at === "string") events.push({ id: "payment-" + source2.field, title: source2.title, at, description: billingSummary(Number(record2.amount), String(record2.currency), options.minorUnits ?? 100, String(record2.billing_interval)), kind: "payment" });
+    if (typeof at !== "string") continue;
+    const paid = recorded.find((row) => row && typeof row === "object" && Date.parse(row.at) === Date.parse(at) && typeof row.amount === "number");
+    const description = paid ? formatBillingAmount(paid.amount, String(paid.currency ?? record2.currency), options.minorUnits ?? 100) : billingSummary(Number(record2.amount), String(record2.currency), options.minorUnits ?? 100, String(record2.billing_interval));
+    events.push({ id: "payment-" + source2.field, title: source2.title, at, description, kind: "payment" });
   }
   for (const source2 of [{ field: "created_at", title: "Created" }, { field: "last_event_at", title: String(record2.last_event ?? "Updated").replaceAll("_", " ") }, { field: "issued_at", title: "Issued" }, { field: "period_start", title: "Period started" }, { field: "ownership_transferred_at", title: "Ownership transferred" }]) {
     const at = record2[source2.field];
@@ -17031,6 +17046,7 @@ exports.billingDate = billingDate;
 exports.billingIntervalMessage = billingIntervalMessage;
 exports.billingPaymentRows = billingPaymentRows;
 exports.billingPaymentSummary = billingPaymentSummary;
+exports.billingPeriodEnd = billingPeriodEnd;
 exports.billingSummary = billingSummary;
 exports.chronologicalEvents = chronologicalEvents;
 exports.componentBehaviors = componentBehaviors;
@@ -17063,6 +17079,7 @@ exports.portedComponentContracts = portedComponentContracts;
 exports.portedScenarios = portedScenarios;
 exports.recipeItemLabels = recipeItemLabels;
 exports.recordCollectionEvents = recordCollectionEvents;
+exports.restartedBillingPeriod = restartedBillingPeriod;
 exports.sharedScenarios = sharedScenarios;
 exports.substitutionContractReport = substitutionContractReport;
 exports.summarizeSubstitutionReport = summarizeSubstitutionReport;

package/dist/index.d.cts

@@ -20,6 +20,12 @@ type ComponentContract = {
     id: GovernedComponentId;
     version: '1.0.0' | '1.1.0';
     props: readonly string[];
+    /**
+     * s221-m02 (#2482 ruling 5): saved-schema composition directives the React and Vue components accept, which code
+     * generation consumes (a field binding, a pattern's parts) and the component reads no value from; listed apart from
+     * the props a consumer passes.
+     */
+    directives?: readonly string[];
     /** Public props needed to name or identify a field; substitution must preserve them. */
     requiredProps?: readonly string[];
     slots: readonly string[];
@@ -177,6 +183,25 @@ declare function billingCycle(values: BillingCycleValues): {
     announcement: string;
     ended: boolean;
 };
+/**
+ * The end of a billing period that starts at `start` and lasts one `interval` (UTC). A month keeps the start's day, or
+ * the month's last day when it is shorter. An interval with no fixed length has no computable end: undefined.
+ */
+declare function billingPeriodEnd(start: string, interval: string | undefined): string | undefined;
+/**
+ * s220-m01 (#2461): Billable's billing-anchor reset (traits/financial/Billable.trait.yaml). When the terms an active
+ * record is billed at change (price, currency or interval), a new billing period starts at the change. Billable charges
+ * at a period's start (prepaid), so the new period's payment is due at once, and nothing has collected it: pending.
+ * Progress is left to the clock the period is measured by. Recorded payments are history and keep their own amounts.
+ * Before it, an edit to "€19.99 · yearly" kept the monthly period (77% complete, 7 days remaining, next payment in a month).
+ */
+declare function restartedBillingPeriod(at: string, interval: string | undefined): {
+    current_period_start: string;
+    current_period_end: string | undefined;
+    current_period_progress: undefined;
+    next_payment_due_at: string;
+    payment_status: "pending";
+};
 interface BillingPaymentValues {
     lastPayment?: string;
     nextPayment?: string;
@@ -3021,4 +3046,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 ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, 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, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizScale, type VizSummaryId, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, 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, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, 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, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizScale, type VizSummaryId, 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, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, restartedBillingPeriod, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizSummaryRows };

package/dist/index.d.ts

@@ -20,6 +20,12 @@ type ComponentContract = {
     id: GovernedComponentId;
     version: '1.0.0' | '1.1.0';
     props: readonly string[];
+    /**
+     * s221-m02 (#2482 ruling 5): saved-schema composition directives the React and Vue components accept, which code
+     * generation consumes (a field binding, a pattern's parts) and the component reads no value from; listed apart from
+     * the props a consumer passes.
+     */
+    directives?: readonly string[];
     /** Public props needed to name or identify a field; substitution must preserve them. */
     requiredProps?: readonly string[];
     slots: readonly string[];
@@ -177,6 +183,25 @@ declare function billingCycle(values: BillingCycleValues): {
     announcement: string;
     ended: boolean;
 };
+/**
+ * The end of a billing period that starts at `start` and lasts one `interval` (UTC). A month keeps the start's day, or
+ * the month's last day when it is shorter. An interval with no fixed length has no computable end: undefined.
+ */
+declare function billingPeriodEnd(start: string, interval: string | undefined): string | undefined;
+/**
+ * s220-m01 (#2461): Billable's billing-anchor reset (traits/financial/Billable.trait.yaml). When the terms an active
+ * record is billed at change (price, currency or interval), a new billing period starts at the change. Billable charges
+ * at a period's start (prepaid), so the new period's payment is due at once, and nothing has collected it: pending.
+ * Progress is left to the clock the period is measured by. Recorded payments are history and keep their own amounts.
+ * Before it, an edit to "€19.99 · yearly" kept the monthly period (77% complete, 7 days remaining, next payment in a month).
+ */
+declare function restartedBillingPeriod(at: string, interval: string | undefined): {
+    current_period_start: string;
+    current_period_end: string | undefined;
+    current_period_progress: undefined;
+    next_payment_due_at: string;
+    payment_status: "pending";
+};
 interface BillingPaymentValues {
     lastPayment?: string;
     nextPayment?: string;
@@ -3021,4 +3046,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 ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, 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, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizScale, type VizSummaryId, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, 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, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, type NucleusComponentId, type ObligationStatus, PORTED_COMPONENT_IDS, type PortedComponentId, RESULT_STATES, RESULT_STATE_TONE, type ResultState, SEVERITY_TONES, type ScenarioTrigger, type SharedScenario, type SortIndicatorValues, type SortState, 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, type VizChannel, type VizChartType, type VizColorBinding, type VizControlField, type VizControlId, type VizFieldBinding, type VizIntentFragment, type VizScale, type VizSummaryId, 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, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, restartedBillingPeriod, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizSummaryRows };

package/dist/index.js

@@ -15371,7 +15371,7 @@ var authoredContracts = {
     states: ["subtle", "solid"],
     tokenRoles: ["badge.background", "badge.border", "badge.text"],
     accessibility: ["false remains visible", "archive is the badge variant"],
-    compatibility: "Mirrors renderArchivePill over renderBadgePrimitive: label/text/status/state/isArchived/value label precedence, status/state/isArchived/value status precedence, Archive fallback and archive variant. Boolean false and true remain literal scalar labels/status metadata; absent flags remain absent and authored labels or children win. field binds isArchived. archivedAtField is consumed unbound because the HTML pill has no date term. Noninteractive; no archive or restore action."
+    compatibility: "Mirrors renderArchivePill over renderBadgePrimitive: label/text/status/state/isArchived/value label precedence, status/state/isArchived/value status precedence, Archive fallback and archive variant. Boolean flags read Not archived / Archived while preserving their recorded status; absent flags remain absent and authored labels or children win. field binds isArchived. archivedAtField is consumed unbound because the HTML pill has no date term. Noninteractive; no archive or restore action."
   },
   ArchiveSummary: {
     id: "ArchiveSummary",
@@ -15410,22 +15410,17 @@ var authoredContracts = {
   AuditTimeline: {
     id: "AuditTimeline",
     version: COMPONENT_CONTRACT_VERSION,
-    props: [
-      "title",
-      "events",
-      "history",
-      "entries",
-      "auditLog",
+    props: ["title", "events", "history", "entries", "auditLog", "maxVisible", "showFromState", "showActorId", "showReason"],
+    directives: [
+      "field",
+      "historyField",
+      "statesParameter",
       "auditLogField",
       "createdField",
       "updatedField",
       "eventField",
       "eventTimestampField",
-      "eventOptionsParameter",
-      "maxVisible",
-      "showFromState",
-      "showActorId",
-      "showReason"
+      "eventOptionsParameter"
     ],
     slots: ["default"],
     events: [],
@@ -15537,18 +15532,8 @@ var authoredContracts = {
   CancellationSummary: {
     id: "CancellationSummary",
     version: COMPONENT_CONTRACT_VERSION,
-    props: [
-      "title",
-      "label",
-      "cancelAtPeriodEnd",
-      "requestedAt",
-      "reason",
-      "code",
-      "cancelAtPeriodEndField",
-      "requestedAtField",
-      "reasonField",
-      "codeField"
-    ],
+    props: ["title", "label", "cancelAtPeriodEnd", "requestedAt", "reason", "code"],
+    directives: ["field", "cancelAtPeriodEndField", "requestedAtField", "reasonField", "codeField"],
     slots: ["default"],
     events: [],
     states: ["scheduled", "not-scheduled"],
@@ -15839,7 +15824,9 @@ var authoredContracts = {
       "pageSizeOptions",
       "showPageSizeSelector",
       "showGotoPage",
-      "showItemRange",
+      "showItemRange"
+    ],
+    directives: [
       "pageField",
       "pageSizeField",
       "totalItemsField",
@@ -15935,12 +15922,9 @@ var authoredContracts = {
       "label",
       "value",
       "emphasis",
-      "amountField",
-      "currencyField",
-      "intervalField",
-      "minorUnitsParameter",
       "minorUnits"
     ],
+    directives: ["field", "amountField", "currencyField", "intervalField", "minorUnitsParameter"],
     slots: ["default"],
     events: [],
     states: ["priced", "missing-price"],
@@ -15957,7 +15941,7 @@ var authoredContracts = {
     states: ["populated", "empty"],
     tokenRoles: ["meta.text", "meta.label"],
     accessibility: ["model and interval have literal inline labels", "price metadata is noninteractive"],
-    compatibility: "Mirrors renderPriceCardMeta over renderMetaInline: title/label/heading/name (default Price), Model model/pricingModel and Interval interval/billingInterval inline terms. Children replace the entire body including its title. modelField and intervalField lower to their runtime keys. amountField, currencyField and minorUnitsParameter are consumed unbound because this HTML metadata renderer has no amount or currency term. Noninteractive."
+    compatibility: "Mirrors renderPriceCardMeta over renderMetaInline: title/label/heading/name (default Price), Model model/pricingModel and Interval interval/billingInterval inline terms, their codes read as PriceSummary reads them (formatPriceCode: one_time reads One Time). Children replace the entire body including its title. modelField and intervalField lower to their runtime keys. amountField, currencyField and minorUnitsParameter are consumed unbound because this HTML metadata renderer has no amount or currency term. Noninteractive."
   },
   PriceSummary: {
     id: "PriceSummary",
@@ -15984,10 +15968,9 @@ var authoredContracts = {
       "text",
       "timezone",
       "now",
-      "fallbackField",
-      "timezoneParameter",
       "hideWhenEmpty"
     ],
+    directives: ["field", "fallbackField", "timezoneParameter"],
     slots: ["default"],
     events: [],
     states: ["relative", "absolute", "empty"],
@@ -16030,12 +16013,9 @@ var authoredContracts = {
       "debounceMs",
       "debounce",
       "minQueryLength",
-      "disabled",
-      "placeholderParameter",
-      "debounceParameter",
-      "minQueryLengthParameter",
-      "clearableParameter"
+      "disabled"
     ],
+    directives: ["field", "placeholderParameter", "debounceParameter", "minQueryLengthParameter", "clearableParameter"],
     slots: [],
     events: ["valueChange", "update", "search", "clear"],
     states: ["empty", "valued", "disabled"],
@@ -16059,7 +16039,8 @@ var authoredContracts = {
   Stack: {
     id: "Stack",
     version: COMPONENT_CONTRACT_VERSION_1_1,
-    props: ["direction", "gap", "align", "justify", "wrap", "patternComponent", "fields"],
+    props: ["direction", "gap", "align", "justify", "wrap"],
+    directives: ["patternComponent", "fields"],
     slots: ["default"],
     events: [],
     states: ["row", "column", "wrapped"],
@@ -16081,11 +16062,10 @@ var authoredContracts = {
       "emphasis",
       "showIcon",
       "variant",
-      "statusField",
-      "domainField",
       "readOnly",
       "compact"
     ],
+    directives: ["field", "statusField", "domainField"],
     slots: ["default"],
     events: [],
     states: ["subtle", "solid"],
@@ -16116,12 +16096,21 @@ var authoredContracts = {
       "stateHistory",
       "status",
       "allowedTransitions",
-      "historyField",
-      "statesParameter",
       "showActorId",
       "showReason",
       "maxVisible"
     ],
+    directives: [
+      "field",
+      "historyField",
+      "statesParameter",
+      "auditLogField",
+      "createdField",
+      "updatedField",
+      "eventField",
+      "eventTimestampField",
+      "eventOptionsParameter"
+    ],
     slots: ["default"],
     events: [],
     states: ["populated", "empty"],
@@ -16346,7 +16335,7 @@ var viz_preview_samples_v1_default = {
       input: {
         name: "Example connected relationships",
         description: "Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data."},
-      svg: '<svg width="360" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" baseProfile="full" viewBox="0 0 360 200">\n<rect width="360" height="200" x="0" y="0" fill="#F9FAFC"></rect>\n<path d="M208.4 34Q249.7 88.3 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M221.2 150.3Q155.5 166.3 110.4 115.8" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M110.4 115.8Q176.1 99.8 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,110.3635,115.779)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,221.2255,150.2583)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,208.3976,33.9582)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(120.3635 115.779)" fill="#1A1D23">example-document</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(231.2255 150.2583)" fill="#1A1D23">example-project</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(218.3976 33.9582)" fill="#1A1D23">example-team</text>\n<path d="M-108.1 -5l216.2 0l0 24l-216.2 0Z" transform="translate(180 13)" fill="rgb(0,0,0)" fill-opacity="0" stroke="#3c3c41" stroke-width="0" class="oods-zr-2"></path>\n<text dominant-baseline="central" text-anchor="middle" style="font-size:14px;font-family:sans-serif;font-weight:600;" xml:space="preserve" y="7" transform="translate(180 13)" fill="#1A1D23">Example connected relationships</text>\n<style ><![CDATA[\n.oods-zr-0:hover {\ncursor:pointer;\nstroke-width:4;\n}\n.oods-zr-1:hover {\ncursor:pointer;\nfill:rgba(96,9,26,1);\n}\n.oods-zr-2:hover {\npointer-events:none;\n}\n\n]]>\n\n</style>\n</svg>'}
+      svg: '<svg width="360" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" baseProfile="full" viewBox="0 0 360 200" role="img" aria-label="Example connected relationships" aria-description="Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data."><title>Example connected relationships</title><desc>Synthetic neighborhood edges illustrating relationships that share an endpoint; these are examples, not live graph data.</desc>\n<rect width="360" height="200" x="0" y="0" fill="#F9FAFC"></rect>\n<path d="M208.4 34Q249.7 88.3 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M221.2 150.3Q155.5 166.3 110.4 115.8" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M110.4 115.8Q176.1 99.8 221.2 150.3" fill="none" pointer-events="visible" stroke="rgb(88, 9, 24)" stroke-opacity="0.5" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-0"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,110.3635,115.779)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="0" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,221.2255,150.2583)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="1" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<path d="M1 0A1 1 0 1 1 1 -0.1A1 1 0 0 1 1 0" transform="matrix(5,0,0,5,208.3976,33.9582)" fill="rgb(88, 9, 24)" ecmeta_series_index="0" ecmeta_data_index="2" ecmeta_ssr_type="chart" class="oods-zr-1"></path>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(120.3635 115.779)" fill="#1A1D23">example-document</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(231.2255 150.2583)" fill="#1A1D23">example-project</text>\n<text dominant-baseline="central" text-anchor="start" style="font-size:12px;font-family:sans-serif;" transform="translate(218.3976 33.9582)" fill="#1A1D23">example-team</text>\n<path d="M-108.1 -5l216.2 0l0 24l-216.2 0Z" transform="translate(180 13)" fill="rgb(0,0,0)" fill-opacity="0" stroke="#3c3c41" stroke-width="0" class="oods-zr-2"></path>\n<text dominant-baseline="central" text-anchor="middle" style="font-size:14px;font-family:sans-serif;font-weight:600;" xml:space="preserve" y="7" transform="translate(180 13)" fill="#1A1D23">Example connected relationships</text>\n<style ><![CDATA[\n.oods-zr-0:hover {\ncursor:pointer;\nstroke-width:4;\n}\n.oods-zr-1:hover {\ncursor:pointer;\nfill:rgba(96,9,26,1);\n}\n.oods-zr-2:hover {\npointer-events:none;\n}\n\n]]>\n\n</style>\n</svg>'}
   }
 };
 
@@ -16394,7 +16383,7 @@ var authoredScenarios = [
   { id: "address-editor-fields-and-change", oodsComponentId: "AddressEditor", props: { title: "Shipping address", street: "1 Main St", city: "Springfield", region: "IL", postalCode: "62701" }, slots: {}, initialState: { street: "1 Main St" }, renderExpectation: { name: "change", trigger: "type into the City input", expected: "change emitted with the current street/city/region/postalCode record" }, assertions: ["title is a real h2 heading", "four labelled inputs are prefilled", "change carries the whole address record", "submitting is a no-op"] },
   { id: "address-summary-badge-role", oodsComponentId: "AddressSummaryBadge", props: { label: "Billing address", role: "billing" }, slots: {}, initialState: { status: "billing" }, renderExpectation: { name: "render", trigger: "mount", expected: "visible Billing address label with data-badge-status billing and the address variant" }, assertions: ["label is visible text", "data-badge-status is billing", "data-badge-variant is address", "badge is noninteractive"] },
   { id: "address-validation-timeline-events", oodsComponentId: "AddressValidationTimeline", props: { title: "Address checks", validations: [{ label: "Postal code verified", timestamp: "2026-09-05T12:00:00Z", detail: "Matched carrier database" }, "Geocoded"] }, slots: {}, initialState: { events: 2 }, renderExpectation: { name: "render", trigger: "mount", expected: "a log region titled Address checks with two ordered events, the first timestamped and detailed" }, assertions: ["region has role log and an h2 title", "events are ordered list items", "the timestamp is a time element", "scalar entries render as text"] },
-  { id: "archive-pill-false", oodsComponentId: "ArchivePill", props: { "isArchived": false }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "false remains visible; archive is the badge variant" }, assertions: ["false remains visible", "archive is the badge variant"] },
+  { id: "archive-pill-false", oodsComponentId: "ArchivePill", props: { "isArchived": false }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "Not archived remains visible; machine status remains false; archive is the badge variant" }, assertions: ["Not archived remains visible; machine status remains false", "archive is the badge variant"] },
   { id: "archive-summary-false-and-reason", oodsComponentId: "ArchiveSummary", props: { "isArchived": false, "archivedAt": "2026-09-05T12:00:00Z", "reason": "Retention policy" }, slots: {}, initialState: { content: "populated" }, renderExpectation: { name: "render", trigger: "mount", expected: "No remains visible in its named term; archive date and reason remain associated terms" }, assertions: ["No remains visible in its named term", "archive date and reason remain associated terms"] },
   { id: "archived-row-presentation", oodsComponentId: "ArchivedRowOverlay", props: { "isArchived": true, "showBadge": true, "separateTab": true, "tabLabel": "Archived", "label": "Team subscription" }, slots: {}, initialState: {}, renderExpectation: { name: "render", trigger: "mount", expected: "Archived row stays accessible and its badge and tab label agree" }, assertions: ["Archived row stays accessible and its badge and tab label agree"] },
   { id: "audit-event-type-and-timestamp", oodsComponentId: "AuditEvent", props: { event: "user.updated", timestamp: "2026-09-05T12:00:00Z", detail: "Display name changed" }, slots: {}, initialState: { timestamped: true }, renderExpectation: { name: "render", trigger: "mount", expected: "one audit article with a machine-readable time, the event label and the detail" }, assertions: ["article carries data-event-type audit", "time element has a datetime", "label and detail are visible text"] },
@@ -16606,6 +16595,28 @@ function billingCycle(values) {
   const announcement = `${percent === void 0 ? "Progress unavailable" : `${percent}% complete`} \xB7 ${remainingDays === void 0 ? "Remaining days unavailable" : `${remainingDays} ${remainingDays === 1 ? "day" : "days"} remaining`}`;
   return { percent, remainingDays, announcement, ended };
 }
+var PERIOD_MONTHS = { monthly: 1, quarterly: 3, yearly: 12, annual: 12 };
+function billingPeriodEnd(start, interval) {
+  const date = new Date(start);
+  if (!Number.isFinite(date.getTime())) return void 0;
+  if (interval === "weekly") return new Date(date.getTime() + 7 * 864e5).toISOString();
+  const months = interval ? PERIOD_MONTHS[interval] : void 0;
+  if (!months) return void 0;
+  const end = new Date(date);
+  end.setUTCDate(1);
+  end.setUTCMonth(end.getUTCMonth() + months);
+  end.setUTCDate(Math.min(date.getUTCDate(), new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth() + 1, 0)).getUTCDate()));
+  return end.toISOString();
+}
+function restartedBillingPeriod(at, interval) {
+  return {
+    current_period_start: at,
+    current_period_end: billingPeriodEnd(at, interval),
+    current_period_progress: void 0,
+    next_payment_due_at: at,
+    payment_status: "pending"
+  };
+}
 var NO_NEXT_PAYMENT = "No payment scheduled";
 var NO_LAST_PAYMENT = "No previous payment";
 function billingDate(value) {
@@ -16665,9 +16676,13 @@ function recordCollectionEvents(record2, options = {}) {
     if (typeof at !== "string" || typeof state !== "string") return [];
     return [{ id: "state-" + index, title: String(entry.title ?? state.split(/[_-]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ")), at, description: String(entry.reason ?? ""), kind: "state" }];
   }) : [];
+  const recorded = Array.isArray(record2.payment_history) ? record2.payment_history : [];
   for (const source2 of options.payments ?? []) {
     const at = record2[source2.field];
-    if (typeof at === "string") events.push({ id: "payment-" + source2.field, title: source2.title, at, description: billingSummary(Number(record2.amount), String(record2.currency), options.minorUnits ?? 100, String(record2.billing_interval)), kind: "payment" });
+    if (typeof at !== "string") continue;
+    const paid = recorded.find((row) => row && typeof row === "object" && Date.parse(row.at) === Date.parse(at) && typeof row.amount === "number");
+    const description = paid ? formatBillingAmount(paid.amount, String(paid.currency ?? record2.currency), options.minorUnits ?? 100) : billingSummary(Number(record2.amount), String(record2.currency), options.minorUnits ?? 100, String(record2.billing_interval));
+    events.push({ id: "payment-" + source2.field, title: source2.title, at, description, kind: "payment" });
   }
   for (const source2 of [{ field: "created_at", title: "Created" }, { field: "last_event_at", title: String(record2.last_event ?? "Updated").replaceAll("_", " ") }, { field: "issued_at", title: "Issued" }, { field: "period_start", title: "Period started" }, { field: "ownership_transferred_at", title: "Ownership transferred" }]) {
     const at = record2[source2.field];
@@ -16995,4 +17010,4 @@ function getBaselineCapability(componentId) {
   return componentCapabilityBaseline.rows.find((row) => row.id === componentId);
 }
 
-export { BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, FOUNDATION_V1_EVIDENCE_CLASSES, GOVERNED_DEFINITION, GOVERNED_SURFACES, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, PORTED_COMPONENT_IDS, RESULT_STATES, RESULT_STATE_TONE, SEVERITY_TONES, UI_WORKFLOW_STATES, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, ariaSort, assertStaticSvg, auditSummary, billingAmountMessage, billingAmountText, billingCycle, billingDate, billingIntervalMessage, billingPaymentRows, billingPaymentSummary, billingSummary, chronologicalEvents, componentBehaviors, componentCapabilityBaseline, componentContracts, componentIntake, componentReconciliationProposal, currencyMinorUnits, dateTimeInputValue, defaultVizIntent, deriveStartingComponentCount, editVizIntent, evaluateEmissionEligibility, evaluateFoundationV1, formatBillingAmount, formatDateTime, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizSummaryRows };
+export { BILLING_AMOUNT_ERROR, BILLING_INTERVALS, BILLING_INTERVAL_ERROR, BILLING_MINOR_UNITS, COMPONENT_CLASSIFICATIONS, COMPONENT_CONTRACT_VERSION, COMPONENT_CONTRACT_VERSION_1_1, DEFAULT_COLOR_STATES, EMISSION_ELIGIBILITY_EVIDENCE_CLASSES, FOUNDATION_V1_EVIDENCE_CLASSES, GOVERNED_DEFINITION, GOVERNED_SURFACES, NO_LAST_PAYMENT, NO_NEXT_PAYMENT, NUCLEUS_COMPONENT_IDS, PORTED_COMPONENT_IDS, RESULT_STATES, RESULT_STATE_TONE, SEVERITY_TONES, UI_WORKFLOW_STATES, VIZ_CONTROL_IDS, VIZ_CONTROL_TITLES, VIZ_PREVIEW_TYPES, VIZ_SUMMARY_IDS, 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, formatPriceAmount, formatPriceCode, formatReadOnlyValue, formatRecordLabel, formatReferenceLabel, geoFieldMapping, getBaselineCapability, initialSort, isGovernedComponent, isVizIntentFragment, nextSort, parseBillingAmount, portedComponentContracts, portedScenarios, recipeItemLabels, recordCollectionEvents, restartedBillingPeriod, sharedScenarios, substitutionContractReport, summarizeSubstitutionReport, summaryValue, svgCarriesTitle, traitEventRows, validMinorUnits, validateComponentIntakeDocument, vizControlFields, vizFieldValue, vizSummaryRows };

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@oods/component-contracts",
-  "version": "0.3.1",
-  "description": "Versioned OODS component identities, semantic contracts, shared scenarios, and readiness predicates.",
+  "version": "0.3.3",
+  "description": "Component contracts for OODS Foundry: each component's identity, props, events, states, token roles and accessibility obligations, with shared formatting helpers.",
+  "homepage": "https://oods-foundry.com/",
+  "bugs": {
+    "email": "derek@derekn.com"
+  },
+  "keywords": [
+    "oods",
+    "oods-foundry",
+    "component-contracts",
+    "design-system",
+    "accessibility"
+  ],
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=20.11.1"
+    "node": ">=22.0.0"
   },
   "files": [
     "dist",