chati-dev 4.4.0 → 4.5.1

package/node_modules/@chati/knowledge-context/src/index.js

@@ -0,0 +1,202 @@
+import { closeSync, existsSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, relative } from 'node:path';
+import { ContractError, canonicalize, sha256 } from '@chati/core';
+
+const RETRIEVAL_SCOPES = new Set(['framework', 'organization', 'client', 'project', 'stack', 'task-category']);
+const RETRIEVAL_PURPOSES = new Set(['discovery', 'planning', 'routing', 'execution', 'review', 'release', 'incident']);
+const CANDIDATE_SCOPES = new Set([...RETRIEVAL_SCOPES, 'individual']);
+const PRIVACY_CLASSIFICATIONS = new Set(['internal', 'confidential', 'client-restricted', 'personal-restricted']);
+const SANITIZATION_STATUSES = new Set(['not-required', 'pending', 'passed', 'rejected']);
+const PROPOSED_ACTIONS = new Set(['context', 'skill', 'template', 'quality-gate', 'regression-test', 'framework-change']);
+const CANDIDATE_STATUSES = new Set(['observed', 'candidate']);
+const CAPABILITY_STATES = new Set(['available', 'not-configured', 'unavailable', 'index-error']);
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
+
+function fail(code, message, details = {}) {
+  throw new ContractError(code, message, details);
+}
+
+function assertObject(value, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(code, `${label} must be an object`);
+}
+
+function assertString(value, code, label) {
+  if (typeof value !== 'string' || value.trim() === '') fail(code, `${label} must be a non-empty string`);
+}
+
+function assertIdentifier(value, code, label) {
+  assertString(value, code, label);
+  if (!IDENTIFIER.test(value)) fail(code, `${label} must be an opaque identifier`);
+}
+
+function assertStringArray(value, code, label, { allowEmpty = true } = {}) {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || !value.every((entry) => typeof entry === 'string' && entry.trim() !== '')) {
+    fail(code, `${label} must be an array of non-empty strings`);
+  }
+}
+
+function timestamp(clock) {
+  if (typeof clock !== 'function') fail('MISSING_CLOCK', 'a deterministic clock function is required');
+  const value = clock();
+  const millis = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (Number.isNaN(millis)) fail('INVALID_CLOCK', 'clock must return a valid Date or RFC3339 timestamp');
+  return new Date(millis).toISOString();
+}
+
+function assertTenant({ scope, classification, tenant_ref }, code) {
+  if (scope === 'client' || classification === 'client-restricted') assertIdentifier(tenant_ref, code, 'tenant_ref');
+}
+
+/** Validates C-09 without selecting a source or performing any I/O. */
+export function validateKnowledgeRetrievalRequest(request) {
+  assertObject(request, 'INVALID_KNOWLEDGE_RETRIEVAL', 'request');
+  for (const field of ['retrieval_id', 'purpose', 'query_ref', 'policy_ref']) assertIdentifier(request[field], 'INVALID_KNOWLEDGE_RETRIEVAL', field);
+  if (!RETRIEVAL_SCOPES.has(request.request_scope)) fail('INVALID_KNOWLEDGE_RETRIEVAL', 'request_scope is invalid');
+  if (!RETRIEVAL_PURPOSES.has(request.purpose)) fail('INVALID_KNOWLEDGE_RETRIEVAL', 'purpose is invalid');
+  assertTenant({ scope: request.request_scope, tenant_ref: request.tenant_ref }, 'MISSING_TENANT_REF');
+  return Object.freeze(canonicalize(request));
+}
+
+/** Validates the CHATI-owned subset of C-08. It intentionally has no lifecycle beyond candidate. */
+export function validateLearningCandidate(candidate) {
+  assertObject(candidate, 'INVALID_LEARNING_CANDIDATE', 'candidate');
+  for (const field of ['candidate_id', 'origin', 'taxonomy', 'proposed_action', 'status']) assertIdentifier(candidate[field], 'INVALID_LEARNING_CANDIDATE', field);
+  if (!['rail-evidence', 'explicit-personal-contribution'].includes(candidate.origin)) fail('INVALID_LEARNING_CANDIDATE', 'origin is invalid');
+  if (!CANDIDATE_SCOPES.has(candidate.scope)) fail('INVALID_LEARNING_CANDIDATE', 'scope is invalid');
+  if (!PRIVACY_CLASSIFICATIONS.has(candidate.privacy_classification)) fail('INVALID_LEARNING_CANDIDATE', 'privacy_classification is invalid');
+  if (!SANITIZATION_STATUSES.has(candidate.sanitization_status)) fail('INVALID_LEARNING_CANDIDATE', 'sanitization_status is invalid');
+  if (!PROPOSED_ACTIONS.has(candidate.proposed_action)) fail('INVALID_LEARNING_CANDIDATE', 'proposed_action is invalid');
+  if (!CANDIDATE_STATUSES.has(candidate.status)) fail('UNAUTHORIZED_KNOWLEDGE_LIFECYCLE', 'CHATI may only emit observed or candidate artifacts');
+  assertStringArray(candidate.origin_event_refs, 'INVALID_LEARNING_CANDIDATE', 'origin_event_refs', { allowEmpty: false });
+  assertStringArray(candidate.evidence_refs, 'INVALID_LEARNING_CANDIDATE', 'evidence_refs', { allowEmpty: false });
+  if (candidate.origin === 'rail-evidence') assertStringArray(candidate.lineage_refs, 'INVALID_LEARNING_CANDIDATE', 'lineage_refs', { allowEmpty: false });
+  else if (candidate.lineage_refs !== undefined) assertStringArray(candidate.lineage_refs, 'INVALID_LEARNING_CANDIDATE', 'lineage_refs', { allowEmpty: false });
+  assertTenant({ scope: candidate.scope, classification: candidate.privacy_classification, tenant_ref: candidate.tenant_ref }, 'MISSING_TENANT_REF');
+  if (candidate.privacy_classification === 'personal-restricted') fail('PERSONAL_RESTRICTED_CANDIDATE_FORBIDDEN', 'personal-restricted material cannot be emitted as a Company Brain candidate');
+  if (candidate.origin === 'explicit-personal-contribution') {
+    assertIdentifier(candidate.consent_ref, 'PERSONAL_CONSENT_REQUIRED', 'consent_ref');
+    if (candidate.sanitization_status !== 'passed') fail('PERSONAL_SANITIZATION_REQUIRED', 'explicit personal contribution requires sanitization_status passed');
+  }
+  return Object.freeze(canonicalize(candidate));
+}
+
+function receiptFor(request, state, returned_learning_refs, clock) {
+  return Object.freeze(canonicalize({
+    schema_version: 1,
+    retrieval_id: request.retrieval_id,
+    request_scope: request.request_scope,
+    ...(request.tenant_ref ? { tenant_ref: request.tenant_ref } : {}),
+    purpose: request.purpose,
+    query_ref: request.query_ref,
+    policy_ref: request.policy_ref,
+    state,
+    returned_learning_refs,
+    occurred_at: timestamp(clock),
+    source: 'company-brain-capability',
+  }));
+}
+
+function validateFakeRecord(record) {
+  assertObject(record, 'INVALID_KNOWLEDGE_RECORD', 'record');
+  assertIdentifier(record.learning_ref, 'INVALID_KNOWLEDGE_RECORD', 'learning_ref');
+  if (!RETRIEVAL_SCOPES.has(record.scope)) fail('INVALID_KNOWLEDGE_RECORD', 'record.scope is invalid');
+  if (record.source !== 'company-brain') fail('PERSONAL_BRAIN_SOURCE_FORBIDDEN', 'fake adapter only accepts company-brain records');
+  if (record.scope === 'client') assertIdentifier(record.tenant_ref, 'INVALID_KNOWLEDGE_RECORD', 'record.tenant_ref');
+  if (record.approved !== true) fail('UNAPPROVED_KNOWLEDGE_FORBIDDEN', 'fake adapter only accepts approved records');
+  return canonicalize(record);
+}
+
+/**
+ * Hermetic C-09 adapter. Its records are synthetic approved Company Brain
+ * references, never vault paths or content. It has no write, promotion,
+ * validation or deduplication capability by design.
+ */
+export function createFakeKnowledgeReadAdapter({ capability_state = 'not-configured', records = [], authorized_tenant_refs, clock } = {}) {
+  if (!CAPABILITY_STATES.has(capability_state)) fail('INVALID_KNOWLEDGE_CAPABILITY_STATE', 'capability_state is invalid');
+  if (typeof clock !== 'function') fail('MISSING_CLOCK', 'a deterministic clock function is required');
+  if (!Array.isArray(records)) fail('INVALID_KNOWLEDGE_RECORD', 'records must be an array');
+  const approvedRecords = records.map(validateFakeRecord);
+  if (authorized_tenant_refs !== undefined) assertStringArray(authorized_tenant_refs, 'INVALID_TENANT_AUTHORIZATION', 'authorized_tenant_refs');
+  const authorizedTenants = authorized_tenant_refs === undefined ? undefined : new Set(authorized_tenant_refs);
+  const reads = [];
+
+  function retrieve(input) {
+    const request = validateKnowledgeRetrievalRequest(input);
+    if (capability_state !== 'available') {
+      const receipt = receiptFor(request, capability_state, [], clock);
+      reads.push(Object.freeze({ request, receipt }));
+      return receipt;
+    }
+    if (request.request_scope === 'client') {
+      if (authorizedTenants === undefined) fail('TENANT_AUTHORIZATION_UNAVAILABLE', 'client retrieval requires an explicit tenant authorization context');
+      if (!authorizedTenants.has(request.tenant_ref)) fail('TENANT_SCOPE_MISMATCH', 'client tenant is not authorized for this read adapter', { tenant_ref: request.tenant_ref });
+    }
+    const matches = approvedRecords.filter((record) => {
+      if (record.scope !== request.request_scope) return false;
+      if (request.request_scope === 'client') return record.tenant_ref === request.tenant_ref;
+      return true;
+    }).map((record) => record.learning_ref);
+    const receipt = receiptFor(request, matches.length === 0 ? 'empty' : 'available', matches, clock);
+    reads.push(Object.freeze({ request, receipt }));
+    return receipt;
+  }
+
+  return Object.freeze({
+    mode: 'read-only',
+    capability_state,
+    retrieve,
+    get reads() { return Object.freeze([...reads]); },
+  });
+}
+
+function assertProjectLocalPath(project_dir, candidate_id) {
+  assertString(project_dir, 'INVALID_PROJECT_DIRECTORY', 'project_dir');
+  assertIdentifier(candidate_id, 'INVALID_LEARNING_CANDIDATE', 'candidate_id');
+  const base = resolve(project_dir, '.chati', 'knowledge-candidates');
+  const target = resolve(base, `${candidate_id}.json`);
+  if (relative(base, target).startsWith('..')) fail('CANDIDATE_PATH_ESCAPE', 'candidate artifact must remain in the project-local store');
+  return { base, target };
+}
+
+/**
+ * Writes one immutable C-08 artifact below <project>/.chati/knowledge-candidates.
+ * This is intentionally the only side effect in this package.
+ */
+export function emitLocalLearningCandidate({ project_dir, candidate } = {}) {
+  const validated = validateLearningCandidate(candidate);
+  const { base, target } = assertProjectLocalPath(project_dir, validated.candidate_id);
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  // POSIX rename replaces an existing destination. A durable exclusive lock
+  // serializes every emitter before that operation and preserves immutability.
+  const lock = `${target}.lock`;
+  let lockDescriptor;
+  try {
+    lockDescriptor = openSync(lock, 'wx', 0o600);
+  } catch (error) {
+    if (error?.code === 'EEXIST') fail('CANDIDATE_PUBLICATION_BUSY', 'another local emitter is publishing this candidate', { candidate_id: validated.candidate_id });
+    throw error;
+  }
+  const artifact = Object.freeze(canonicalize({
+    schema_version: 1,
+    artifact_type: 'learning-candidate',
+    artifact_id: validated.candidate_id,
+    artifact_digest: sha256(validated),
+    candidate: validated,
+  }));
+  const temporary = join(dirname(target), `.${validated.candidate_id}.${process.pid}.tmp`);
+  try {
+    if (existsSync(target)) fail('CANDIDATE_ALREADY_EXISTS', 'candidate artifact already exists', { candidate_id: validated.candidate_id });
+    writeFileSync(temporary, `${JSON.stringify(artifact)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    renameSync(temporary, target);
+  } catch (error) {
+    // The lock makes a competing emitter wait/fail before POSIX rename, which
+    // otherwise has replacement semantics.
+    if (error?.code === 'EEXIST') fail('CANDIDATE_PUBLICATION_CONFLICT', 'candidate publication encountered a conflicting local artifact', { candidate_id: validated.candidate_id });
+    throw error;
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+    closeSync(lockDescriptor);
+    unlinkSync(lock);
+  }
+  return Object.freeze(canonicalize({ candidate_id: validated.candidate_id, artifact_ref: `project-local://.chati/knowledge-candidates/${validated.candidate_id}.json`, artifact_digest: artifact.artifact_digest }));
+}

package/node_modules/@chati/planning/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@chati/planning",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": "./src/index.js",
+  "dependencies": {
+    "@chati/browser-capability": "0.1.0",
+    "@chati/core": "0.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/node_modules/@chati/planning/src/index.js

@@ -0,0 +1,367 @@
+import { execFileSync } from 'node:child_process';
+import { ContractError, canonicalize, sha256 } from '@chati/core';
+import { assertBrowserCapabilityForTask } from '@chati/browser-capability';
+
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
+
+function fail(code, message, details = {}) {
+  throw new ContractError(code, message, details);
+}
+
+function assertObject(value, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(code, `${label} must be an object`);
+}
+
+function assertString(value, code, label) {
+  if (typeof value !== 'string' || value.trim() === '') fail(code, `${label} must be a non-empty string`);
+}
+
+function assertTimestamp(value, code, label) {
+  assertString(value, code, label);
+  if (!RFC3339.test(value)) fail(code, `${label} must be RFC3339`);
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) deepFreeze(nested);
+  }
+  return value;
+}
+
+function assertStringArray(value, code, label, { allowEmpty = true } = {}) {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || !value.every((item) => typeof item === 'string' && item.trim() !== '')) {
+    fail(code, `${label} must be an array of non-empty strings`);
+  }
+}
+
+function assertImmutableRef(value, code, label) {
+  assertString(value, code, label);
+}
+
+function validateTask(task, knownTaskIds) {
+  assertObject(task, 'INVALID_HANDOFF_TASK', 'task');
+  assertString(task.task_id, 'INVALID_HANDOFF_TASK', 'task.task_id');
+  assertStringArray(task.dependency_ids, 'INVALID_HANDOFF_TASK', 'task.dependency_ids');
+  assertStringArray(task.acceptance_criteria_refs, 'MISSING_ACCEPTANCE_CRITERIA', 'task.acceptance_criteria_refs', { allowEmpty: false });
+  assertImmutableRef(task.execution_scope_ref, 'INVALID_HANDOFF_TASK', 'task.execution_scope_ref');
+  assertImmutableRef(task.routing_constraints_ref, 'INVALID_HANDOFF_TASK', 'task.routing_constraints_ref');
+  assertObject(task.execution_binding, 'TASK_EXECUTION_BINDING_REQUIRED', 'task.execution_binding');
+  for (const field of ['provider_id', 'harness_id', 'model_id', 'reasoning_configuration']) {
+    assertString(task.execution_binding[field], 'TASK_EXECUTION_BINDING_REQUIRED', `task.execution_binding.${field}`);
+  }
+  if (task.clickup_ref !== undefined) assertImmutableRef(task.clickup_ref, 'INVALID_HANDOFF_TASK', 'task.clickup_ref');
+  if (task.requires_browser !== undefined && typeof task.requires_browser !== 'boolean') fail('INVALID_HANDOFF_TASK', 'task.requires_browser must be boolean');
+  if (task.requires_browser === true && (!task.browser_policy || typeof task.browser_policy !== 'object' || Array.isArray(task.browser_policy))) {
+    fail('BROWSER_POLICY_REQUIRED', 'browser tasks require a browser_policy in the sealed handoff');
+  }
+  if (task.requires_browser === true) assertBrowserCapabilityForTask(task);
+  assertObject(task.estimate, 'INVALID_HANDOFF_TASK', 'task.estimate');
+  for (const field of ['ai_processing', 'human_effort', 'uncertainty']) {
+    if (task.estimate[field] === undefined || task.estimate[field] === null) {
+      fail('INVALID_HANDOFF_TASK', `task.estimate.${field} is required`);
+    }
+  }
+  for (const dependencyId of task.dependency_ids) {
+    if (dependencyId === task.task_id || !knownTaskIds.has(dependencyId)) {
+      fail('UNRESOLVED_DEPENDENCY', `task ${task.task_id} has unresolved dependency ${dependencyId}`, { task_id: task.task_id, dependency_id: dependencyId });
+    }
+  }
+}
+
+function validateLineage(lineage, handoff) {
+  if (lineage === undefined) return;
+  assertObject(lineage, 'INVALID_HANDOFF_LINEAGE', 'lineage');
+  if (!['rebase', 'revision'].includes(lineage.kind)) fail('INVALID_HANDOFF_LINEAGE', 'lineage.kind must be rebase or revision');
+  for (const field of ['supersedes_handoff_id', 'supersedes_version', 'supersedes_manifest_digest']) {
+    assertString(lineage[field], 'INVALID_HANDOFF_LINEAGE', `lineage.${field}`);
+  }
+  if (lineage.supersedes_handoff_id === handoff.handoff_id) fail('INVALID_HANDOFF_LINEAGE', 'handoff cannot supersede itself');
+  if (!/^[a-f0-9]{64}$/i.test(lineage.supersedes_manifest_digest)) {
+    fail('INVALID_HANDOFF_LINEAGE', 'lineage.supersedes_manifest_digest must be SHA-256');
+  }
+}
+
+/**
+ * Returns the exact material used to derive a handoff digest.  The digest
+ * itself is intentionally excluded to make verification possible.
+ */
+export function buildCanonicalManifest(handoff) {
+  assertObject(handoff, 'INVALID_HANDOFF', 'handoff');
+  const { seal, ...rest } = handoff;
+  assertObject(seal, 'INVALID_HANDOFF', 'seal');
+  const { manifest_digest, ...sealWithoutDigest } = seal;
+  return canonicalize({ ...rest, seal: sealWithoutDigest });
+}
+
+export function computeManifestDigest(handoff) {
+  return sha256(buildCanonicalManifest(handoff));
+}
+
+/** Validates a complete C-03 artifact and fails before any dispatch can occur. */
+export function validateSealedHandoff(handoff) {
+  assertObject(handoff, 'INVALID_HANDOFF', 'handoff');
+  for (const field of ['handoff_id', 'version', 'project_id']) assertString(handoff[field], 'INVALID_HANDOFF', field);
+  assertObject(handoff.source_artifacts, 'INVALID_HANDOFF', 'source_artifacts');
+  for (const field of ['requirements_ref', 'architecture_ref', 'qa_plan_ref']) {
+    assertImmutableRef(handoff.source_artifacts[field], 'INVALID_HANDOFF', `source_artifacts.${field}`);
+  }
+  if (handoff.source_artifacts.ux_ref !== undefined) assertImmutableRef(handoff.source_artifacts.ux_ref, 'INVALID_HANDOFF', 'source_artifacts.ux_ref');
+  assertImmutableRef(handoff.task_graph_ref, 'INVALID_HANDOFF', 'task_graph_ref');
+  if (!Array.isArray(handoff.tasks) || handoff.tasks.length === 0) fail('INVALID_HANDOFF', 'tasks must be a non-empty array');
+  const taskIds = new Set();
+  for (const task of handoff.tasks) {
+    assertObject(task, 'INVALID_HANDOFF_TASK', 'task');
+    assertString(task.task_id, 'INVALID_HANDOFF_TASK', 'task.task_id');
+    if (taskIds.has(task.task_id)) fail('DUPLICATE_TASK_ID', `task_id ${task.task_id} is duplicated`);
+    taskIds.add(task.task_id);
+  }
+  for (const task of handoff.tasks) validateTask(task, taskIds);
+  validateLineage(handoff.lineage, handoff);
+  assertObject(handoff.seal, 'INVALID_HANDOFF_SEAL', 'seal');
+  assertString(handoff.seal.sealed_by, 'INVALID_HANDOFF_SEAL', 'seal.sealed_by');
+  assertTimestamp(handoff.seal.sealed_at, 'INVALID_HANDOFF_SEAL', 'seal.sealed_at');
+  if (handoff.seal.digest_algorithm !== 'sha256') fail('UNSUPPORTED_DIGEST_ALGORITHM', 'seal.digest_algorithm must be sha256');
+  assertString(handoff.seal.manifest_digest, 'INVALID_HANDOFF_SEAL', 'seal.manifest_digest');
+  if (!/^[a-f0-9]{64}$/i.test(handoff.seal.manifest_digest)) fail('INVALID_HANDOFF_SEAL', 'seal.manifest_digest must be SHA-256');
+  assertString(handoff.seal.git_commit_ref, 'INVALID_GIT_COMMIT_REF', 'seal.git_commit_ref');
+  if (!GIT_OBJECT_ID.test(handoff.seal.git_commit_ref)) fail('INVALID_GIT_COMMIT_REF', 'seal.git_commit_ref must be an immutable Git object id');
+  const actualDigest = computeManifestDigest(handoff);
+  if (actualDigest !== handoff.seal.manifest_digest) {
+    fail('HANDOFF_DIGEST_MISMATCH', 'handoff manifest digest does not match its material', { expected: handoff.seal.manifest_digest, actual: actualDigest });
+  }
+  return deepFreeze(canonicalize(handoff));
+}
+
+/** Seals a validated planning artifact. It cannot mutate the supplied draft. */
+export function sealHandoff(draft) {
+  assertObject(draft, 'INVALID_HANDOFF', 'draft');
+  const copied = canonicalize(draft);
+  assertObject(copied.seal, 'INVALID_HANDOFF_SEAL', 'seal');
+  const seal = { ...copied.seal, digest_algorithm: copied.seal.digest_algorithm ?? 'sha256' };
+  delete seal.manifest_digest;
+  const unsealed = { ...copied, seal };
+  const manifestDigest = computeManifestDigest(unsealed);
+  return validateSealedHandoff({ ...unsealed, seal: { ...seal, manifest_digest: manifestDigest } });
+}
+
+/** Checks that an object id exists as a local commit. No remote is consulted. */
+export function verifyLocalGitCommit({ git_dir, git_commit_ref }) {
+  assertString(git_dir, 'INVALID_GIT_DIRECTORY', 'git_dir');
+  assertString(git_commit_ref, 'INVALID_GIT_COMMIT_REF', 'git_commit_ref');
+  if (!GIT_OBJECT_ID.test(git_commit_ref)) fail('INVALID_GIT_COMMIT_REF', 'git_commit_ref must be an immutable Git object id');
+  try {
+    execFileSync('git', ['-C', git_dir, 'cat-file', '-e', `${git_commit_ref}^{commit}`], { stdio: 'ignore' });
+  } catch {
+    fail('GIT_COMMIT_NOT_FOUND', 'sealed git_commit_ref is unavailable in the supplied local repository', { git_commit_ref });
+  }
+  return true;
+}
+
+export function assertDispatchable({ handoff, task_id, completed_task_ids = [], git_dir, status = 'active' }) {
+  const validated = validateSealedHandoff(handoff);
+  if (status === 'cancelled') fail('HANDOFF_CANCELLED', 'cancelled handoff cannot be dispatched', { handoff_id: validated.handoff_id });
+  if (status === 'superseded') fail('HANDOFF_SUPERSEDED', 'superseded handoff cannot be dispatched', { handoff_id: validated.handoff_id });
+  if (status !== 'active') fail('HANDOFF_NOT_ACTIVE', 'handoff is not active', { status });
+  // A sealed digest without a reachable local commit is insufficient evidence
+  // for a new dispatch. Recovery is separately bound to its original attempt.
+  assertString(git_dir, 'MISSING_GIT_VERIFICATION_CONTEXT', 'git_dir');
+  verifyLocalGitCommit({ git_dir, git_commit_ref: validated.seal.git_commit_ref });
+  assertString(task_id, 'INVALID_TASK_ID', 'task_id');
+  assertStringArray(completed_task_ids, 'INVALID_COMPLETED_TASK_IDS', 'completed_task_ids');
+  const task = validated.tasks.find((candidate) => candidate.task_id === task_id);
+  if (!task) fail('TASK_NOT_FOUND', 'task is not part of the sealed handoff', { task_id });
+  const completed = new Set(completed_task_ids);
+  const pending = task.dependency_ids.filter((dependencyId) => !completed.has(dependencyId));
+  if (pending.length > 0) fail('DEPENDENCY_PENDING', 'task has incomplete dependencies', { task_id, pending_dependency_ids: pending });
+  return deepFreeze(canonicalize({
+    handoff_id: validated.handoff_id,
+    handoff_version: validated.version,
+    manifest_digest: validated.seal.manifest_digest,
+    git_commit_ref: validated.seal.git_commit_ref,
+    task_id: task.task_id,
+  }));
+}
+
+export function createAttemptBinding({ handoff, task_id, attempt_id, completed_task_ids = [], git_dir, status = 'active' }) {
+  assertString(attempt_id, 'INVALID_ATTEMPT_ID', 'attempt_id');
+  const dispatch = assertDispatchable({ handoff, task_id, completed_task_ids, git_dir, status });
+  return deepFreeze(canonicalize({ attempt_id, ...dispatch }));
+}
+
+export function validateAttemptBinding({ attempt, handoff }) {
+  assertObject(attempt, 'INVALID_ATTEMPT_BINDING', 'attempt');
+  const validated = validateSealedHandoff(handoff);
+  for (const field of ['attempt_id', 'handoff_id', 'handoff_version', 'manifest_digest', 'git_commit_ref', 'task_id']) {
+    assertString(attempt[field], 'INVALID_ATTEMPT_BINDING', field);
+  }
+  if (attempt.handoff_id !== validated.handoff_id || attempt.handoff_version !== validated.version || attempt.manifest_digest !== validated.seal.manifest_digest || attempt.git_commit_ref !== validated.seal.git_commit_ref) {
+    fail('ATTEMPT_HANDOFF_DRIFT', 'attempt is not bound to this exact sealed handoff', { attempt_id: attempt.attempt_id });
+  }
+  if (!validated.tasks.some((task) => task.task_id === attempt.task_id)) fail('ATTEMPT_TASK_DRIFT', 'attempt task is not part of bound handoff');
+  return deepFreeze(canonicalize(attempt));
+}
+
+function legacyValue(value, label) {
+  if (typeof value === 'string' && value.trim() !== '') return value;
+  fail('INVALID_LEGACY_PLANNING_ARTIFACT', `${label} must provide an immutable reference`);
+}
+
+function legacyCriteriaRefs(task, taskId) {
+  if (Array.isArray(task.acceptance_criteria_refs)) return task.acceptance_criteria_refs;
+  if (!Array.isArray(task.criteria) || task.criteria.length === 0 || !task.criteria.every((criterion) => typeof criterion === 'string' && criterion.trim() !== '')) {
+    fail('MISSING_ACCEPTANCE_CRITERIA', `legacy task ${taskId} must include criteria or acceptance_criteria_refs`);
+  }
+  // Legacy criteria are inline strings rather than immutable artifacts. Their
+  // content-addressed refs preserve their exact material in the imported graph.
+  return task.criteria.map((criterion) => `legacy-inline://sha256/${sha256({ task_id: taskId, criterion })}`);
+}
+
+/**
+ * Maps the old CHATI task-plan shape into an unsealed C-03 draft. It is a
+ * pure importer: it reads no legacy files and never edits the legacy package.
+ */
+export function importLegacyPlanningArtifact({ legacy, handoff_id, version, project_id, seal, lineage, default_execution_binding, clickup_required = true } = {}) {
+  assertObject(legacy, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'legacy');
+  assertString(handoff_id, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'handoff_id');
+  assertString(version, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'version');
+  assertObject(seal, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'seal');
+  const artifacts = legacy.artifacts ?? legacy.source_artifacts;
+  assertObject(artifacts, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'legacy.artifacts');
+  const resolvedProjectId = project_id ?? legacy.project_id ?? legacy.project?.id;
+  assertString(resolvedProjectId, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'project_id');
+  const legacyTasks = legacy.tasks ?? legacy.task_graph?.tasks;
+  if (!Array.isArray(legacyTasks) || legacyTasks.length === 0) fail('INVALID_LEGACY_PLANNING_ARTIFACT', 'legacy.tasks must be a non-empty array');
+  const sharedRoutingRef = legacy.routing_constraints_ref ?? legacy.routing_policy_ref;
+  const sharedClickUpRefs = legacy.clickup_refs ?? {};
+  const tasks = legacyTasks.map((legacyTask) => {
+    assertObject(legacyTask, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'legacy task');
+    const taskId = legacyTask.task_id ?? legacyTask.id;
+    assertString(taskId, 'INVALID_LEGACY_PLANNING_ARTIFACT', 'legacy task id');
+    const scope = legacyTask.execution_scope_ref ?? legacyTask.scope_ref ?? legacyTask.scope;
+    const routing = legacyTask.routing_constraints_ref ?? legacyTask.routing_policy_ref ?? sharedRoutingRef;
+    const clickup = legacyTask.clickup_ref ?? legacyTask.clickup_task_ref ?? sharedClickUpRefs[taskId];
+    const estimate = legacyTask.estimate ?? legacyTask.estimates;
+    const executionBinding = legacyTask.execution_binding ?? default_execution_binding;
+    assertObject(executionBinding, 'TASK_EXECUTION_BINDING_REQUIRED', `legacy task ${taskId}.execution_binding`);
+    for (const field of ['provider_id', 'harness_id', 'model_id', 'reasoning_configuration']) {
+      assertString(executionBinding[field], 'TASK_EXECUTION_BINDING_REQUIRED', `legacy task ${taskId}.execution_binding.${field}`);
+    }
+    const task = {
+      task_id: taskId,
+      dependency_ids: legacyTask.dependency_ids ?? legacyTask.dependencies ?? [],
+      acceptance_criteria_refs: legacyCriteriaRefs(legacyTask, taskId),
+      execution_scope_ref: legacyValue(scope, `legacy task ${taskId}.scope`),
+      routing_constraints_ref: legacyValue(routing, `legacy task ${taskId}.routing_constraints`),
+      execution_binding: canonicalize(executionBinding),
+      estimate,
+    };
+    if (clickup_required || clickup !== undefined) task.clickup_ref = legacyValue(clickup, `legacy task ${taskId}.clickup_ref`);
+    return task;
+  });
+  const source_artifacts = {
+    requirements_ref: legacyValue(artifacts.requirements_ref ?? artifacts.requirements, 'legacy artifacts.requirements'),
+    architecture_ref: legacyValue(artifacts.architecture_ref ?? artifacts.architecture, 'legacy artifacts.architecture'),
+    qa_plan_ref: legacyValue(artifacts.qa_plan_ref ?? artifacts.qa_plan, 'legacy artifacts.qa_plan'),
+  };
+  const ux = artifacts.ux_ref ?? artifacts.ux;
+  if (ux !== undefined) source_artifacts.ux_ref = legacyValue(ux, 'legacy artifacts.ux');
+  return canonicalize({
+    handoff_id,
+    version,
+    project_id: resolvedProjectId,
+    source_artifacts,
+    task_graph_ref: legacyValue(legacy.task_graph_ref ?? legacy.task_graph?.ref ?? artifacts.task_graph_ref ?? artifacts.task_graph, 'legacy task graph'),
+    tasks,
+    ...(lineage === undefined ? {} : { lineage }),
+    seal,
+  });
+}
+
+/**
+ * In-memory lifecycle gate used by the future RAIL dispatcher. It deliberately
+ * has no side effects: callers must pass its dispatch proof before claiming work.
+ */
+export class SealedHandoffRegistry {
+  #records = new Map();
+  #attempts = new Map();
+
+  register(handoff) {
+    const validated = validateSealedHandoff(handoff);
+    if (this.#records.has(validated.handoff_id)) fail('HANDOFF_ALREADY_REGISTERED', 'handoff_id is already registered');
+    this.#records.set(validated.handoff_id, { handoff: validated, status: 'active', cancellation: null });
+    return validated;
+  }
+
+  rebase({ predecessor_handoff_id, successor }) {
+    assertString(predecessor_handoff_id, 'INVALID_HANDOFF_ID', 'predecessor_handoff_id');
+    const predecessor = this.#records.get(predecessor_handoff_id);
+    if (!predecessor) fail('HANDOFF_NOT_FOUND', 'predecessor handoff is not registered');
+    if (predecessor.status !== 'active') fail('HANDOFF_NOT_ACTIVE', 'only an active handoff can be rebased');
+    const validated = validateSealedHandoff(successor);
+    const lineage = validated.lineage;
+    if (!lineage || lineage.kind !== 'rebase' || lineage.supersedes_handoff_id !== predecessor.handoff.handoff_id || lineage.supersedes_version !== predecessor.handoff.version || lineage.supersedes_manifest_digest !== predecessor.handoff.seal.manifest_digest) {
+      fail('INVALID_REBASE_LINEAGE', 'successor must explicitly reference the exact predecessor');
+    }
+    if (validated.project_id !== predecessor.handoff.project_id) fail('PROJECT_LINEAGE_MISMATCH', 'successor project_id must match predecessor');
+    this.register(validated);
+    predecessor.status = 'superseded';
+    predecessor.successor_handoff_id = validated.handoff_id;
+    return validated;
+  }
+
+  cancel({ handoff_id, cancellation_id, event_version = 1, cancelled_by, cancelled_at, reason_ref }) {
+    assertString(handoff_id, 'INVALID_HANDOFF_ID', 'handoff_id');
+    const record = this.#records.get(handoff_id);
+    if (!record) fail('HANDOFF_NOT_FOUND', 'handoff is not registered');
+    if (record.status === 'superseded') fail('HANDOFF_SUPERSEDED', 'superseded handoff cannot be cancelled');
+    if (record.status === 'cancelled') return record.cancellation;
+    assertString(cancellation_id, 'INVALID_CANCELLATION', 'cancellation_id');
+    if (event_version !== 1) fail('UNSUPPORTED_CANCELLATION_EVENT_VERSION', 'event_version must be 1');
+    assertString(cancelled_by, 'INVALID_CANCELLATION', 'cancelled_by');
+    assertTimestamp(cancelled_at, 'INVALID_CANCELLATION', 'cancelled_at');
+    assertImmutableRef(reason_ref, 'INVALID_CANCELLATION', 'reason_ref');
+    record.status = 'cancelled';
+    record.cancellation = deepFreeze(canonicalize({
+      event_id: cancellation_id,
+      event_type: 'handoff_cancelled',
+      event_version,
+      handoff_id,
+      manifest_digest: record.handoff.seal.manifest_digest,
+      lineage: {
+        kind: 'cancellation',
+        supersedes_handoff_id: record.handoff.handoff_id,
+        supersedes_version: record.handoff.version,
+        supersedes_manifest_digest: record.handoff.seal.manifest_digest,
+      },
+      cancelled_by,
+      cancelled_at,
+      reason_ref,
+    }));
+    return record.cancellation;
+  }
+
+  createAttempt({ handoff_id, task_id, attempt_id, completed_task_ids = [], git_dir }) {
+    const record = this.#records.get(handoff_id);
+    if (!record) fail('HANDOFF_NOT_FOUND', 'handoff is not registered');
+    if (this.#attempts.has(attempt_id)) fail('ATTEMPT_ALREADY_EXISTS', 'attempt_id is already registered');
+    const attempt = createAttemptBinding({ handoff: record.handoff, task_id, attempt_id, completed_task_ids, git_dir, status: record.status });
+    this.#attempts.set(attempt_id, attempt);
+    return attempt;
+  }
+
+  getAttemptForRecovery(attempt_id) {
+    const attempt = this.#attempts.get(attempt_id);
+    if (!attempt) fail('ATTEMPT_NOT_FOUND', 'attempt is not registered');
+    const record = this.#records.get(attempt.handoff_id);
+    validateAttemptBinding({ attempt, handoff: record.handoff });
+    return attempt;
+  }
+
+  getStatus(handoff_id) {
+    const record = this.#records.get(handoff_id);
+    if (!record) fail('HANDOFF_NOT_FOUND', 'handoff is not registered');
+    return record.status;
+  }
+}

package/node_modules/@chati/provider-registry/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@chati/provider-registry",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": "./src/index.js",
+  "dependencies": {
+    "@chati/core": "0.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}