@company-semantics/contracts 0.137.0 → 0.139.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.137.0",
+  "version": "0.139.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -612,3 +612,10 @@ export type {
   RequestDescriptor,
   SchedulerEvent,
 } from './requests'
+
+// Mutation policy types (lane behavior semantics)
+export type { MutationPolicy } from './mutations'
+
+// Observability envelope types (shared metric shape)
+export { REQUEST_ID_HEADER } from './observability'
+export type { Labels, MetricEnvelope, SchedulerMetricName } from './observability'

package/src/mutations.ts

@@ -0,0 +1,13 @@
+export type { MutationBehavior } from './requests';
+
+export type MutationPolicy = {
+  /**
+   * collapse — the newer mutation supersedes older in-flight or queued mutations
+   *            on the same resource lane. Use for idempotent field sets (rename).
+   * queue    — FIFO lane per resource. No collapse. Use when each mutation carries
+   *            meaningful intent that must be preserved (reorder, append, toggle-sequence).
+   * parallel — independent mutations on different resourceIds may run concurrently;
+   *            same-resource requests still serialize to avoid lost writes.
+   */
+  behavior: 'collapse' | 'queue' | 'parallel';
+};

package/src/observability.ts

@@ -0,0 +1,16 @@
+export const REQUEST_ID_HEADER = 'x-request-id';
+
+export type Labels = Record<string, string>;
+export type MetricEnvelope =
+  | { kind: 'counter'; name: string; value: number; labels?: Labels; ts: number }
+  | { kind: 'gauge'; name: string; value: number; labels?: Labels; ts: number }
+  | { kind: 'histogram'; name: string; value: number; labels?: Labels; ts: number };
+
+export type SchedulerMetricName =
+  | 'scheduler.inflight_requests'
+  | 'scheduler.queue_depth'
+  | 'scheduler.queue_wait_ms'
+  | 'scheduler.dedupe_hits'
+  | 'scheduler.heap_used_bytes'
+  | 'scheduler.rss_bytes'
+  | 'scheduler.fetch_latency_ms';