@openplanr/protocol 0.2.0

package/src/task-contracts.mjs

@@ -0,0 +1,130 @@
+import { CANONICAL_REGISTRIES, resolveTaskKind } from './registries.mjs';
+import { ProtocolError } from './errors.mjs';
+
+const diagnostic = (code, path, message) => ({ code, path, message });
+const pathKey = ({ repositoryKey, path }) => `${repositoryKey}:${path}`;
+
+export function validateTaskManifestSemantics(value, {
+  roles = CANONICAL_REGISTRIES['roles.json'],
+  taskKinds = CANONICAL_REGISTRIES['task-kinds.json'],
+} = {}) {
+  const diagnostics = [];
+  const binding = taskKinds.bindings.find(({ taskKind }) => taskKind === value?.routing?.taskKind);
+  if (!binding || binding.roleId !== value?.routing?.roleId) {
+    diagnostics.push(diagnostic('E_TASK_KIND_ROLE_MISMATCH', '$.routing', 'taskKind and roleId must match one canonical task-kind binding.'));
+  }
+  if (value?.routing?.taskKindRegistryDigest !== taskKinds.documentDigest
+    || value?.routing?.roleRegistryDigest !== roles.documentDigest) {
+    diagnostics.push(diagnostic('E_TASK_REGISTRY_BINDING_MISMATCH', '$.routing', 'routing must bind the exact canonical task-kind and role registry digests.'));
+  }
+  const role = roles.roles.find(({ roleId }) => roleId === value?.routing?.roleId);
+  if (!role || role.roleVersion !== value?.routing?.roleVersion) {
+    diagnostics.push(diagnostic('E_TASK_ROLE_VERSION_MISMATCH', '$.routing.roleVersion', 'role version is not present in the bound registry.'));
+  }
+  const scopeSets = new Map();
+  for (const scope of ['create', 'modify', 'preserve']) {
+    for (const entry of value?.scope?.[scope] ?? []) {
+      const key = pathKey(entry);
+      const previous = scopeSets.get(key);
+      if (previous) diagnostics.push(diagnostic('E_TASK_SCOPE_OVERLAP', `$.scope.${scope}`, `${key} is already declared in ${previous}.`));
+      scopeSets.set(key, scope);
+    }
+  }
+  if (!value?.reviewBinding?.planDigest || !value?.reviewBinding?.planningReviewReceiptDigest || !value?.reviewBinding?.ownerDecisionDigest) {
+    diagnostics.push(diagnostic('E_TASK_REVIEW_BINDING_REQUIRED', '$.reviewBinding', 'DEV task issuance requires plan, review-receipt, and owner-decision digests.'));
+  }
+  return diagnostics;
+}
+
+export function assertTaskManifestSemantics(value, options) {
+  const diagnostics = validateTaskManifestSemantics(value, options);
+  if (diagnostics.length) throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
+  return value;
+}
+
+export function validateTaskGraph(values) {
+  const diagnostics = [];
+  const byId = new Map(values.map((value) => [value?.task?.taskId, value]));
+  if (byId.size !== values.length || byId.has(undefined)) diagnostics.push(diagnostic('E_TASK_GRAPH_DUPLICATE', '$', 'Task graph IDs must be present and unique.'));
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) {
+      diagnostics.push(diagnostic('E_TASK_GRAPH_CYCLE', '$.dependencies', `Task dependency cycle includes ${id}.`));
+      return;
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dependency of byId.get(id)?.dependencies ?? []) {
+      if (!byId.has(dependency.taskId)) diagnostics.push(diagnostic('E_TASK_DEPENDENCY_MISSING', '$.dependencies', `Unknown dependency ${dependency.taskId}.`));
+      else visit(dependency.taskId);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of byId.keys()) if (id !== undefined) visit(id);
+  return diagnostics;
+}
+
+export function countR2Tasks(values) {
+  return values.reduce((count, value) => {
+    try {
+      return count + (resolveTaskKind(value.routing.taskKind).countsTowardR2 ? 1 : 0);
+    } catch {
+      return count;
+    }
+  }, 0);
+}
+
+export function validateTaskOutputSemantics(value, { taskManifest } = {}) {
+  const diagnostics = [];
+  if (taskManifest) {
+    if (value?.taskBinding?.taskManifestId !== taskManifest.taskManifestId
+      || value?.taskBinding?.taskManifestDigest !== taskManifest.documentDigest) {
+      diagnostics.push(diagnostic('E_TASK_OUTPUT_BINDING_MISMATCH', '$.taskBinding', 'Task output must bind the exact issued task manifest.'));
+    }
+    if (value?.roleBinding?.roleId !== taskManifest.routing.roleId
+      || value?.roleBinding?.roleVersion !== taskManifest.routing.roleVersion
+      || value?.roleBinding?.registryDigest !== taskManifest.routing.roleRegistryDigest) {
+      diagnostics.push(diagnostic('E_TASK_OUTPUT_ROLE_MISMATCH', '$.roleBinding', 'Task output role binding must equal issued routing.'));
+    }
+    const allowed = new Set([...taskManifest.scope.create, ...taskManifest.scope.modify].map(pathKey));
+    const preserved = new Map(taskManifest.scope.preserve.map((entry) => [pathKey(entry), entry]));
+    for (const change of value?.changes ?? []) {
+      const key = pathKey(change);
+      if (!allowed.has(key)) diagnostics.push(diagnostic('E_TASK_OUTPUT_SCOPE_ESCAPE', '$.changes', `${key} is outside Create/Modify.`));
+      if (preserved.has(key)) diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_CHANGED', '$.changes', `${key} intersects Preserve.`));
+    }
+    const verification = new Map((value?.preserveVerification ?? []).map((entry) => [pathKey(entry), entry]));
+    if (verification.size !== preserved.size || [...preserved.keys()].some((key) => !verification.has(key))) {
+      diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_COVERAGE', '$.preserveVerification', 'Preserve verification must bijectively cover the issued Preserve set.'));
+    }
+    for (const [key, entry] of verification) {
+      if (!preserved.has(key) || entry.beforeDigest !== entry.afterDigest || entry.unchanged !== true) {
+        diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_CHANGED', '$.preserveVerification', `${key} is not digest-equal.`));
+      }
+    }
+  }
+  if (value?.roleBinding?.roleId === 'planr-qa' && (value?.changes?.length ?? 0) > 0) {
+    diagnostics.push(diagnostic('E_TASK_OUTPUT_QA_WRITE', '$.changes', 'QA is read-only and cannot report changed files.'));
+  }
+  if ((value?.externalEffects?.length ?? 0) > 0) {
+    diagnostics.push(diagnostic('E_TASK_OUTPUT_EXTERNAL_EFFECT', '$.externalEffects', 'Protocol 1.5 task outputs permit no external effects.'));
+  }
+  const failedCommand = (value?.commandEvidence ?? []).some(({ status }) => status === 'failed');
+  const failedAcceptance = (value?.acceptanceEvidence ?? []).some(({ result }) => result !== 'passed');
+  const errorDiagnostic = (value?.diagnostics ?? []).some(({ severity }) => severity === 'error');
+  if (value?.outcome === 'completed' && (value.errorHandoff !== null || failedCommand || failedAcceptance || errorDiagnostic)) {
+    diagnostics.push(diagnostic('E_TASK_OUTPUT_COMPLETED_INVALID', '$.outcome', 'Completed output cannot retain failed evidence, error diagnostics, or an error handoff.'));
+  }
+  if (value?.outcome === 'blocked' && (!value.errorHandoff || !errorDiagnostic)) {
+    diagnostics.push(diagnostic('E_TASK_OUTPUT_BLOCKED_HANDOFF_REQUIRED', '$.errorHandoff', 'Blocked output requires an error diagnostic and bound error handoff.'));
+  }
+  return diagnostics;
+}
+
+export function assertTaskOutputSemantics(value, options) {
+  const diagnostics = validateTaskOutputSemantics(value, options);
+  if (diagnostics.length) throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
+  return value;
+}

package/src/workspace-contracts.d.mts

@@ -0,0 +1,26 @@
+export interface WorkspaceCiphertext { iv: string; ciphertext: string }
+export interface WorkspacePublicKey { kty: 'EC'; crv: 'P-256'; x: string; y: string; ext?: boolean; key_ops?: ['verify'] }
+export interface WorkspaceRevision extends WorkspaceCiphertext {
+  id: string; epoch: number; reviewOf: string; createdAt: string; signature: string;
+}
+export interface WorkspaceEvent extends WorkspaceCiphertext {
+  id: string; revisionId: string; reviewOf: string; epoch: number;
+  publicKey: WorkspacePublicKey; signature: string;
+}
+export interface DesignReviewWorkspace {
+  schemaVersion: '1.0.0'; id: string; version: number; epoch: number;
+  currentRevision: string; commentsPaused: boolean;
+  ownerPublicKey: WorkspacePublicKey; keyring: WorkspaceCiphertext;
+}
+export declare const DESIGN_WORKSPACE_VERSION: '1.0.0';
+export declare const DESIGN_WORKSPACE_API: '/api/v1/design-workspaces';
+export declare const DESIGN_WORKSPACE_MAX_BYTES: number;
+export declare const DESIGN_WORKSPACE_MAX_EVENT_BYTES: number;
+export declare const DESIGN_WORKSPACE_ID_PATTERN: string;
+export declare const DESIGN_WORKSPACE_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_WORKSPACE_CREATE_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_WORKSPACE_REVISION_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_WORKSPACE_EVENT_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_REVIEW_BUNDLE_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_WORKSPACE_SCHEMAS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+export declare function assertWorkspaceContract<T>(value: T, contract: Readonly<Record<string, unknown>>): T;

package/src/workspace-contracts.mjs

@@ -0,0 +1,83 @@
+import { validateJson } from './json-schema.mjs';
+import { DESIGN_DOCUMENT_SCHEMA } from './design-contracts.mjs';
+
+export const DESIGN_WORKSPACE_VERSION = '1.0.0';
+export const DESIGN_WORKSPACE_API = '/api/v1/design-workspaces';
+export const DESIGN_WORKSPACE_MAX_BYTES = 5 * 1024 * 1024;
+export const DESIGN_WORKSPACE_MAX_EVENT_BYTES = 256 * 1024;
+export const DESIGN_WORKSPACE_ID_PATTERN = '^[A-Za-z0-9_-]{22,64}$';
+const id = { type: 'string', pattern: DESIGN_WORKSPACE_ID_PATTERN };
+const digest = { type: 'string', pattern: '^[a-f0-9]{64}$' };
+const b64 = { type: 'string', pattern: '^[A-Za-z0-9_-]+$' };
+const epoch = { type: 'integer', minimum: 1, maximum: 2147483647 };
+const cipherProperties = { iv: { ...b64, minLength: 16, maxLength: 16 }, ciphertext: { ...b64, minLength: 22, maxLength: Math.ceil(DESIGN_WORKSPACE_MAX_BYTES * 4 / 3) } };
+const signature = { ...b64, minLength: 86, maxLength: 86 };
+const publicKey = {
+  type: 'object', additionalProperties: false, required: ['kty', 'crv', 'x', 'y'],
+  properties: { kty: { const: 'EC' }, crv: { const: 'P-256' }, x: { ...b64, minLength: 43, maxLength: 43 }, y: { ...b64, minLength: 43, maxLength: 43 }, ext: { type: 'boolean' }, key_ops: { type: 'array', items: { const: 'verify' }, maxItems: 1 } },
+};
+const schema = (name, properties, required = Object.keys(properties)) => ({
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: `https://openplanr.dev/schemas/v1.9.0/${name}.schema.json`,
+  'x-openplanr-contract': { id: name, version: '1.9.0' },
+  type: 'object', additionalProperties: false, properties, required,
+});
+
+export const DESIGN_WORKSPACE_REVISION_SCHEMA = schema('design-workspace-revision', {
+  id, epoch, reviewOf: digest, createdAt: { type: 'string', format: 'date-time' }, ...cipherProperties, signature,
+});
+export const DESIGN_WORKSPACE_EVENT_SCHEMA = schema('design-workspace-event', {
+  id, revisionId: id, reviewOf: digest, epoch, ...cipherProperties, publicKey, signature,
+});
+const sealed = { type: 'object', additionalProperties: false, required: ['iv', 'ciphertext'], properties: cipherProperties };
+export const DESIGN_WORKSPACE_CREATE_SCHEMA = schema('design-workspace-create', {
+  schemaVersion: { const: DESIGN_WORKSPACE_VERSION }, id, ownerPublicKey: publicKey,
+  ownerAuthHash: digest, reviewerAuthHash: digest, epoch: { const: 1 }, keyring: sealed,
+  revision: DESIGN_WORKSPACE_REVISION_SCHEMA, operationId: id, signature,
+});
+export const DESIGN_WORKSPACE_SCHEMA = schema('design-review-workspace', {
+  schemaVersion: { const: DESIGN_WORKSPACE_VERSION }, id, version: epoch, epoch,
+  currentRevision: id, commentsPaused: { type: 'boolean' }, ownerPublicKey: publicKey, keyring: sealed,
+});
+
+// An explicit presentation-only model. Authored paths, source provenance, and
+// design-system references are deliberately not part of a published workspace.
+const designProperties = structuredClone(DESIGN_DOCUMENT_SCHEMA.properties);
+for (const key of ['kind', 'schemaVersion', 'brief', 'assets', 'designSystem']) delete designProperties[key];
+delete designProperties.screens.items.properties.source;
+designProperties.screens.items.required = ['id', 'title'];
+delete designProperties.variants.items.properties.sources;
+export const DESIGN_REVIEW_BUNDLE_SCHEMA = schema('design-review-bundle', {
+  kind: { const: 'openplanr-design-review-bundle' }, schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
+  design: { type: 'object', additionalProperties: false, properties: designProperties, required: ['id', 'title', 'frames', 'screens', 'screenOrder', 'variants', 'selectedVariant', 'defaultView'] },
+  envelope: { type: 'object', required: ['schemaVersion', 'artifacts', 'viewer'] },
+  entries: { type: 'array', minItems: 1, maxItems: 256, items: { type: 'object', additionalProperties: false, required: ['artifactId', 'screenId', 'variantId', 'frameId'], properties: Object.fromEntries(['artifactId', 'screenId', 'variantId', 'frameId'].map((key) => [key, { type: 'string', minLength: 1, maxLength: 128 }])) } },
+  state: {
+    type: ['object', 'null'], additionalProperties: false,
+    properties: {
+      positions: {
+        type: 'object', additionalProperties: {
+          type: 'object', additionalProperties: false, required: ['x', 'y'],
+          properties: { x: { type: 'number', minimum: -1e7, maximum: 1e7 }, y: { type: 'number', minimum: -1e7, maximum: 1e7 } },
+        },
+      },
+    },
+  },
+  revision: { type: 'string', minLength: 1, maxLength: 128 },
+  verification: { type: ['object', 'null'], additionalProperties: false, properties: { status: { enum: ['verified', 'unverified', 'failed', 'pending'] } } },
+}, ['kind', 'schemaVersion', 'design', 'envelope', 'entries', 'revision']);
+DESIGN_REVIEW_BUNDLE_SCHEMA.$defs = structuredClone(DESIGN_DOCUMENT_SCHEMA.$defs);
+
+export function assertWorkspaceContract(value, contract) {
+  const errors = validateJson(value, contract);
+  if (errors.length) throw new TypeError(`Invalid ${contract['x-openplanr-contract'].id}: ${errors.slice(0, 5).map(({ path, detail }) => `${path}: ${detail}`).join('; ')}`);
+  return value;
+}
+
+export const DESIGN_WORKSPACE_SCHEMAS = Object.freeze({
+  'design-review-workspace': DESIGN_WORKSPACE_SCHEMA,
+  'design-workspace-create': DESIGN_WORKSPACE_CREATE_SCHEMA,
+  'design-workspace-revision': DESIGN_WORKSPACE_REVISION_SCHEMA,
+  'design-workspace-event': DESIGN_WORKSPACE_EVENT_SCHEMA,
+  'design-review-bundle': DESIGN_REVIEW_BUNDLE_SCHEMA,
+});