@inhuman.tools/plexus-expectations 0.0.0-stage → 0.2.0

package/src/shared/models/index.ts

@@ -0,0 +1,6 @@
+export * from "./WorkContainer.js";
+export * from "./WorkExpectation.js";
+export * from "./Job.js";
+export * from "./DriverSpec.js";
+export * from "./ConnectionSpec.js";
+export { type LiveFacts as LiveFacts } from "./jsonRecord.js";

package/src/shared/models/jsonRecord.ts

@@ -0,0 +1,49 @@
+/**
+ * Plexus `@syncing.record` bags are `Record<string, string>`. Values round-trip
+ * through JSON.stringify; `undefined` is omitted.
+ */
+
+/** Process self-report on ConnectionSpec / DriverSpec. JSON through `liveMap`. */
+export type LiveFacts = {
+  readonly [key: string]: unknown | undefined;
+  readonly models?: readonly string[];
+  readonly tools?: unknown;
+};
+export function readJsonRecord(map: Record<string, string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(map)) {
+    try {
+      out[key] = JSON.parse(raw);
+    } catch {
+      out[key] = raw;
+    }
+  }
+  return deepFreeze(out);
+}
+
+export function writeJsonRecord(
+  map: Record<string, string>,
+  next: Readonly<Record<string, unknown>> | undefined,
+): void {
+  const encoded: Record<string, string> = {};
+  for (const [key, value] of Object.entries(next ?? {})) {
+    if (value === undefined) continue;
+    encoded[key] = JSON.stringify(value);
+  }
+  for (const key of Object.keys(map)) {
+    if (!(key in encoded)) delete map[key];
+  }
+  for (const [key, value] of Object.entries(encoded)) {
+    if (map[key] !== value) map[key] = value;
+  }
+}
+
+export function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  if (Array.isArray(value)) {
+    for (const item of value) deepFreeze(item);
+  } else {
+    for (const item of Object.values(value as Record<string, unknown>)) deepFreeze(item);
+  }
+  return Object.freeze(value);
+}

package/src/shared/revalidation-demand.ts

@@ -0,0 +1,121 @@
+/**
+ * Revalidation demand. Clients publish on kernel awareness; PEW reduces to
+ * none | secondary | primary. Interned connections outlive a session wrap, so
+ * occupancy is not session-plane. Drivers read the reduced token — never clientIds.
+ */
+import { FieldAwareness, type PlexusAwareness } from "@here.build/plexus";
+
+import { ConnectionSpec } from "./models/ConnectionSpec.js";
+import { DriverSpec } from "./models/DriverSpec.js";
+
+export type RevalidationDemand = "none" | "secondary" | "primary";
+
+export const REVALIDATION_DEMAND_LANE = "revalidationDemand";
+export const REVALIDATION_DEMAND_FOCUS_LANE = "revalidationDemandFocus";
+
+export type RevalidationDemandRef =
+  | { readonly kind: "driver"; readonly name: string }
+  | { readonly kind: "connection"; readonly id: string };
+
+export type RevalidationDemandSubject = DriverSpec | ConnectionSpec;
+
+export type RevalidationDemandSource = RevalidationDemandSubject | Iterable<RevalidationDemandSubject | null | undefined> | null | undefined;
+
+export function revalidationDemandRefFromSpec(spec: RevalidationDemandSubject): RevalidationDemandRef {
+  if (isConnectionSubject(spec)) return { kind: "connection", id: spec.id };
+  return { kind: "driver", name: spec.name };
+}
+
+export function collectRevalidationDemandRefs(source: RevalidationDemandSource): RevalidationDemandRef[] {
+  if (source == null) return [];
+  if (isRevalidationDemandSubject(source)) return [revalidationDemandRefFromSpec(source)];
+  const out: RevalidationDemandRef[] = [];
+  const seen = new Set<string>();
+  for (const item of source) {
+    if (item == null || !isRevalidationDemandSubject(item)) continue;
+    const ref = revalidationDemandRefFromSpec(item);
+    const key = refKey(ref);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(ref);
+  }
+  return out;
+}
+
+export function publishRevalidationDemand(hub: PlexusAwareness, refs: readonly RevalidationDemandRef[]): void {
+  const lane = new FieldAwareness(hub, REVALIDATION_DEMAND_LANE);
+  if (refs.length === 0) {
+    lane.clear();
+    return;
+  }
+  lane.set(refs as never);
+}
+
+export function publishRevalidationDemandFocus(hub: PlexusAwareness, ref: RevalidationDemandRef | null): void {
+  const lane = new FieldAwareness(hub, REVALIDATION_DEMAND_FOCUS_LANE);
+  if (ref == null) {
+    lane.clear();
+    return;
+  }
+  lane.set(ref as never);
+}
+
+/** Union of every client's occupancy. Primary wins over secondary. */
+export function revalidationDemandOf(hub: PlexusAwareness, target: RevalidationDemandRef): RevalidationDemand {
+  const focus = new FieldAwareness(hub, REVALIDATION_DEMAND_FOCUS_LANE);
+  for (const clientId of focus.clientIds) {
+    const value = asRevalidationDemandRef(focus.getOther(clientId));
+    if (value != null && sameRef(value, target)) return "primary";
+  }
+  const ambient = new FieldAwareness(hub, REVALIDATION_DEMAND_LANE);
+  for (const clientId of ambient.clientIds) {
+    const list = asRevalidationDemandRefList(ambient.getOther(clientId));
+    if (list.some((item) => sameRef(item, target))) return "secondary";
+  }
+  return "none";
+}
+
+function isConnectionSubject(spec: RevalidationDemandSubject): spec is ConnectionSpec {
+  if (spec instanceof ConnectionSpec) return true;
+  if (spec instanceof DriverSpec) return false;
+  return "driver" in spec && "configuration" in spec;
+}
+
+function isRevalidationDemandSubject(value: unknown): value is RevalidationDemandSubject {
+  if (value instanceof ConnectionSpec || value instanceof DriverSpec) return true;
+  if (typeof value !== "object" || value === null) return false;
+  if ("driver" in value && "configuration" in value) return true;
+  return "importPath" in value && "abilityClaim" in value;
+}
+
+function asRevalidationDemandRef(value: unknown): RevalidationDemandRef | null {
+  if (typeof value !== "object" || value === null) return null;
+  const rec = value as { kind?: unknown; name?: unknown; id?: unknown };
+  if (rec.kind === "driver" && typeof rec.name === "string" && rec.name !== "") {
+    return { kind: "driver", name: rec.name };
+  }
+  if (rec.kind === "connection" && typeof rec.id === "string" && rec.id !== "") {
+    return { kind: "connection", id: rec.id };
+  }
+  return null;
+}
+
+function asRevalidationDemandRefList(value: unknown): RevalidationDemandRef[] {
+  if (!Array.isArray(value)) return [];
+  const out: RevalidationDemandRef[] = [];
+  for (const item of value) {
+    const ref = asRevalidationDemandRef(item);
+    if (ref != null) out.push(ref);
+  }
+  return out;
+}
+
+function sameRef(a: RevalidationDemandRef, b: RevalidationDemandRef): boolean {
+  if (a.kind === "driver" && b.kind === "driver") return a.name === b.name;
+  if (a.kind === "connection" && b.kind === "connection") return a.id === b.id;
+  return false;
+}
+
+function refKey(ref: RevalidationDemandRef): string {
+  return ref.kind === "driver" ? `driver:${ref.name}` : `connection:${ref.id}`;
+}

package/src/shared/role.ts

@@ -0,0 +1,32 @@
+/**
+ * Role occupancy. One awareness lane, keyed by expectation uuid.
+ * Schema is append-only (`PlexusAwareness.MAX_LANES` = 64); a lane per
+ * expectation exhausts the budget. Retract the uuid on leave — occupancy
+ * is presence, not a durable outcome. `""` occupies without a report frame.
+ */
+import { type PlexusAwareness } from "@here.build/plexus";
+
+import { MapFieldAwareness } from "./map-field-awareness.js";
+import { ROLE_EXPECTATIONS_LANE } from "./types.js";
+
+export function reportRole(hub: PlexusAwareness, uuid: string, value: unknown): void {
+  const field = lane(hub);
+  if (value === null) {
+    field.mapDelete(uuid);
+    return;
+  }
+  field.mapSet(uuid, value);
+}
+
+export function retractRole(hub: PlexusAwareness, uuid: string): void {
+  lane(hub).mapDelete(uuid);
+}
+
+/** First value for `uuid` across bases. Missing key is `undefined`. */
+export function roleOf(hub: PlexusAwareness, uuid: string): unknown {
+  return lane(hub).mapGet(uuid);
+}
+
+function lane(hub: PlexusAwareness): MapFieldAwareness {
+  return new MapFieldAwareness(hub, ROLE_EXPECTATIONS_LANE);
+}

package/src/shared/types.ts

@@ -0,0 +1,57 @@
+import type { AwarenessSerializable, AwarenessShape, Plexus, PlexusModel } from "@here.build/plexus";
+
+import type { ConnectionSpec } from "./models/ConnectionSpec.js";
+import type { DriverSpec } from "./models/DriverSpec.js";
+import type { WorkContainer } from "./models/WorkContainer.js";
+import type { RevalidationDemandRef } from "./revalidation-demand.js";
+
+/** `null` = never ensured / never loaded. */
+export type ReadyState = null | "bootstrapping" | "ready" | "failed";
+
+export function asReadyState(value: unknown): ReadyState {
+  if (value === "bootstrapping" || value === "ready" || value === "failed") return value;
+  return null;
+}
+
+/**
+ * Revalidation demand is kernel-plane: interned connections outlive a session wrap.
+ * Live catalog faces stay on DriverSpec / ConnectionSpec, not awareness lanes.
+ */
+export type KernelAwareness = AwarenessShape & {
+  revalidationDemand?: readonly RevalidationDemandRef[];
+  revalidationDemandFocus?: RevalidationDemandRef | null;
+};
+
+/** Live shell tails: one lane, `Record<job.uuid, frame>`. */
+export const SHELL_TAILS_LANE = "shell-tails";
+
+/** Role occupancy: one lane, `Record<expectation.uuid, frame | "">`. */
+export const ROLE_EXPECTATIONS_LANE = "role:expectations";
+
+/** Statusline left slot: the daemon's last successful eval. */
+export const STATUSLINE_LANE = "statusline";
+
+export type SessionAwareness = AwarenessShape & {
+  /** Operator `policy.json` load/eval throw. Presence, not a leaf vote. */
+  policyError?: string;
+  [STATUSLINE_LANE]?: string;
+  [SHELL_TAILS_LANE]?: Record<string, AwarenessSerializable>;
+  [ROLE_EXPECTATIONS_LANE]?: Record<string, AwarenessSerializable>;
+};
+
+/**
+ * Catalog parent of {@link DriverSpec} / {@link ConnectionSpec}.
+ * Ordinary records, not virtual maps.
+ */
+export type SpecCatalog = PlexusModel<null> & {
+  readonly drivers: Record<string, DriverSpec>;
+  readonly connections: Record<string, ConnectionSpec>;
+};
+
+/** Product membership is YAML projected onto these records. */
+export type KernelRootModel = SpecCatalog;
+
+export type SessionRootModel = WorkContainer;
+
+export type KernelPlexus = Plexus<KernelRootModel, KernelAwareness>;
+export type SessionPlexus = Plexus<SessionRootModel, SessionAwareness>;