@opengeni/api-router 0.17.0 → 0.21.0

package/src/routes/workspace-state.ts

@@ -2,11 +2,14 @@ import {
   WORKSPACE_STATE_MAX_BASES,
   WORKSPACE_STATE_MAX_TOPICS,
   WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WorkspaceStateQuery,
   WorkspaceStateResponse,
 } from "@opengeni/contracts";
 import { hasPermission, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
 import {
   getWorkspace,
+  getCurrentPreferenceRegistryGovernanceMetadata,
+  getWorkspaceStateAcceptedAttemptGovernance,
   listWorkspaceStateMemoryRecords,
   listWorkspaceInstructionPolicyRevisions,
 } from "@opengeni/db";
@@ -19,11 +22,12 @@ import { projectWorkspaceState } from "../workspace-state-projection";
 export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/workspace-state", async (context) => {
     const workspaceId = context.req.param("workspaceId");
+    const query = WorkspaceStateQuery.parse(context.req.query());
     const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
     const generatedAt = new Date().toISOString();
     const canInspectKnowledge = hasPermission(grant.permissions, "documents:search");
 
-    const [workspace, policies, knowledge] = await Promise.all([
+    const [workspace, policies, knowledge, attemptGovernance] = await Promise.all([
       getWorkspace(deps.db, workspaceId),
       listWorkspaceInstructionPolicyRevisions(deps.db, workspaceId, { limit: 1 }),
       canInspectKnowledge
@@ -40,6 +44,46 @@ export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): voi
             return { documents, memories };
           })()
         : Promise.resolve(null),
+      query.attemptId
+        ? getWorkspaceStateAcceptedAttemptGovernance(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            attemptId: query.attemptId,
+          }).then(async (snapshot) => {
+            if (!snapshot) return { status: "unavailable" as const };
+            const currentPreferences = await getCurrentPreferenceRegistryGovernanceMetadata(
+              deps.db,
+              {
+                workspaceId,
+                subjectId: grant.subjectId,
+              },
+            );
+            return {
+              status: "available" as const,
+              attemptId: snapshot.attemptId,
+              executionGeneration: snapshot.executionGeneration,
+              acceptedAt: snapshot.acceptedAt,
+              policySnapshot: snapshot.policySnapshot,
+              preferenceSnapshot: snapshot.preferenceSnapshot
+                ? {
+                    id: snapshot.preferenceSnapshot.id,
+                    descriptorHash: snapshot.preferenceSnapshot.descriptorHash,
+                    descriptors: snapshot.preferenceSnapshot.descriptors.map((descriptor) => ({
+                      id: descriptor.id,
+                      revisionId: descriptor.revisionId,
+                      contentHash: descriptor.contentHash,
+                      activeVersion: descriptor.activeVersion,
+                      scope: descriptor.scope,
+                    })),
+                    truncated: snapshot.preferenceSnapshot.truncated,
+                    createdAt: snapshot.preferenceSnapshot.createdAt,
+                  }
+                : null,
+              currentPreferences,
+            };
+          })
+        : Promise.resolve(null),
     ]);
 
     if (!workspace) {
@@ -54,6 +98,7 @@ export function registerWorkspaceStateRoutes(app: Hono, deps: ApiRouteDeps): voi
           workspaceAgentInstructions: workspace.agentInstructions,
           policies,
           knowledge,
+          attemptGovernance,
         }),
       ),
     );

package/src/workspace-state-projection.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   KnowledgeMemoryKind,
   KnowledgeMemoryStatus,
@@ -10,6 +11,8 @@ import {
   WORKSPACE_STATE_TOPIC_MAX_CHARS,
   WorkspaceStateResponse,
   type WorkspaceInstructionPolicyListResponse,
+  type WorkspaceInstructionPolicySnapshot,
+  type WorkspaceStateGovernanceDriftStatus,
   type WorkspaceStateGap,
   type WorkspaceStateMemoryKindCounts,
   type WorkspaceStateMemoryStatusCounts,
@@ -23,14 +26,213 @@ type KnowledgeProjectionInput = {
   memories: WorkspaceStateMemoryRecord[];
 };
 
+type PreferenceGovernanceIdentity = {
+  id: string;
+  revisionId: string;
+  contentHash: string;
+  activeVersion: number;
+  scope: "organization" | "workspace" | "user";
+};
+
+type AttemptGovernanceProjectionInput =
+  | { status: "unavailable" }
+  | {
+      status: "available";
+      attemptId: string;
+      executionGeneration: number;
+      acceptedAt: string;
+      policySnapshot: WorkspaceInstructionPolicySnapshot | null;
+      preferenceSnapshot: {
+        id: string;
+        descriptorHash: string;
+        descriptors: PreferenceGovernanceIdentity[];
+        truncated: boolean;
+        createdAt: string;
+      } | null;
+      currentPreferences: {
+        descriptors: PreferenceGovernanceIdentity[];
+        truncated: boolean;
+      };
+    };
+
 export type WorkspaceStateProjectionInput = {
   workspaceId: string;
   generatedAt: string;
   workspaceAgentInstructions: string | null;
   policies: WorkspaceInstructionPolicyListResponse;
   knowledge: KnowledgeProjectionInput | null;
+  attemptGovernance?: AttemptGovernanceProjectionInput | null;
 };
 
+function hashIdentities(values: readonly string[]): string {
+  return createHash("sha256").update(values.join("\n"), "utf8").digest("hex");
+}
+
+function policyTargetKey(value: { kind: string; scope: string; roleKey: string | null }): string {
+  return `${value.kind}:${value.scope}:${value.roleKey ?? ""}`;
+}
+
+function policyTargetKeysForRole(policyRole: string | null): Set<string> {
+  const keys = new Set(["charter:global:", "policy:global:"]);
+  if (policyRole !== null) keys.add(`policy:role:${policyRole}`);
+  return keys;
+}
+
+function policyIdentity(value: {
+  kind: string;
+  scope: string;
+  roleKey: string | null;
+  revisionId: string;
+  contentHash: string;
+  activationVersion: number;
+}): string {
+  return `${policyTargetKey(value)}:${value.revisionId}:${value.contentHash}:${value.activationVersion}`;
+}
+
+function preferenceIdentity(value: PreferenceGovernanceIdentity): string {
+  return `${value.scope}:${value.id}:${value.revisionId}:${value.contentHash}:${value.activeVersion}`;
+}
+
+function classifyIdentityDrift(
+  snapshotIdentities: readonly string[],
+  currentIdentities: readonly string[],
+  snapshotKeys: readonly string[],
+  currentKeys: readonly string[],
+): "identical" | "changed" | "superseded" {
+  if (snapshotIdentities.join("\n") === currentIdentities.join("\n")) return "identical";
+  return snapshotKeys.join("\n") === currentKeys.join("\n") ? "superseded" : "changed";
+}
+
+function overallDriftStatus(
+  policy: WorkspaceStateGovernanceDriftStatus,
+  preferences: WorkspaceStateGovernanceDriftStatus,
+): WorkspaceStateGovernanceDriftStatus {
+  for (const status of ["unavailable", "truncated", "missing", "changed", "superseded"] as const) {
+    if (policy === status || preferences === status) return status;
+  }
+  return "identical";
+}
+
+function attemptGovernanceProjection(input: WorkspaceStateProjectionInput) {
+  const governance = input.attemptGovernance ?? null;
+  if (governance === null) return { status: "not_requested" as const };
+  if (governance.status === "unavailable") {
+    return {
+      status: "unavailable" as const,
+      reason: "attempt_not_found_or_not_authorized" as const,
+      driftStatus: "unavailable" as const,
+    };
+  }
+
+  const policySnapshot = governance.policySnapshot;
+  let policyStatus: WorkspaceStateGovernanceDriftStatus = "missing";
+  let policySnapshotHash: string | null = null;
+  let policyCurrentHash: string | null = null;
+  let policySnapshotTargetCount = 0;
+  let policyCurrentTargetCount = 0;
+  if (policySnapshot) {
+    const snapshotEntries = [...policySnapshot.entries].sort((left, right) =>
+      policyTargetKey(left).localeCompare(policyTargetKey(right)),
+    );
+    const snapshotKeys = snapshotEntries.map(policyTargetKey);
+    const relevantTargetKeys = policyTargetKeysForRole(policySnapshot.policyRole);
+    const currentEntries = input.policies.activeHeads
+      .filter((head) => relevantTargetKeys.has(policyTargetKey(head)))
+      .sort((left, right) => policyTargetKey(left).localeCompare(policyTargetKey(right)));
+    const snapshotIdentities = snapshotEntries.map(policyIdentity);
+    const currentIdentities = currentEntries.map(policyIdentity);
+    const currentKeys = currentEntries.map(policyTargetKey);
+    policyStatus = classifyIdentityDrift(
+      snapshotIdentities,
+      currentIdentities,
+      snapshotKeys,
+      currentKeys,
+    );
+    policySnapshotHash = hashIdentities(snapshotIdentities);
+    policyCurrentHash = hashIdentities(currentIdentities);
+    policySnapshotTargetCount = snapshotEntries.length;
+    policyCurrentTargetCount = currentEntries.length;
+  }
+
+  const preferenceSnapshot = governance.preferenceSnapshot;
+  const currentPreferences = [...governance.currentPreferences.descriptors].sort((left, right) =>
+    preferenceIdentity(left).localeCompare(preferenceIdentity(right)),
+  );
+  let preferenceStatus: WorkspaceStateGovernanceDriftStatus = "missing";
+  let preferenceSnapshotHash: string | null = null;
+  const currentPreferenceIdentities = currentPreferences.map(preferenceIdentity);
+  const currentPreferenceHash = hashIdentities(currentPreferenceIdentities);
+  let snapshotPreferenceCount = 0;
+  let snapshotPreferenceTruncated = false;
+  if (preferenceSnapshot) {
+    const snapshotPreferences = [...preferenceSnapshot.descriptors].sort((left, right) =>
+      preferenceIdentity(left).localeCompare(preferenceIdentity(right)),
+    );
+    const snapshotPreferenceIdentities = snapshotPreferences.map(preferenceIdentity);
+    const snapshotPreferenceKeys = snapshotPreferences.map((descriptor) => descriptor.id).sort();
+    const currentPreferenceKeys = currentPreferences.map((descriptor) => descriptor.id).sort();
+    preferenceSnapshotHash = hashIdentities(snapshotPreferenceIdentities);
+    snapshotPreferenceCount = snapshotPreferences.length;
+    snapshotPreferenceTruncated = preferenceSnapshot.truncated;
+    preferenceStatus =
+      preferenceSnapshot.truncated || governance.currentPreferences.truncated
+        ? "truncated"
+        : classifyIdentityDrift(
+            snapshotPreferenceIdentities,
+            currentPreferenceIdentities,
+            snapshotPreferenceKeys,
+            currentPreferenceKeys,
+          );
+  }
+
+  return {
+    status: "available" as const,
+    attemptId: governance.attemptId,
+    executionGeneration: governance.executionGeneration,
+    acceptedAt: governance.acceptedAt,
+    policySnapshot: policySnapshot
+      ? {
+          status: "available" as const,
+          id: policySnapshot.id,
+          createdAt: policySnapshot.createdAt,
+          entryHash: policySnapshot.entryHash,
+          policyRole: policySnapshot.policyRole,
+          roleSource: policySnapshot.roleSource,
+          entries: policySnapshot.entries,
+        }
+      : { status: "missing" as const },
+    preferenceSnapshot: preferenceSnapshot
+      ? {
+          status: "available" as const,
+          id: preferenceSnapshot.id,
+          createdAt: preferenceSnapshot.createdAt,
+          descriptorHash: preferenceSnapshot.descriptorHash,
+          descriptorCount: preferenceSnapshot.descriptors.length,
+          truncated: preferenceSnapshot.truncated,
+        }
+      : { status: "missing" as const },
+    drift: {
+      overall: overallDriftStatus(policyStatus, preferenceStatus),
+      policy: {
+        status: policyStatus,
+        snapshotHash: policySnapshotHash,
+        currentHash: policyCurrentHash,
+        snapshotTargetCount: policySnapshotTargetCount,
+        currentTargetCount: policyCurrentTargetCount,
+      },
+      preferences: {
+        status: preferenceStatus,
+        snapshotHash: preferenceSnapshotHash,
+        currentHash: currentPreferenceHash,
+        snapshotDescriptorCount: snapshotPreferenceCount,
+        currentDescriptorCount: currentPreferences.length,
+        snapshotTruncated: snapshotPreferenceTruncated,
+        currentTruncated: governance.currentPreferences.truncated,
+      },
+    },
+  };
+}
+
 function emptyMemoryStatusCounts(): WorkspaceStateMemoryStatusCounts {
   return Object.fromEntries(
     KnowledgeMemoryStatus.options.map((status) => [status, 0]),
@@ -227,10 +429,7 @@ export function projectWorkspaceState(
     generatedAt: input.generatedAt,
     truth: {
       current: { source: "read_time_projection", capturedAt: input.generatedAt },
-      policySnapshot: {
-        status: "not_captured",
-        reason: "workspace_instruction_policy_snapshot_not_implemented",
-      },
+      attemptGovernance: attemptGovernanceProjection(input),
     },
     policy: policyProjection(input),
     knowledge: input.knowledge