@openplanr/protocol 0.2.0

package/src/compat/operate-experience-live-patch.mjs

@@ -0,0 +1,66 @@
+/**
+ * The Operate experience live patch, with no Operate runtime dependency.
+ *
+ * The dashboard server needs this one builder. Importing it from the projection module put the
+ * package root on the Operate runtime, so it lives here instead. The private helpers are copied
+ * rather than shared: the projection module has 111 `fail` and 46 `clone` call sites, and these
+ * duplicates are meant to die with it.
+ */
+import { PipelineError } from '../errors.mjs';
+import { assertOperateExperienceArtifactV2 } from '../contracts.mjs';
+import { sha256Jcs } from '../canonical-json.mjs';
+
+const PROTOCOL_VERSION = '2.0.0';
+
+
+
+function fail(code, message, context = {}) {
+  throw new PipelineError(code, message, '', { retryable: false, context });
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const nested of Object.values(value)) freeze(nested);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function without(value, field) {
+  return Object.fromEntries(Object.entries(value).filter(([key]) => key !== field));
+}
+
+function stableId(prefix, value) {
+  return `${prefix}_${sha256Jcs(value).slice('sha256:'.length, 'sha256:'.length + 32)}`;
+}
+
+function assertCanonicalView(view) {
+  assertOperateExperienceArtifactV2('operate-experience-view', view);
+  if (view.viewHash !== sha256Jcs(without(view, 'viewHash'))) fail('E_OPERATE_BINDING_MISMATCH', 'Experience viewHash does not equal its canonical content.');
+  return view;
+}
+
+function validInstant(value, field) {
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) fail('RESULT_CONTRACT_INVALID', `${field} must be an RFC 3339 instant.`);
+  return value;
+}
+
+export function buildOperateExperienceLivePatchV2(previous, next, { createdAt = next?.generatedAt } = {}) {
+  assertCanonicalView(previous); assertCanonicalView(next);
+  for (const field of ['scopeId', 'domainId', 'domainVersion', 'actorId', 'accessLevel']) if (previous[field] !== next[field]) fail('E_OPERATE_BINDING_MISMATCH', `Live patch binding changed at ${field}.`);
+  if (next.eventHead.sequence !== previous.eventHead.sequence + 1
+    || (previous.eventHead.sequence > 0 && next.eventHead.hash === previous.eventHead.hash)) {
+    fail('STATE_TRANSITION_INVALID', 'Live patch requires one exact contiguous, non-forking Event-head advance.');
+  }
+  validInstant(createdAt, 'createdAt');
+  const paths = ['status', 'attention', 'domainMetrics', 'cycles', 'inbox', 'actions', 'evidence', 'claims', 'rationale', 'outcomes', 'learnings', 'history', 'replay', 'allowedActions', 'omissions', 'export'];
+  const operations = paths.filter((path) => sha256Jcs(previous[path]) !== sha256Jcs(next[path])).map((path) => ({ op: 'replace', path: `/${path}`, valueHash: sha256Jcs(next[path]), value: clone(next[path]) }));
+  const base = { kind: 'operate-experience-live-patch', schemaVersion: '1.0.0', protocolVersion: PROTOCOL_VERSION, patchId: stableId('xpatch', { from: previous.viewHash, to: next.viewHash }), scopeId: next.scopeId, domainId: next.domainId, domainVersion: next.domainVersion, actorId: next.actorId, fromEventHead: clone(previous.eventHead), toEventHead: clone(next.eventHead), fromViewHash: previous.viewHash, toViewHash: next.viewHash, operations, createdAt };
+  const patch = { ...base, patchHash: sha256Jcs(base) };
+  assertOperateExperienceArtifactV2('operate-experience-live-patch', patch);
+  return freeze(patch);
+}

package/src/compat/operating-planning-contracts.mjs

@@ -0,0 +1,114 @@
+/**
+ * Planning-bridge contracts with no Operate runtime dependency.
+ *
+ * These assertions are needed by the protocol loader and the pipeline's origin reader, neither of
+ * which should reach into the Operate runtime to get them. The Operate side imports them back.
+ */
+import { PipelineError } from '../errors.mjs';
+import { assertOperateExperienceArtifactV2 } from '../contracts.mjs';
+import { sha256Jcs } from '../canonical-json.mjs';
+
+const PROTOCOL_VERSION = '2.0.0';
+
+const FORBIDDEN_KEY = /(?:hidden|chain[-_]?of[-_]?thought|reasoning|raw[-_]?prompt|credential|secret|token|private[-_]?path|rejected[-_]?advice)/iu;
+const FORBIDDEN_TEXT = /(?:\/Users\/|\/home\/|[A-Za-z]:\\|-----BEGIN [A-Z ]+PRIVATE KEY-----|\b(?:api[-_]?key|access[-_]?token|password)\b\s*[:=])/iu;
+
+function fail(code, message, context = {}) {
+  throw new PipelineError(code, message, '', { retryable: false, context });
+}
+
+function without(value, field) { return Object.fromEntries(Object.entries(value).filter(([key]) => key !== field)); }
+
+function sameScope(value, scope) { return Boolean(scope) && value?.scopeId === scope.scopeId && value?.domainId === scope.domainId && value?.domainVersion === scope.domainVersion; }
+function sameHead(left, right) { return left?.sequence === right?.sequence && left?.hash === right?.hash; }
+
+function assertNoSensitiveContext(value, path = '$') {
+  if (typeof value === 'string' && FORBIDDEN_TEXT.test(value)) fail('EVIDENCE_ACCESS_DENIED', `Access-safe planning context contains prohibited private material at ${path}.`);
+  if (!value || typeof value !== 'object') return;
+  for (const [key, nested] of Object.entries(value)) {
+    if (FORBIDDEN_KEY.test(key)) fail('EVIDENCE_ACCESS_DENIED', `Access-safe planning context contains prohibited field ${path}.${key}.`);
+    assertNoSensitiveContext(nested, `${path}.${key}`);
+  }
+}
+
+export function assertOperatingPlanningProposalV1(proposal) {
+  assertOperateExperienceArtifactV2('operating-planning-proposal', proposal);
+  assertNoSensitiveContext(proposal);
+  if (proposal.proposalHash !== sha256Jcs(without(proposal, 'proposalHash'))) fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal hash does not equal its canonical content.');
+  const route = proposal.deliveryRoute;
+  if (!sameScope(route, proposal) || !sameHead(route.eventHead, proposal.eventHead)
+    || route.action.actionId !== proposal.action.actionId || route.action.revision !== proposal.action.revision
+    || route.action.actionHash !== proposal.action.actionHash || route.routeHash !== sha256Jcs(without(route, 'routeHash'))) {
+    fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal delivery route does not bind its exact scope, Action, and Event head.');
+  }
+  const chair = proposal.acceptedPerspectiveSummaries.filter(({ roleKind }) => roleKind === 'chair');
+  const challenger = proposal.acceptedPerspectiveSummaries.filter(({ roleKind }) => roleKind === 'challenger');
+  const advisors = proposal.acceptedPerspectiveSummaries.filter(({ roleKind }) => roleKind === 'advisor');
+  const normative = proposal.acceptedPerspectiveSummaries.filter(({ normative: isNormative }) => isNormative);
+  if (chair.length !== 1 || challenger.length !== 1 || advisors.length < 1 || normative.length !== 1 || normative[0] !== chair[0]
+    || chair[0].stance !== 'synthesis' || chair[0].artifactId !== proposal.decision.sourceArtifactId
+    || proposal.action.sourceArtifactId !== proposal.decision.sourceArtifactId || chair[0].summary !== proposal.decision.rationale
+    || proposal.acceptedPerspectiveSummaries.some((perspective) => perspective.roleVersion !== PROTOCOL_VERSION)) {
+    fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal requires exact advisor/Challenger context and exactly one normative Chair synthesis equal to the Decision rationale.');
+  }
+  const decisionEvidenceIds = [...proposal.decision.evidenceRefIds].sort();
+  const projectedEvidenceIds = proposal.evidence.map(({ evidenceRefId }) => evidenceRefId).sort();
+  if (new Set(projectedEvidenceIds).size !== projectedEvidenceIds.length || sha256Jcs(decisionEvidenceIds) !== sha256Jcs(projectedEvidenceIds)
+    || proposal.evidence.some((entry) => entry.accessState === 'restricted' ? entry.summary !== null : typeof entry.summary !== 'string')) {
+    fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal evidence does not equal the exact access-safe Decision evidence set.');
+  }
+  if (proposal.metric.metricId !== proposal.action.metricId || proposal.verification.metricId !== proposal.metric.metricId
+    || proposal.verification.metricHash !== proposal.metric.metricHash || proposal.verification.verificationPlanId !== proposal.action.verificationPlanId) fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal metric and verification identities are not exact.');
+  if (proposal.preview.digest !== sha256Jcs({ proposalId: proposal.proposalId, correlationId: proposal.correlationId, eventHead: proposal.eventHead, framing: proposal.framing, actorId: proposal.actor.actorId })
+    || proposal.preview.issuedAt !== proposal.createdAt || Date.parse(proposal.preview.expiresAt) <= Date.parse(proposal.preview.issuedAt)) {
+    fail('E_OPERATE_BINDING_MISMATCH', 'Planning proposal preview digest, actor, or expiry is not exact.');
+  }
+  if (proposal.state === 'approved') {
+    const reviewBase = { ...without(proposal, 'proposalHash'), revision: 1, predecessorProposalHash: null, state: 'review-required', confirmation: null };
+    const reviewHash = sha256Jcs(reviewBase);
+    const confirmation = proposal.confirmation;
+    if (proposal.revision !== 2 || proposal.predecessorProposalHash !== reviewHash || confirmation.reviewProposalHash !== reviewHash
+      || confirmation.reviewProposalRevision !== 1 || !sameHead(confirmation.eventHead, proposal.eventHead)
+      || confirmation.previewDigest !== proposal.preview.digest || confirmation.actorId !== proposal.actor.actorId
+      || confirmation.previewExpiresAt !== proposal.preview.expiresAt || confirmation.confirmationHash !== sha256Jcs(without(confirmation, 'confirmationHash'))
+      || Date.parse(confirmation.confirmedAt) < Date.parse(proposal.preview.issuedAt)
+      || Date.parse(confirmation.confirmedAt) > Date.parse(confirmation.previewExpiresAt)) fail('E_OPERATE_BINDING_MISMATCH', 'Approved proposal lacks exact, timely human confirmation proof.');
+  }
+  return proposal;
+}
+
+export function assertOperatingOriginV1(origin) {
+  assertOperateExperienceArtifactV2('operating-origin', origin); assertNoSensitiveContext(origin);
+  if (origin.originHash !== sha256Jcs(without(origin, 'originHash')) || origin.verification.metricId !== origin.metric.metricId || origin.verification.metricHash !== origin.metric.metricHash) fail('E_OPERATE_BINDING_MISMATCH', 'Operating origin hash or metric/verification binding is invalid.');
+  return origin;
+}
+
+export function assertOperatingDeliveryEvidenceV1(evidence) {
+  assertOperateExperienceArtifactV2('operating-delivery-evidence', evidence); assertNoSensitiveContext(evidence);
+  assertDeliveryClassification(evidence.classification, evidence.artifacts);
+  if (evidence.deliveryEvidenceHash !== sha256Jcs(without(evidence, 'deliveryEvidenceHash')) || evidence.outcomeStatus !== 'verification-required'
+    || evidence.verification.metricId !== evidence.metric.metricId || evidence.verification.metricHash !== evidence.metric.metricHash
+    || ((evidence.deliveryStatus === 'rolled-back') !== (evidence.rollback !== null))
+    || (evidence.rollback !== null && (evidence.rollback.originalShipRunId !== evidence.shipRun.runId || evidence.rollback.status !== 'succeeded'))) fail('E_OPERATE_BINDING_MISMATCH', 'Delivery evidence is not exact or attempts to substitute verification, rollback custody, or claim Outcome closure.');
+  return evidence;
+}
+
+function assertDeliveryClassification(classification, artifacts) {
+  const rank = { public: 0, internal: 1, confidential: 2, restricted: 3 };
+  if (!(classification in rank) || !Array.isArray(artifacts)
+    || artifacts.some((artifact) => !(artifact.classification in rank) || rank[artifact.classification] > rank[classification])) {
+    fail('E_OPERATE_BINDING_MISMATCH', 'Delivery classification cannot narrow accepted Artifact classification.');
+  }
+}
+
+export {
+  FORBIDDEN_KEY,
+  FORBIDDEN_TEXT,
+  PROTOCOL_VERSION,
+  assertDeliveryClassification,
+  assertNoSensitiveContext,
+  fail,
+  sameHead,
+  sameScope,
+  without,
+};

package/src/contracts.d.mts

@@ -0,0 +1,42 @@
+export interface ResolvedProtocolSchema { kind: string; protocolVersion: string; path: string; schema: Record<string, unknown> }
+export interface ProtocolValidationError { path: string; rule: string; detail: string }
+export declare const PROTOCOL_SCHEMA_REGISTRY: Readonly<Record<string, Readonly<Record<string, string>>>>;
+export declare const OPERATE_EXPERIENCE_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATING_DELIVERY_ROUTES_V1: readonly string[];
+export declare const OPERATE_ROLE_MANDATES_V2: readonly Readonly<Record<string, unknown>>[];
+export declare const OPERATE_EXTENSION_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_EVIDENCE_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_EVIDENCE_KINDS_V2: readonly string[];
+export declare const OPERATE_EVIDENCE_EDGE_RELATIONS_V2: readonly string[];
+export declare const OPERATE_EVIDENCE_RESOLVER_ERROR_CODES_V2: readonly string[];
+export declare const OPERATE_OPERATING_INTELLIGENCE_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_OPERATING_PROJECTION_IDENTITIES_V2: readonly string[];
+export declare const OPERATE_OPERATING_PROVIDER_REGISTRATION_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_GOVERNED_EXECUTION_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_GOVERNED_PROVIDER_REGISTRATION_CONTRACT_KINDS_V2: readonly string[];
+export declare const OPERATE_GOVERNED_EFFECT_CLASSES_V2: readonly string[];
+export declare const OPERATE_GOVERNED_POLICY_OUTCOMES_V2: readonly string[];
+export declare const OPERATE_GOVERNED_POLICY_TIERS_V2: readonly string[];
+export declare const OPERATE_GOVERNED_CORE_PROHIBITIONS_V2: readonly Readonly<Record<string, unknown>>[];
+export declare const OPERATE_GOVERNED_RECOVERY_CLASSIFICATIONS_V2: readonly string[];
+export declare const OPERATE_GOVERNED_OPERATION_STATES_V2: readonly string[];
+export declare const OPERATE_GOVERNED_OPERATION_TERMINAL_STATES_V2: readonly string[];
+export declare const OPERATE_EXECUTION_VERIFICATION_STATUSES_V2: readonly string[];
+export declare const OPERATE_HYPOTHESIS_VERIFICATION_STATUSES_V2: readonly string[];
+export declare const OPERATE_GOVERNED_TOOL_OPERATIONS_V2: readonly string[];
+export declare const OPERATE_AUTHORITY_GUARD_IDS_V2: readonly string[];
+export declare const OPERATE_PUBLIC_DOMAIN_CONTRACT_BINDINGS_V2: Readonly<Record<string, unknown>>;
+export declare function findOperateCoreProhibitionV2(values: unknown): Readonly<Record<string, unknown>> | null;
+export declare function assertOperateIntelligencePlanContractV2<T>(value: T): T;
+export declare function loadOperateRoleMandateV2(roleId: string, options?: { roleVersion?: string }): Readonly<Record<string, unknown>>;
+export declare function assertOperateRoleOutputContractV2<T>(roleId: string, outputContract: T, options?: { roleVersion?: string }): T;
+export declare function listProtocolSchemas(): Array<{ kind: string; protocolVersion: string; path: string }>;
+export declare function resolveProtocolSchema(kind: string, options?: { protocolVersion?: string }): ResolvedProtocolSchema;
+export declare function resolveOperateExperienceSchemaV2(kind: string, options?: { protocolVersion?: string }): ResolvedProtocolSchema;
+export declare function validateProtocolArtifact(kind: string, value: unknown, options?: { protocolVersion?: string }): ProtocolValidationError[];
+export declare function validateDashboardBootstrapV1(value: unknown): ProtocolValidationError[];
+export declare function assertDashboardBootstrapV1<T>(value: T): T;
+export declare function validateOperateExperienceArtifactV2(kind: string, value: unknown): ProtocolValidationError[];
+export declare function assertOperateExperienceArtifactV2<T>(kind: string, value: T): T;
+export declare function assertProtocolArtifact<T>(kind: string, value: T, options?: { protocolVersion?: string }): T;
+export declare function assertOperateGovernedExtensionRegistrationV2<T>(kind: string, value: T): T;