@robosystems/client 0.5.8 → 0.5.10

package/types.gen.d.ts

@@ -364,6 +364,132 @@ export type AvailableGraphTiersResponse = {
      */
     tiers: Array<GraphTierInfo>;
 };
+/**
+ * BackfillPeriodOutcome
+ *
+ * Per-month result of a plan-history backfill pass.
+ */
+export type BackfillPeriodOutcome = {
+    /**
+     * Period
+     *
+     * The month, in YYYY-MM
+     */
+    period: string;
+    /**
+     * Status
+     *
+     * stamped: reopen → reclose completed. skipped_drafts: the month holds draft entries the backfill refuses to post — review via list-period-drafts, then close-period or re-run. failed: the reclose raised; processing halted (see detail).
+     */
+    status: string;
+    /**
+     * Statements Stamped
+     *
+     * Whether the reclose stamped canonical statement FactSets. False with a statement_stamp_note soft-skip when reporting isn't set up.
+     */
+    statements_stamped?: boolean;
+    /**
+     * Statement Stamp Note
+     *
+     * Soft-skip reason when statements_stamped is false
+     */
+    statement_stamp_note?: string | null;
+    /**
+     * Statement Rule Summary
+     *
+     * Statement-rule verification tally for the month's stamped sets (pass/fail/error/skipped); None when no rules ran.
+     */
+    statement_rule_summary?: {
+        [key: string]: number;
+    } | null;
+    /**
+     * Detail
+     *
+     * Human-readable detail for skipped/failed months
+     */
+    detail?: string | null;
+};
+/**
+ * BackfillPlanHistoryOperation
+ *
+ * Compile monthly statement history behind the close boundary.
+ */
+export type BackfillPlanHistoryOperation = {
+    /**
+     * Start Period
+     *
+     * YYYY-MM period to backfill from. Clamped to the earliest month with ledger data; defaults to that month when omitted. Must be on or before `closed_through`.
+     */
+    start_period?: string | null;
+    /**
+     * Max Periods
+     *
+     * Maximum months to restamp in this call. Each month runs a full reopen → reclose cycle; keep chunks modest and loop on `remaining_periods`.
+     */
+    max_periods?: number;
+    /**
+     * Allow Stale Sync
+     *
+     * Override the sync-currency gate on each reclose. Historical months predate the last sync in the normal case, so this is rarely needed.
+     */
+    allow_stale_sync?: boolean;
+    /**
+     * Restamp
+     *
+     * Also re-derive months that ALREADY have canonical statement sets (default: skip them). Use after an engine improvement changes what a stamp produces — each month reruns the full reopen → reclose cycle and replaces its sets. A restamp run is not self-resuming (every month in range stays a candidate); advance `start_period` between chunks.
+     */
+    restamp?: boolean;
+    /**
+     * Note
+     *
+     * Free-form note attached to each close audit event
+     */
+    note?: string | null;
+};
+/**
+ * BackfillPlanHistoryResponse
+ *
+ * Response from one chunked plan-history backfill call.
+ */
+export type BackfillPlanHistoryResponse = {
+    fiscal_calendar: FiscalCalendarResponse;
+    /**
+     * Earliest Available Period
+     *
+     * First month with ledger data — the hard floor for backfill
+     */
+    earliest_available_period: string;
+    /**
+     * Effective Start Period
+     *
+     * The start actually used after clamping to earliest_available_period
+     */
+    effective_start_period: string;
+    /**
+     * Closed Through
+     *
+     * The close boundary the backfill runs up to (inclusive)
+     */
+    closed_through: string;
+    /**
+     * Period Rows Created
+     *
+     * FiscalPeriod rows seeded (baseline-closed) for months the calendar didn't cover yet
+     */
+    period_rows_created?: number;
+    /**
+     * Processed
+     *
+     * Months this call attempted, oldest first
+     */
+    processed?: Array<BackfillPeriodOutcome>;
+    /**
+     * Remaining Periods
+     *
+     * Months still lacking canonical statement sets that this call did not attempt (beyond max_periods, or after a failure halt). Loop until empty.
+     */
+    remaining_periods?: Array<string>;
+};
 /**
  * BackupCreateRequest
  *
@@ -1193,6 +1319,34 @@ export type ClosePeriodResponse = {
      * ids of schedule Structures whose rules were evaluated during the close. Pairs with rule_summary.
      */
     evaluated_structure_ids?: Array<string>;
+    /**
+     * Statements Stamped
+     *
+     * Whether the close stamped the period's canonical statement FactSets (the close-time pivot). False when the tenant hasn't set up reporting yet — see statement_stamp_note.
+     */
+    statements_stamped?: boolean;
+    /**
+     * Statement Stamp Note
+     *
+     * Soft-skip reason when statements_stamped is false: no_coa_mapping | no_entity | no_statement_structures | no_taxonomy.
+     */
+    statement_stamp_note?: string | null;
+    /**
+     * Stamped Statement Sets
+     *
+     * structure_id -> fact_set_id for every canonical statement FactSet minted by this close (report_id NULL; replaced on reclose).
+     */
+    stamped_statement_sets?: {
+        [key: string]: string;
+    };
+    /**
+     * Statement Rule Summary
+     *
+     * Aggregated statement-rule verification outcome across the stamped structures — keys: pass/fail/error/skipped. None when no statement rules exist. Distinct from rule_summary (the schedule-rule pass).
+     */
+    statement_rule_summary?: {
+        [key: string]: number;
+    } | null;
 };
 /**
  * ComputeForecastRequest
@@ -2143,6 +2297,18 @@ export type CreateForecastRequest = {
      * Lever assertions — at least one.
      */
     levers: Array<LeverAssertionRequest>;
+    /**
+     * Line Assertions
+     *
+     * Direct statement-line assertions (manual overrides). Each names a calc-DAG leaf and wins over driver rules and carry-forward for the months it asserts.
+     */
+    line_assertions?: Array<LineAssertionRequest>;
+    /**
+     * Line Growth
+     *
+     * Per-line growth trajectories. Each names an income-statement leaf and grows it month-over-month at the asserted rate — the generic form of the revenue growth lever, for lines the catalog doesn't drive (opex trajectories, cost-cut ramps).
+     */
+    line_growth?: Array<LineGrowthRequest>;
     /**
      * Entity Id
      *
@@ -3000,9 +3166,27 @@ export type DatabaseHealthResponse = {
     /**
      * Memory Usage Mb
      *
-     * Memory usage in MB
+     * Instance memory in use, MB. Only populated for dedicated single-tenant instances; null on shared repositories and packed tiers.
      */
     memory_usage_mb?: number | null;
+    /**
+     * Memory Usage Percent
+     *
+     * Instance memory in use, percent. Expect high values during materialization — the engine deliberately boosts to near the whole instance while rebuilding. Read `resource_status` rather than this number alone. Dedicated instances only.
+     */
+    memory_usage_percent?: number | null;
+    /**
+     * Cpu Usage Percent
+     *
+     * Instance CPU in use, percent. Dedicated single-tenant instances only.
+     */
+    cpu_usage_percent?: number | null;
+    /**
+     * Resource Status
+     *
+     * Interpreted instance load: 'idle' (headroom), 'busy' (working normally — typical while materializing), 'constrained' (sustained pressure worth acting on). Null when resource metrics are not exposed.
+     */
+    resource_status?: string | null;
     /**
      * Storage Usage Mb
      *
@@ -3874,6 +4058,12 @@ export type ElementLite = {
      * Value-domain vocabulary (monetary | ratio | percent | multiple | days | string | …). None means untyped; fall back to is_monetary.
      */
     item_type?: string | null;
+    /**
+     * Documentation
+     *
+     * The element's documentation-role label — the catalog's authoritative value semantics (e.g. whether a percent driver is a growth rate or a rate-on-base fraction). None when the element carries no documentation label.
+     */
+    documentation?: string | null;
 };
 /**
  * ElementUpdatePatch
@@ -5003,6 +5193,18 @@ export type ForecastMechanics = {
      * Expanded lever assertions (authoring order).
      */
     levers: Array<LeverAssertionLite>;
+    /**
+     * Line Assertions
+     *
+     * Direct statement-line assertions (authoring order) — manual overrides that win over driver rules and carry-forward for the months they name.
+     */
+    line_assertions?: Array<LineAssertionLite>;
+    /**
+     * Line Growth
+     *
+     * Per-line growth trajectories (authoring order) — each grows an income-statement leaf month-over-month at the asserted rate, compounding from the base month.
+     */
+    line_growth?: Array<LineGrowthLite>;
     /**
      * Computed Months
      *
@@ -6924,13 +7126,21 @@ export type LeverAssertionLite = {
  * One lever's asserted values for the scenario.
  *
  * ``qname`` must resolve to an ``rs-driver:*`` catalog element (the
- * create handler rejects anything else). Value conventions follow the
- * catalog: percent levers are decimals per month (0.03 = 3%/month),
- * days levers are day counts.
+ * create handler rejects anything else). Each lever's value semantics
+ * are defined by its catalog element's documentation — surfaced as
+ * ``documentation`` on the elements bundled in the forecast block's
+ * envelope (``get-information-block``). Percent levers are decimals but
+ * their *meaning* varies by lever: growth levers are month-over-month
+ * rates (``RevenueGrowthRate`` 0.03 = +3%/month, compounding), while
+ * rate-on-base levers are fractions of the same month's base
+ * (``CostOfRevenueRate`` 0.62 = cost of revenue at 62% of that month's
+ * revenues — not a growth rate). Days levers (``DaysSalesOutstanding``,
+ * ``DaysPayableOutstanding``) are day counts.
  *
  * ``value`` is a uniform fill across the whole horizon;
  * ``values_by_period`` overrides individual months (``"YYYY-MM"``
- * keys). At least one of the two must be provided. Months covered by
+ * keys) — e.g. a margin-compression ramp asserts a different rate each
+ * month. At least one of the two must be provided. Months covered by
  * neither carry no assertion — the lever's rule is inactive for that
  * month and its target falls to the engine's carry-forward default.
  */
@@ -6956,6 +7166,196 @@ export type LeverAssertionRequest = {
         [key: string]: number;
     } | null;
 };
+/**
+ * LineAssertionLite
+ *
+ * One statement line's persisted direct assertion inside
+ * ``ForecastMechanics``.
+ *
+ * The manual-override sibling of :class:`LeverAssertionLite`: a lever
+ * asserts a *driver* whose rule derives a line; a line assertion pins
+ * the **line itself** (a calc-DAG leaf) to typed values for the months
+ * it names — winning over driver rules and carry-forward for exactly
+ * those months (a displaced rule surfaces in the compute response's
+ * ``skipped`` list). Subtotals stay calc-DAG-derived, so a manual line
+ * still articulates through RollUps, RE, balancing cash, and derived
+ * CF, and stays verification-gated.
+ *
+ * Same persistence doctrine as levers: values are duplicated as
+ * authored facts in the scenario's lever FactSet (facts are what
+ * ``compute-forecast`` binds); this mechanics copy is the
+ * operator-legible round-trip shape.
+ */
+export type LineAssertionLite = {
+    /**
+     * Qname
+     *
+     * Asserted statement-leaf qname.
+     */
+    qname: string;
+    /**
+     * Element Id
+     *
+     * Resolved tenant element id.
+     */
+    element_id: string;
+    /**
+     * Item Type
+     *
+     * Format family from the element (monetary | ...).
+     */
+    item_type?: string | null;
+    /**
+     * Period Type
+     *
+     * The element's period type — duration assertions pin IS lines; instant assertions pin BS lines through the roll.
+     */
+    period_type?: string;
+    /**
+     * Values By Period
+     *
+     * Expanded per-month assertions keyed by ``YYYY-MM``.
+     */
+    values_by_period: {
+        [key: string]: number;
+    };
+};
+/**
+ * LineAssertionRequest
+ *
+ * One statement line's directly asserted values for the scenario.
+ *
+ * The manual-override half of the authored surface: where a lever
+ * asserts a *driver* (growth %, DSO) whose rule derives the line, a
+ * line assertion asserts the **line itself** — an rs-gaap (or tenant
+ * extension) statement leaf pinned to typed values for the months it
+ * names. Assertions win over driver rules and carry-forward for those
+ * months (a displaced rule lands in ``skipped``, legibly); months the
+ * assertion doesn't name keep the engine's normal derivation.
+ *
+ * **Leaves only** — subtotals stay calc-DAG-derived, so a manually set
+ * line still articulates through RollUps, RE, balancing cash, and the
+ * derived CF, and stays verification-gated (the whole pitch vs a
+ * spreadsheet cell). The create handler rejects calc-parent qnames.
+ *
+ * Value/period grammar is identical to levers: ``value`` is a uniform
+ * fill across the horizon, ``values_by_period`` overrides individual
+ * months. The canonical uses: zero out a base-month one-off so
+ * carry-forward stops replicating it, or hold a line at a known budget
+ * number no driver models.
+ */
+export type LineAssertionRequest = {
+    /**
+     * Qname
+     *
+     * QName of the statement leaf to assert (e.g. ``rs-gaap:NonoperatingIncomeExpense``). Must be a calc-DAG leaf; rs-driver concepts belong in ``levers``.
+     */
+    qname: string;
+    /**
+     * Value
+     *
+     * Uniform value asserted for every month of the horizon.
+     */
+    value?: number | null;
+    /**
+     * Values By Period
+     *
+     * Per-month overrides keyed by ``YYYY-MM``. Wins over ``value`` for the months it names.
+     */
+    values_by_period?: {
+        [key: string]: number;
+    } | null;
+};
+/**
+ * LineGrowthLite
+ *
+ * One statement line's persisted growth trajectory inside
+ * ``ForecastMechanics``.
+ *
+ * The generic per-line form of the revenue growth lever: grows an
+ * income-statement leaf month-over-month at the asserted rate
+ * (``line[t] = line[t-1] * (1 + rate[t])``), compounding from the base
+ * month's value. Months without a rate keep the engine's carry-forward.
+ * Duration leaves only; disjoint from ``line_assertions`` and from any
+ * active catalog rule's target (one owner per line).
+ *
+ * Persistence deviates from levers/assertions deliberately: rates are
+ * NOT duplicated as facts in the scenario FactSet — a growth rate on a
+ * monetary statement element would be a unit-lying fact. This mechanics
+ * copy is the single authored store; ``compute-forecast`` binds rates
+ * from here.
+ */
+export type LineGrowthLite = {
+    /**
+     * Qname
+     *
+     * Grown statement-leaf qname.
+     */
+    qname: string;
+    /**
+     * Element Id
+     *
+     * Resolved tenant element id.
+     */
+    element_id: string;
+    /**
+     * Item Type
+     *
+     * Always 'percent' — the grid row renders rates, not values.
+     */
+    item_type?: string;
+    /**
+     * Values By Period
+     *
+     * Expanded per-month growth rates keyed by ``YYYY-MM``.
+     */
+    values_by_period: {
+        [key: string]: number;
+    };
+};
+/**
+ * LineGrowthRequest
+ *
+ * One statement line's asserted growth trajectory for the scenario.
+ *
+ * The generic per-line sibling of ``rs-driver:RevenueGrowthRate``: where
+ * the catalog lever grows *revenue* through its seeded rule, a line
+ * growth entry grows **any income-statement leaf** at a month-over-month
+ * rate — ``value`` -0.05 cuts the line 5% per month, compounding from
+ * the base month's value. This is what expense trajectories ("opex +2%/mo
+ * with inflation", "cut costs 5%/mo starting October") use; without it
+ * every unmodeled line just carries flat.
+ *
+ * Semantics per month: ``line[t] = line[t-1] * (1 + rate[t])``. Months
+ * the entry doesn't name keep the engine's carry-forward (grow-then-hold
+ * ramps fall out of ``values_by_period`` naturally). **Duration leaves
+ * only**: balance-sheet lines roll from the IS and the working-capital
+ * levers — grow the driving IS line instead. A line already driven by an
+ * active catalog rule (e.g. Revenues with ``RevenueGrowthRate`` set) or
+ * named by a ``line_assertions`` entry is rejected — one owner per line.
+ */
+export type LineGrowthRequest = {
+    /**
+     * Qname
+     *
+     * QName of the income-statement leaf to grow (e.g. ``rs-gaap:ResearchAndDevelopmentExpense``). Must be a calc-DAG duration leaf.
+     */
+    qname: string;
+    /**
+     * Value
+     *
+     * Uniform month-over-month growth rate for every month of the horizon (decimal: 0.02 = +2%/mo, -0.05 = -5%/mo).
+     */
+    value?: number | null;
+    /**
+     * Values By Period
+     *
+     * Per-month rate overrides keyed by ``YYYY-MM``. Wins over ``value`` for the months it names; months named by neither carry the line's prior value (rate 0).
+     */
+    values_by_period?: {
+        [key: string]: number;
+    } | null;
+};
 /**
  * LineItemMetadataPredicate
  *
@@ -7718,6 +8118,51 @@ export type OperationEnvelopeAssociationResponse = {
      */
     idempotentReplay?: boolean;
 };
+/**
+ * OperationEnvelope[BackfillPlanHistoryResponse]
+ */
+export type OperationEnvelopeBackfillPlanHistoryResponse = {
+    /**
+     * Operation
+     *
+     * Kebab-case operation name
+     */
+    operation: string;
+    /**
+     * Operationid
+     *
+     * op_-prefixed ULID for audit and SSE correlation
+     */
+    operationId: string;
+    /**
+     * Status
+     *
+     * Operation lifecycle state
+     */
+    status: 'completed' | 'pending' | 'failed';
+    /**
+     * Command-specific result payload
+     */
+    result?: BackfillPlanHistoryResponse | null;
+    /**
+     * At
+     *
+     * ISO-8601 UTC timestamp
+     */
+    at: string;
+    /**
+     * Createdby
+     *
+     * User ID that initiated the operation (null for legacy callers)
+     */
+    createdBy?: string | null;
+    /**
+     * Idempotentreplay
+     *
+     * True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.
+     */
+    idempotentReplay?: boolean;
+};
 /**
  * OperationEnvelope[BindTextBlockResponse]
  */
@@ -13916,11 +14361,13 @@ export type UpdateEventHandlerRequest = {
  *
  * Update a forecast block in place.
  *
- * Mutable: name, scenario_kind, horizon_months, base_period, levers.
- * ``levers`` is a **full replace** when provided (partial lever edits
- * would make the asserted set ambiguous). Updating does NOT recompute —
- * previously computed scenario months go stale until the next
- * ``compute-forecast`` run (the compute-metrics drift semantics).
+ * Mutable: name, scenario_kind, horizon_months, base_period, levers,
+ * line_assertions. ``levers`` and ``line_assertions`` are each a
+ * **full replace** when provided (partial edits would make the asserted
+ * set ambiguous); replacing one leaves the other as stored. Updating
+ * does NOT recompute — previously computed scenario months go stale
+ * until the next ``compute-forecast`` run (the compute-metrics drift
+ * semantics).
  */
 export type UpdateForecastRequest = {
     /**
@@ -13951,6 +14398,18 @@ export type UpdateForecastRequest = {
      * Full replacement of the lever set when provided.
      */
     levers?: Array<LeverAssertionRequest> | null;
+    /**
+     * Line Assertions
+     *
+     * Full replacement of the line-assertion set when provided. Pass an empty list to clear every assertion.
+     */
+    line_assertions?: Array<LineAssertionRequest> | null;
+    /**
+     * Line Growth
+     *
+     * Full replacement of the line-growth set when provided. Pass an empty list to clear every growth entry.
+     */
+    line_growth?: Array<LineGrowthRequest> | null;
 };
 /**
  * UpdateInformationBlockRequest
@@ -14953,7 +15412,7 @@ export type UpdateForecastArm = {
      */
     block_type: 'forecast';
     /**
-     * Forecast update payload.
+     * Forecast update payload. Updating does NOT recompute — lever, horizon, or base-period changes leave the scenario's computed months stale until the next `compute-forecast` run.
      */
     payload: UpdateForecastRequest;
 };
@@ -17509,7 +17968,7 @@ export type GetGraphMetricsData = {
         graph_id: string;
     };
     query?: never;
-    url: '/v1/graphs/{graph_id}/analytics';
+    url: '/v1/graphs/{graph_id}/metrics';
 };
 export type GetGraphMetricsErrors = {
     /**
@@ -17549,7 +18008,7 @@ export type GetGraphMetricsResponses = {
     200: GraphMetricsResponse;
 };
 export type GetGraphMetricsResponse = GetGraphMetricsResponses[keyof GetGraphMetricsResponses];
-export type GetGraphUsageAnalyticsData = {
+export type GetGraphUsageData = {
     body?: never;
     path: {
         /**
@@ -17589,9 +18048,9 @@ export type GetGraphUsageAnalyticsData = {
          */
         include_events?: boolean;
     };
-    url: '/v1/graphs/{graph_id}/analytics/usage';
+    url: '/v1/graphs/{graph_id}/usage';
 };
-export type GetGraphUsageAnalyticsErrors = {
+export type GetGraphUsageErrors = {
     /**
      * Invalid request
      */
@@ -17621,14 +18080,14 @@ export type GetGraphUsageAnalyticsErrors = {
      */
     500: ErrorResponse;
 };
-export type GetGraphUsageAnalyticsError = GetGraphUsageAnalyticsErrors[keyof GetGraphUsageAnalyticsErrors];
-export type GetGraphUsageAnalyticsResponses = {
+export type GetGraphUsageError = GetGraphUsageErrors[keyof GetGraphUsageErrors];
+export type GetGraphUsageResponses = {
     /**
      * Successful Response
      */
     200: GraphUsageResponse;
 };
-export type GetGraphUsageAnalyticsResponse = GetGraphUsageAnalyticsResponses[keyof GetGraphUsageAnalyticsResponses];
+export type GetGraphUsageResponse = GetGraphUsageResponses[keyof GetGraphUsageResponses];
 export type ExecuteCypherData = {
     body: CypherStatementRequest;
     path: {
@@ -22915,6 +23374,65 @@ export type ReopenPeriodResponses = {
     200: OperationEnvelopeFiscalCalendarResponse;
 };
 export type ReopenPeriodResponse = ReopenPeriodResponses[keyof ReopenPeriodResponses];
+export type BackfillPlanHistoryData = {
+    body: BackfillPlanHistoryOperation;
+    headers?: {
+        /**
+         * Idempotency-Key
+         */
+        'Idempotency-Key'?: string | null;
+    };
+    path: {
+        /**
+         * Graph Id
+         */
+        graph_id: string;
+    };
+    query?: never;
+    url: '/extensions/roboledger/{graph_id}/operations/backfill-plan-history';
+};
+export type BackfillPlanHistoryErrors = {
+    /**
+     * Invalid request
+     */
+    400: ErrorResponse;
+    /**
+     * Authentication required
+     */
+    401: ErrorResponse;
+    /**
+     * Access denied
+     */
+    403: ErrorResponse;
+    /**
+     * Resource not found
+     */
+    404: ErrorResponse;
+    /**
+     * Idempotency-Key conflict — key reused with different body
+     */
+    409: ErrorResponse;
+    /**
+     * Validation error
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+    /**
+     * Internal server error
+     */
+    500: ErrorResponse;
+};
+export type BackfillPlanHistoryError = BackfillPlanHistoryErrors[keyof BackfillPlanHistoryErrors];
+export type BackfillPlanHistoryResponses = {
+    /**
+     * Successful Response
+     */
+    200: OperationEnvelopeBackfillPlanHistoryResponse;
+};
+export type BackfillPlanHistoryResponse2 = BackfillPlanHistoryResponses[keyof BackfillPlanHistoryResponses];
 export type CreateReportData = {
     body: CreateReportRequest;
     headers?: {