@opengeni/core 0.21.10 → 0.24.1

package/src/domain/company-profile-durable-learning-adapter.ts

@@ -0,0 +1,221 @@
+import {
+  CompanyProfileLearningSubjectKind,
+  CompanyProfileLearningWrite,
+  type CompanyProfileMutationResponse,
+} from "@opengeni/contracts";
+import {
+  type CompanyProfileLearningWriteResult,
+  type Database,
+  rollbackCompanyProfileLearning,
+  writeCompanyProfileLearning,
+} from "@opengeni/db";
+
+export type CompanyProfileDurableLearningResource = {
+  surface: "company_profile";
+  id: string;
+  version: string | null;
+  status: string;
+};
+
+export type CompanyProfileDurableLearningWriteResult = {
+  outcome: "applied" | "proposed";
+  resource: CompanyProfileDurableLearningResource;
+  effectiveBoundary: "next_accepted_attempt";
+  rollback: {
+    supported: boolean;
+    targetAttemptId: null;
+    token: string | null;
+  };
+};
+
+export type CompanyProfileDurableLearningRollbackResult = {
+  resource: CompanyProfileDurableLearningResource;
+  effectiveBoundary: "next_accepted_attempt";
+};
+
+/**
+ * Structural match for canonical durable-learning router's DurableLearningAuthorityAdapter. The router
+ * package owns its complete request/decision types; accepting unknown here
+ * keeps this adapter assignable without copying or competing with that router.
+ */
+export type CompanyProfileDurableLearningAuthorityAdapter = {
+  write: (input: unknown) => Promise<CompanyProfileDurableLearningWriteResult>;
+  rollback: (input: unknown) => Promise<CompanyProfileDurableLearningRollbackResult>;
+};
+
+export type CompanyProfileDurableLearningAdapterOptions = {
+  db: Database;
+  authority?: {
+    write: typeof writeCompanyProfileLearning;
+    rollback: typeof rollbackCompanyProfileLearning;
+  };
+};
+
+function record(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function nullableString(value: unknown, name: string): string | null {
+  if (value === null) return null;
+  return requiredString(value, name);
+}
+
+function actorKind(value: unknown): "human" | "agent" | "service" {
+  if (value === "human" || value === "agent" || value === "service") return value;
+  throw new Error("durable-learning attempt actor kind is invalid");
+}
+
+function parseAttempt(value: unknown) {
+  const attempt = record(value, "durable-learning attempt");
+  const actor = record(attempt.actor, "durable-learning actor");
+  return {
+    id: requiredString(attempt.id, "durable-learning attempt id"),
+    accountId: requiredString(attempt.accountId, "durable-learning account id"),
+    workspaceId: requiredString(attempt.workspaceId, "durable-learning workspace id"),
+    actor: {
+      kind: actorKind(actor.kind),
+      subjectId: requiredString(actor.subjectId, "durable-learning actor subject"),
+    },
+  };
+}
+
+function parseWriteInput(value: unknown) {
+  const input = record(value, "company-profile durable-learning write");
+  const attempt = parseAttempt(input.attempt);
+  const request = record(input.request, "durable-learning write request");
+  const decision = record(input.decision, "durable-learning route decision");
+  const scope = record(decision.scope, "durable-learning resolved scope");
+  const subject = record(request.subject, "durable-learning subject");
+  if (
+    request.operation !== "write" ||
+    request.attemptId !== attempt.id ||
+    request.targetSurface !== "company_profile" ||
+    decision.disposition !== "route" ||
+    decision.destination !== "company_profile" ||
+    scope.kind !== "organization" ||
+    (decision.authority !== "active" && decision.authority !== "proposal")
+  ) {
+    throw new Error(
+      "The company-profile adapter accepts only matching routed active or proposal organization company_profile writes",
+    );
+  }
+  return CompanyProfileLearningWrite.parse({
+    operationId: attempt.id,
+    accountId: attempt.accountId,
+    workspaceId: attempt.workspaceId,
+    actorSubjectId: attempt.actor.subjectId,
+    actorKind: attempt.actor.kind,
+    authority: decision.authority,
+    subject: {
+      kind: CompanyProfileLearningSubjectKind.parse(subject.kind),
+      content: requiredString(subject.content, "durable-learning subject content"),
+      stableKey: nullableString(subject.stableKey, "durable-learning subject stable key"),
+    },
+    sourceId: `durable-learning-attempt:${attempt.id}`,
+  });
+}
+
+function parseRollbackInput(value: unknown) {
+  const input = record(value, "company-profile durable-learning rollback");
+  const attempt = parseAttempt(input.attempt);
+  const targetAttempt = parseAttempt(input.targetAttempt);
+  const targetReceipt = record(input.targetReceipt, "durable-learning target receipt");
+  const targetResource = record(
+    targetReceipt.resource,
+    "durable-learning target company-profile resource",
+  );
+  const receiptRollback = record(
+    targetReceipt.rollback,
+    "durable-learning target rollback receipt",
+  );
+  const rollbackToken = requiredString(input.rollbackToken, "company-profile rollback token");
+  if (
+    targetReceipt.attemptId !== targetAttempt.id ||
+    targetResource.surface !== "company_profile" ||
+    receiptRollback.supported !== true ||
+    receiptRollback.token !== rollbackToken
+  ) {
+    throw new Error("The company-profile adapter cannot roll back another authority surface");
+  }
+  return {
+    attempt,
+    rollbackToken,
+    reason: requiredString(input.reason, "company-profile rollback reason"),
+  };
+}
+
+function writeResource(
+  result: CompanyProfileLearningWriteResult,
+): CompanyProfileDurableLearningResource {
+  return {
+    surface: "company_profile",
+    id: result.revision.id,
+    version: String(result.revision.revision),
+    status: result.outcome === "applied" ? "active" : "proposal",
+  };
+}
+
+function rollbackResource(
+  result: CompanyProfileMutationResponse,
+): CompanyProfileDurableLearningResource {
+  if (!result.event) throw new Error("Company-profile rollback returned no activation event");
+  return {
+    surface: "company_profile",
+    id: result.head?.revisionId ?? result.event.oldRevision?.id ?? result.event.id,
+    version: String(result.event.activationVersion),
+    status: result.head ? "active" : "inactive",
+  };
+}
+
+/** Install this under `authorities.company_profile` in the canonical durable-learning router ports. */
+export function createCompanyProfileDurableLearningAdapter(
+  options: CompanyProfileDurableLearningAdapterOptions,
+): CompanyProfileDurableLearningAuthorityAdapter {
+  const authority = options.authority ?? {
+    write: writeCompanyProfileLearning,
+    rollback: rollbackCompanyProfileLearning,
+  };
+  return {
+    async write(rawInput) {
+      const input = parseWriteInput(rawInput);
+      const result = await authority.write(options.db, input);
+      return {
+        outcome: result.outcome,
+        resource: writeResource(result),
+        effectiveBoundary: result.effectiveBoundary,
+        rollback: {
+          supported: result.rollbackToken !== null,
+          targetAttemptId: null,
+          token: result.rollbackToken,
+        },
+      };
+    },
+
+    async rollback(rawInput) {
+      const input = parseRollbackInput(rawInput);
+      const result = await authority.rollback(options.db, {
+        operationId: input.attempt.id,
+        accountId: input.attempt.accountId,
+        workspaceId: input.attempt.workspaceId,
+        actorSubjectId: input.attempt.actor.subjectId,
+        actorKind: input.attempt.actor.kind,
+        token: input.rollbackToken,
+        reason: input.reason,
+      });
+      return {
+        resource: rollbackResource(result),
+        effectiveBoundary: "next_accepted_attempt",
+      };
+    },
+  };
+}

package/src/domain/durable-learning-slack-publication.ts

@@ -0,0 +1,202 @@
+import {
+  enqueueMemorySlackPublication,
+  getCurrentMemorySlackPublicationConfiguration,
+  type Database,
+  type EnqueueMemorySlackPublicationResult,
+} from "@opengeni/db";
+import { sanitizeSlackPublicationText } from "./slack-publication-secret-safety";
+
+/**
+ * Narrow post-persistence port for the immutable durable-learning v1 attempt/receipt contract.
+ * The router owns validation, authority, routing, and persistence. This adapter
+ * consumes only the fields required to create a bounded notification projection.
+ */
+export type DurableLearningSlackOutcome = {
+  attempt: {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    inputHash: string;
+    actor: { kind: "human" | "agent" | "service"; subjectId: string };
+    initiatingHumanSubjectId: string | null;
+    sessionId: string | null;
+    request:
+      | {
+          operation: "write";
+          subject: {
+            kind: string;
+            summary: string | null;
+          };
+          evidence: Array<{ kind: string }>;
+        }
+      | {
+          operation: "rollback";
+          targetAttemptId: string;
+        };
+  };
+  receipt: {
+    attemptId: string;
+    inputHash: string;
+    outcome:
+      | "applied"
+      | "proposed"
+      | "evidence_recorded"
+      | "noop"
+      | "clarification_required"
+      | "rejected"
+      | "rolled_back"
+      | "failed";
+    decision: {
+      code: string;
+      destination: string | null;
+      scope: { kind: string } | null;
+      authority: string | null;
+    };
+    resource: {
+      surface: string;
+      id: string;
+      version: string | null;
+      status: string;
+    } | null;
+    createdAt: string;
+  };
+};
+
+export type DurableLearningSlackPublicationResult =
+  | {
+      kind:
+        | "contract_mismatch"
+        | "not_workspace_scoped"
+        | "connector_evidence_untrusted"
+        | "summary_required"
+        | "policy_quiet";
+      enqueue: null;
+    }
+  | { kind: "enqueued"; enqueue: EnqueueMemorySlackPublicationResult };
+
+export type DurableLearningSlackProjection = {
+  summary: string;
+  outcome: DurableLearningSlackOutcome["receipt"]["outcome"];
+  decisionCode: string;
+  destination: string | null;
+  authority: string | null;
+  resource: DurableLearningSlackOutcome["receipt"]["resource"];
+  occurredAt: string;
+};
+
+export async function publishDurableLearningOutcomeToSlack(
+  db: Database,
+  outcome: DurableLearningSlackOutcome,
+): Promise<DurableLearningSlackPublicationResult> {
+  const { attempt, receipt } = outcome;
+  if (attempt.id !== receipt.attemptId || attempt.inputHash !== receipt.inputHash) {
+    return { kind: "contract_mismatch", enqueue: null };
+  }
+  if (receipt.decision.scope?.kind !== "workspace") {
+    return { kind: "not_workspace_scoped", enqueue: null };
+  }
+  if (
+    attempt.request.operation === "write" &&
+    attempt.request.evidence.some((evidence) => evidence.kind === "connector")
+  ) {
+    // The v1 router contract intentionally does not identify connector providers.
+    // Fail closed rather than risk republishing a Slack-derived learning outcome.
+    return { kind: "connector_evidence_untrusted", enqueue: null };
+  }
+
+  const projection = durableLearningSlackProjection(outcome);
+  if (!projection) return { kind: "summary_required", enqueue: null };
+  const importance = durableLearningImportance(outcome);
+  const configuration = await getCurrentMemorySlackPublicationConfiguration(
+    db,
+    attempt.workspaceId,
+  );
+  const deliveryMode = configuration?.autoImportances.includes(importance)
+    ? "auto"
+    : configuration?.reviewImportances.includes(importance)
+      ? "review"
+      : null;
+  if (!configuration?.enabled || !deliveryMode) {
+    return { kind: "policy_quiet", enqueue: null };
+  }
+
+  const enqueue = await enqueueMemorySlackPublication(db, {
+    accountId: attempt.accountId,
+    workspaceId: attempt.workspaceId,
+    sourceType: "durable_learning",
+    sourceId: receipt.attemptId,
+    sourceVersion: receipt.inputHash,
+    sourceIdempotencyKey: `durable-learning:${receipt.attemptId}`,
+    projection,
+    importance,
+    deliveryMode,
+    actor: {
+      kind: attempt.actor.kind,
+      subjectId: attempt.actor.subjectId,
+      initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
+      sessionId: attempt.sessionId,
+      attemptId: attempt.id,
+    },
+  });
+  return { kind: "enqueued", enqueue };
+}
+
+export function durableLearningImportance(
+  outcome: DurableLearningSlackOutcome,
+): "major" | "normal" | "minor" {
+  if (outcome.receipt.outcome === "failed" || outcome.receipt.outcome === "rolled_back") {
+    return "major";
+  }
+  if (outcome.receipt.outcome === "noop" || outcome.receipt.outcome === "clarification_required") {
+    return "minor";
+  }
+  if (
+    outcome.attempt.request.operation === "write" &&
+    ["decision", "workspace_charter", "mandatory_operating_context", "workspace_goal"].includes(
+      outcome.attempt.request.subject.kind,
+    )
+  ) {
+    return "major";
+  }
+  return "normal";
+}
+
+export function durableLearningSlackProjection(
+  outcome: DurableLearningSlackOutcome,
+): DurableLearningSlackProjection | null {
+  const summary = durableLearningSummary(outcome);
+  if (!summary) return null;
+  return {
+    summary,
+    outcome: outcome.receipt.outcome,
+    decisionCode: outcome.receipt.decision.code,
+    destination: boundedSlackPublicationText(outcome.receipt.decision.destination, 128),
+    authority: outcome.receipt.decision.authority,
+    resource: outcome.receipt.resource
+      ? {
+          surface: outcome.receipt.resource.surface,
+          id: outcome.receipt.resource.id,
+          version: outcome.receipt.resource.version,
+          status: outcome.receipt.resource.status,
+        }
+      : null,
+    occurredAt: outcome.receipt.createdAt,
+  };
+}
+
+function durableLearningSummary(outcome: DurableLearningSlackOutcome): string | null {
+  if (outcome.attempt.request.operation === "rollback") {
+    const destination =
+      boundedSlackPublicationText(outcome.receipt.decision.destination, 128) ??
+      "governed knowledge";
+    return `Rolled back a durable learning change for ${destination}.`;
+  }
+  const summary = outcome.attempt.request.subject.summary?.replace(/\s+/g, " ").trim();
+  return summary ? sanitizeSlackPublicationText(summary).slice(0, 512) : null;
+}
+
+function boundedSlackPublicationText(value: string | null, maxChars: number): string | null {
+  if (!value) return null;
+  const sanitized = sanitizeSlackPublicationText(value.replace(/\s+/g, " ").trim());
+  return sanitized ? sanitized.slice(0, maxChars) : null;
+}