@openplanr/protocol 0.2.0

package/lib/dashboard/operate-experience-surface-contract.d.mts

@@ -0,0 +1,157 @@
+import type {
+	JsonValue,
+	OperateExperienceAccessLevelV1,
+	OperateExperienceAttentionV1,
+	OperateExperienceCycleV1,
+	OperateExperienceDomainMetricV1,
+	OperateExperienceEventHeadV1,
+	OperateExperienceInboxItemV1,
+	OperateExperienceActionV1,
+	OperateExperienceOutcomeV1,
+	OperateExperienceLearningV1,
+	OperateExperienceEvidenceV1,
+	OperateExperienceClaimV1,
+	OperateExperienceRationaleV1,
+	OperateExperienceHistoryV1,
+	OperateExperienceReplayV1,
+	OperateExperienceViewV1,
+	ProtocolValidationError,
+} from "../protocol/index.js";
+import type { OperateSharedTruthSummaryV1 } from "./operate-review-workspace-projection-v2.mjs";
+
+export type OperateExperienceSurfaceStatusV1 =
+	OperateExperienceViewV1["status"];
+export interface OperateExperienceSurfaceBaseV1 {
+	ok: true;
+	kind: "operate-experience-surface";
+	schemaVersion: "1.0.0";
+	protocolVersion: "2.0.0";
+	surface:
+		| "today"
+		| "inbox"
+		| "cycles"
+		| "cycle"
+		| "actions"
+		| "action"
+		| "evidence"
+		| "outcomes"
+		| "outcome"
+		| "history"
+		| "search"
+		| "export";
+	readOnly: true;
+	mutationEnabled: boolean;
+	scopeId: string;
+	domainId: string;
+	domainVersion: string;
+	actorId: string;
+	accessLevel: OperateExperienceAccessLevelV1;
+	generatedAt: string;
+	eventHead: OperateExperienceEventHeadV1;
+	viewHash: string;
+	truthSummary: OperateSharedTruthSummaryV1;
+	status: OperateExperienceSurfaceStatusV1;
+	reasonCodes: string[];
+}
+export type OperateExperienceTodaySurfaceV1 = OperateExperienceSurfaceBaseV1 & {
+	surface: "today";
+	data: {
+		attention: OperateExperienceAttentionV1[];
+		domainMetrics: OperateExperienceDomainMetricV1[];
+		activeCycle: OperateExperienceCycleV1 | null;
+		inbox: OperateExperienceInboxItemV1[];
+		actions: OperateExperienceActionV1[];
+		outcomes: OperateExperienceOutcomeV1[];
+		allowedActions: OperateExperienceViewV1["allowedActions"];
+	};
+};
+export type OperateExperienceSurfaceV1 = OperateExperienceSurfaceBaseV1 &
+	(
+		| { surface: "today"; data: OperateExperienceTodaySurfaceV1["data"] }
+		| {
+				surface: "inbox";
+				data: {
+					inbox: OperateExperienceInboxItemV1[];
+					requestBinding: {
+						projectId: string;
+						generation: number;
+						subjectId: string | null;
+					};
+				};
+		  }
+		| { surface: "cycles"; data: { cycles: OperateExperienceCycleV1[] } }
+		| { surface: "cycle"; data: { cycle: OperateExperienceCycleV1 } }
+		| {
+				surface: "actions";
+				data: {
+					actions: OperateExperienceActionV1[];
+					requestBinding: { projectId: string; generation: number };
+				};
+		  }
+		| {
+				surface: "action";
+				data: {
+					action: OperateExperienceActionV1;
+				};
+		  }
+		| {
+				surface: "evidence";
+				data: {
+					evidence: OperateExperienceEvidenceV1[];
+					claims: OperateExperienceClaimV1[];
+					rationale: OperateExperienceRationaleV1[];
+				};
+		  }
+		| {
+				surface: "outcomes";
+				data: {
+					domainMetrics: OperateExperienceDomainMetricV1[];
+					outcomes: OperateExperienceOutcomeV1[];
+					learnings: OperateExperienceLearningV1[];
+				};
+		  }
+		| {
+				surface: "outcome";
+				data: {
+					outcome: OperateExperienceOutcomeV1;
+					learnings: OperateExperienceLearningV1[];
+				};
+		  }
+		| {
+				surface: "history";
+				data: {
+					history: OperateExperienceHistoryV1[];
+					replay: OperateExperienceReplayV1;
+				};
+		  }
+		| {
+				surface: "search";
+				data: {
+					query: string;
+					results: Array<{
+						kind: string;
+						subjectId: string;
+						title: string;
+						summary: string;
+						state: string;
+						deepLink?: string;
+					}>;
+				};
+		  }
+		| {
+				surface: "export";
+				data: {
+					format: "json" | "html";
+					mediaType: "application/json" | "text/html; charset=utf-8";
+					content: string;
+				};
+		  }
+	);
+
+export function validateOperateExperienceSurfaceV1(
+	value: unknown,
+): ProtocolValidationError[];
+export function assertOperateExperienceSurfaceV1<T>(value: T): T;
+export const OPERATE_EXPERIENCE_SURFACE_SCHEMA_V1: Readonly<
+	Record<string, JsonValue>
+>;

package/lib/dashboard/operate-experience-surface-contract.mjs

@@ -0,0 +1,91 @@
+import { validateJson } from '../../src/json-schema.mjs';
+import {
+	OPERATE_ALLOWED_ACTION_SCHEMA as allowedActionSchema,
+	OPERATING_DELIVERY_ROUTE_SCHEMA as deliveryRouteSchema,
+	OPERATING_EVIDENCE_RESOLUTION_SCHEMA as evidenceResolutionSchema,
+	OPERATING_EXECUTION_RESULT_SCHEMA as executionResultSchema,
+	OPERATE_EXPERIENCE_VIEW_SCHEMA as experienceViewSchema,
+	OPERATING_FINDING_SCHEMA as findingSchema,
+	OPERATING_GOVERNED_OPERATION_SCHEMA as governedOperationSchema,
+	OPERATING_REVIEW_SCHEMA as reviewSchema,
+	OPERATING_TRACE_MATRIX_SCHEMA as traceMatrixSchema,
+	OPERATE_REVIEW_DISPLAY_WORKSPACE_SCHEMA as reviewWorkspaceSchema,
+	OPERATE_EXPERIENCE_SURFACE_SCHEMA as surfaceSchema,
+} from "./generated/operate-experience-surface-schema-data.mjs";
+
+const schemas = new Map([
+	["operate-experience-view.schema.json", experienceViewSchema],
+	["operating-finding.schema.json", findingSchema],
+	["operate-allowed-action.schema.json", allowedActionSchema],
+	["operating-delivery-route.schema.json", deliveryRouteSchema],
+	["operating-evidence-resolution.schema.json", evidenceResolutionSchema],
+	["operating-execution-result.schema.json", executionResultSchema],
+	["operating-governed-operation.schema.json", governedOperationSchema],
+	["operating-review.schema.json", reviewSchema],
+	["operating-trace-matrix.schema.json", traceMatrixSchema],
+	["operate-review-display-workspace.schema.json", reviewWorkspaceSchema],
+]);
+
+function jsonPointer(root, fragment) {
+	if (!fragment || fragment === "#") return root;
+	if (!fragment.startsWith("#/")) return null;
+	return fragment
+		.slice(2)
+		.split("/")
+		.map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
+		.reduce((value, part) => value?.[part], root);
+}
+
+function resolveSurfaceRef(reference) {
+	const [path, pointer = ""] = reference.split("#");
+	const filename = path.split("/").at(-1);
+	const rootSchema = schemas.get(filename);
+	if (!rootSchema) return null;
+	return {
+		schema: jsonPointer(rootSchema, pointer ? `#${pointer}` : "#"),
+		rootSchema,
+		base: filename,
+	};
+}
+
+export function validateOperateExperienceSurfaceV1(value) {
+	const errors = validateJson(value, surfaceSchema, {
+		base: "schemas/v1.2.0/operate-experience-surface.schema.json",
+		resolveRef: resolveSurfaceRef,
+	});
+	if (errors.length > 0) return errors;
+	const summary = value.truthSummary;
+	if (
+		summary.sourceViewHash !== value.viewHash ||
+		summary.sourceEventHead.sequence !== value.eventHead.sequence ||
+		summary.sourceEventHead.hash !== value.eventHead.hash ||
+		summary.stages.total !== summary.stages.cycles * 7 ||
+		summary.evidence.linked > summary.evidence.total ||
+		summary.proof.linkedEvidence !== summary.evidence.linked ||
+		summary.seats.total !==
+			summary.seats.terminal + summary.seats.active + summary.seats.pending
+	) {
+		return [{
+			path: "$.truthSummary",
+			rule: "sharedTruth",
+			detail: "does not bind one internally consistent shared truth summary",
+		}];
+	}
+	return [];
+}
+
+export function assertOperateExperienceSurfaceV1(value) {
+	const errors = validateOperateExperienceSurfaceV1(value);
+	if (errors.length > 0) {
+		const error = new TypeError(
+			`operate-experience-surface: ${errors[0].path} ${errors[0].detail}`,
+		);
+		error.code = "E_OPERATE_EXPERIENCE_SURFACE_INVALID";
+		throw error;
+	}
+	return value;
+}
+
+export const OPERATE_EXPERIENCE_SURFACE_SCHEMA_V1 = Object.freeze(
+	structuredClone(surfaceSchema),
+);

package/lib/dashboard/operate-review-contract.d.mts

@@ -0,0 +1,34 @@
+import type {
+  OperateReviewBoundSubmissionV1,
+  OperatingReviewReceiptV2,
+} from '../protocol/index.js';
+
+export {
+  assertOperateReviewDisplayWorkspaceV1,
+} from './operate-review-display-workspace-contract.mjs';
+
+export type {
+  OperateReviewDisplayWorkspaceExpectedBindingV1,
+  OperateReviewDisplayWorkspaceIntegrityV1,
+  OperateReviewDisplayWorkspaceV1,
+} from './operate-review-display-workspace-contract.mjs';
+
+export type {
+  OperateReviewBoundSubmissionV1,
+  OperatingReviewReceiptV2,
+};
+
+export const OPERATE_REVIEW_BOUND_SUBMISSION_DOMAIN:
+  'openplanr:operate-review-bound-submission:project-write:operating-review@2.0.0#/$defs/workDisposition:1.0.0';
+
+export function computeOperatingReviewBoundSubmissionHashV1(
+  value: Omit<OperateReviewBoundSubmissionV1, 'boundSubmissionHash'> | OperateReviewBoundSubmissionV1,
+): string;
+
+export function assertOperatingReviewBoundSubmissionV1(
+  value: unknown,
+): OperateReviewBoundSubmissionV1;
+
+export function assertOperatingReviewReceiptV2(
+  value: unknown,
+): OperatingReviewReceiptV2;

package/lib/dashboard/operate-review-contract.mjs

@@ -0,0 +1,175 @@
+import { validateJson } from '../../src/json-schema.mjs';
+import {
+  exactEventHead,
+  exactJson,
+  jcsHash,
+  safeDataClone,
+} from './closed-json-contract.mjs';
+import {
+  OPERATE_REVIEW_BOUND_SUBMISSION_SCHEMA_REVIEW_SLICE as boundSubmissionSchema,
+  OPERATING_ASSIGNMENT_SCHEMA_REVIEW_SLICE as assignmentSchema,
+  OPERATING_REVIEW_READ_SCHEMA_REVIEW_SLICE as reviewReadSchema,
+  OPERATING_REVIEW_RECEIPT_SCHEMA_REVIEW_SLICE as reviewReceiptSchema,
+  OPERATING_REVIEW_SCHEMA_REVIEW_SLICE as reviewSchema,
+} from './generated/operate-review-schema-data.mjs';
+import { assertOperateReviewWorkspacePayloadSafeV1 } from './operate-review-payload-safety.mjs';
+
+export {
+  assertOperateReviewDisplayWorkspaceV1,
+} from './operate-review-display-workspace-contract.mjs';
+
+export const OPERATE_REVIEW_BOUND_SUBMISSION_DOMAIN =
+  'openplanr:operate-review-bound-submission:project-write:operating-review@2.0.0#/$defs/workDisposition:1.0.0';
+
+const schemas = new Map([
+  ['operate-review-bound-submission.schema.json', boundSubmissionSchema],
+  ['operating-assignment.schema.json', assignmentSchema],
+  ['operating-review-read.schema.json', reviewReadSchema],
+  ['operating-review-receipt.schema.json', reviewReceiptSchema],
+  ['operating-review.schema.json', reviewSchema],
+]);
+
+function jsonPointer(root, fragment) {
+  if (!fragment || fragment === '#') return root;
+  if (!fragment.startsWith('#/')) return null;
+  return fragment
+    .slice(2)
+    .split('/')
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .reduce((value, part) => value?.[part], root);
+}
+
+function resolveSchemaRef(reference) {
+  const [path, pointer = ''] = reference.split('#');
+  const filename = path.split('/').at(-1);
+  const rootSchema = schemas.get(filename);
+  if (!rootSchema) return null;
+  return {
+    schema: jsonPointer(rootSchema, pointer ? `#${pointer}` : '#'),
+    rootSchema,
+    base: filename,
+  };
+}
+
+function fail(code, message) {
+  const error = new TypeError(message);
+  error.code = code;
+  throw error;
+}
+
+function assertClosedSchema(value, schema, base, code, message) {
+  let clone;
+  try {
+    clone = safeDataClone(value);
+    const errors = validateJson(clone, schema, { base, resolveRef: resolveSchemaRef });
+    if (errors.length > 0) fail(code, message);
+  } catch (error) {
+    if (error?.code === code) throw error;
+    fail(code, message);
+  }
+  return clone;
+}
+
+function boundSubmissionHashPayload(value) {
+  return {
+    domain: OPERATE_REVIEW_BOUND_SUBMISSION_DOMAIN,
+    expectedReadEventHead: value.expectedReadEventHead,
+    choiceId: value.choiceId,
+    choiceHash: value.choiceHash,
+    submitArguments: value.submitArguments,
+    note: value.note,
+  };
+}
+
+export function computeOperatingReviewBoundSubmissionHashV1(value) {
+  return jcsHash(boundSubmissionHashPayload(safeDataClone(value)));
+}
+
+export function assertOperatingReviewBoundSubmissionV1(value) {
+  const candidate = assertClosedSchema(
+    value,
+    boundSubmissionSchema,
+    'schemas/v2.0.0/operate-review-bound-submission.schema.json',
+    'RESULT_CONTRACT_INVALID',
+    'The bound Review submission does not satisfy its closed integrity contract.',
+  );
+  if (candidate.choiceHash !== jcsHash(candidate.submitArguments)
+    || candidate.boundSubmissionHash !== computeOperatingReviewBoundSubmissionHashV1(candidate)) {
+    fail(
+      'RESULT_CONTRACT_INVALID',
+      'The bound Review submission does not satisfy its closed integrity contract.',
+    );
+  }
+  return value;
+}
+
+function exactChoiceBinding(choice, receipt) {
+  return choice.choiceHash === jcsHash(choice.submitArguments)
+    && choice.submitArguments.reviewId === receipt.review.reviewId
+    && choice.submitArguments.cycleId === receipt.cycleId
+    && exactJson(choice.submitArguments.actor, receipt.actor)
+    && exactJson(choice.submitArguments.scope, receipt.scope);
+}
+
+function exactReceiptSemantics(receipt) {
+  const choices = receipt.dispositionChoices;
+  const choiceIds = new Set(choices.map(({ choiceId }) => choiceId));
+  const choiceHashes = new Set(choices.map(({ choiceHash }) => choiceHash));
+  if (choiceIds.size !== choices.length
+    || choiceHashes.size !== choices.length
+    || choices.some((choice) => !exactChoiceBinding(choice, receipt))
+    || receipt.review.reviewId.length === 0
+    || receipt.review.cycleId !== receipt.cycleId
+    || receipt.review.ownerActorId !== receipt.actor.actorId
+    || receipt.review.state !== receipt.decision
+    || receipt.review.disposition !== receipt.decision
+    || !exactJson(receipt.review.workDispositions, receipt.appliedWorkDispositions)
+    || receipt.eventHead.sequence !== receipt.readEventHead.sequence + 1) {
+    return false;
+  }
+
+  const applied = choices.filter((choice) => (
+    choice.choiceId === receipt.appliedChoiceId
+    && choice.choiceHash === receipt.appliedChoiceHash
+  ));
+  if (applied.length !== 1) return false;
+  const [choice] = applied;
+  if (choice.submitArguments.disposition !== receipt.decision
+    || !exactJson(choice.submitArguments.workDispositions, receipt.appliedWorkDispositions)
+    || receipt.summary.decisionCount !== receipt.decisions.length
+    || receipt.summary.actionCount !== receipt.actions.length
+    || receipt.summary.findingCount !== receipt.findings.length
+    || receipt.summary.dissentCount !== receipt.dissent.length
+    || receipt.summary.gapCount !== receipt.gaps.length) {
+    return false;
+  }
+
+  if (receipt.boundSubmission === undefined) return true;
+  try {
+    assertOperatingReviewBoundSubmissionV1(receipt.boundSubmission);
+  } catch {
+    return false;
+  }
+  return exactEventHead(receipt.boundSubmission.expectedReadEventHead, receipt.readEventHead)
+    && receipt.boundSubmission.choiceId === choice.choiceId
+    && receipt.boundSubmission.choiceHash === choice.choiceHash
+    && exactJson(receipt.boundSubmission.submitArguments, choice.submitArguments);
+}
+
+export function assertOperatingReviewReceiptV2(value) {
+  const candidate = assertClosedSchema(
+    value,
+    reviewReceiptSchema,
+    'schemas/v2.0.0/operating-review-receipt.schema.json',
+    'E_OPERATE_REVIEW_RECEIPT_INVALID',
+    'The operating Review receipt does not satisfy its closed integrity contract.',
+  );
+  assertOperateReviewWorkspacePayloadSafeV1(candidate);
+  if (!exactReceiptSemantics(candidate)) {
+    fail(
+      'E_OPERATE_REVIEW_RECEIPT_INVALID',
+      'The operating Review receipt does not satisfy its closed integrity contract.',
+    );
+  }
+  return value;
+}

package/lib/dashboard/operate-review-display-workspace-contract.d.mts

@@ -0,0 +1,54 @@
+import type { JsonValue, ProtocolValidationError } from '../protocol/index.js';
+import type { OperateReviewWorkspacePayloadV1 } from './operate-review-workspace-projection-v2.mjs';
+
+export const OPERATE_REVIEW_DISPLAY_WORKSPACE_DOMAIN:
+  'openplanr:operate-review-display-workspace:1.0.0';
+
+export type OperateReviewDisplayWorkspaceIntegrityV1 = Readonly<{
+  algorithm: 'sha-256-jcs';
+  domain: typeof OPERATE_REVIEW_DISPLAY_WORKSPACE_DOMAIN;
+  sourceArtifactKind: OperateReviewWorkspacePayloadV1['sourceArtifactKind'];
+  sourceViewHash: string;
+  sourceArtifactHash: string;
+  contentHash: string;
+}>;
+
+export type OperateReviewDisplayWorkspaceV1 = Readonly<{
+  kind: 'operate-review-display-workspace';
+  schemaVersion: '1.0.0';
+  protocolVersion: '2.0.0';
+  payload: OperateReviewWorkspacePayloadV1;
+  integrity: OperateReviewDisplayWorkspaceIntegrityV1;
+}>;
+
+export type OperateReviewDisplayWorkspaceExpectedBindingV1 = Readonly<{
+  actorId: string;
+  scopeId: string;
+  domainId: string;
+  domainVersion: string;
+  cycleId: string;
+  reviewId: string;
+  sourceArtifactKind: OperateReviewWorkspacePayloadV1['sourceArtifactKind'];
+  sourceArtifactHash: string;
+  sourceEventHead: OperateReviewWorkspacePayloadV1['sourceEventHead'];
+  sourceReadEventHead: OperateReviewWorkspacePayloadV1['sourceReadEventHead'];
+  sourceViewHash: string;
+}>;
+
+export function validateOperateReviewDisplayWorkspaceV1(
+  value: unknown,
+  expected?: OperateReviewDisplayWorkspaceExpectedBindingV1,
+): ProtocolValidationError[];
+
+export function assertOperateReviewDisplayWorkspaceV1<T>(
+  value: T,
+  expected?: OperateReviewDisplayWorkspaceExpectedBindingV1,
+): T;
+
+export function issueOperateReviewDisplayWorkspaceV1(
+  payload: OperateReviewWorkspacePayloadV1,
+): OperateReviewDisplayWorkspaceV1;
+
+export const OPERATE_REVIEW_DISPLAY_WORKSPACE_SCHEMA_V1: Readonly<
+  Record<string, JsonValue>
+>;