kld-sdd 2.5.1 → 2.6.0

package/skywalk-sdd/ontology/runtime.cjs

@@ -0,0 +1,466 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { SCHEMA_VERSION, normalizeProfile } = require('./schema.cjs');
+const { safeChangeName, parseChangeArtifacts } = require('./artifact-parser.cjs');
+const { normalizeFacts } = require('./normalizer.cjs');
+const { validateTraceability } = require('./traceability-validator.cjs');
+const { buildIdentityCatalog } = require('./identity-index.cjs');
+const { buildEffectiveGraph } = require('./effective-graph.cjs');
+const { generateUuidV7 } = require('./id.cjs');
+const {
+  WORKING_ARTIFACT_SCHEMA_VERSION,
+  ARTIFACT_INDEX_SCHEMA_VERSION,
+  buildWorkingArtifactFacts,
+} = require('./working-artifacts.cjs');
+const {
+  acquireChangeLock,
+  assertChangeLock,
+  releaseChangeLock,
+} = require('./change-lock.cjs');
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function resolveChangeDir(projectRoot, changeName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  return path.join(root, 'openspec', 'changes', safeChangeName(changeName));
+}
+
+function changeOntologyPaths(projectRoot, changeName) {
+  const changeDir = resolveChangeDir(projectRoot, changeName);
+  return {
+    changeDir,
+    working: path.join(changeDir, 'working-ontology.json'),
+    diagnostics: path.join(changeDir, 'diagnostics.json'),
+    fileIndex: path.join(changeDir, 'file-index.json'),
+    artifactIndex: path.join(changeDir, 'artifact-index.json'),
+    artifactDir: path.join(changeDir, 'artifacts'),
+  };
+}
+
+function statePaths(projectRoot, changeName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const safeName = safeChangeName(changeName);
+  const dir = path.join(root, 'skywalk-sdd', 'state', 'ontology', safeName);
+  return {
+    dir,
+    current: path.join(dir, 'current.json'),
+  };
+}
+
+function serialized(value) {
+  return JSON.stringify(value, null, 2) + '\n';
+}
+
+function atomicWriteIfChanged(filePath, value) {
+  const content = typeof value === 'string' ? value : serialized(value);
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(tempPath, content, 'utf8');
+  fs.renameSync(tempPath, filePath);
+  return true;
+}
+
+function stateError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+function readJson(filePath, code) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw stateError(code, `无法读取状态文件 ${filePath}: ${error.message}`);
+  }
+}
+
+function readRevisionBundle(paths, expectedRevision) {
+  for (const filePath of [paths.working, paths.diagnostics, paths.fileIndex, paths.artifactIndex]) {
+    if (!fs.existsSync(filePath)) {
+      throw stateError('SEM_STATE_INCOMPLETE', `revision ${expectedRevision} 缺少 ${path.basename(filePath)}`);
+    }
+  }
+  const working = readJson(paths.working, 'SEM_STATE_CORRUPT');
+  const diagnostics = readJson(paths.diagnostics, 'SEM_STATE_CORRUPT');
+  const fileIndex = readJson(paths.fileIndex, 'SEM_STATE_CORRUPT');
+  const artifactIndex = readJson(paths.artifactIndex, 'SEM_STATE_CORRUPT');
+  const revisions = [working.revision, diagnostics.revision, fileIndex.revision, artifactIndex.revision];
+  if (revisions.some((revision) => revision !== expectedRevision)) {
+    throw stateError(
+      'SEM_STATE_REVISION_MISMATCH',
+      `current=${expectedRevision}，working/diagnostics/file-index=${revisions.join('/')}`,
+    );
+  }
+  for (const artifact of artifactIndex.artifacts || []) {
+    const artifactPath = path.resolve(paths.changeDir, artifact.json_path || '');
+    const artifactRelative = path.relative(paths.changeDir, artifactPath);
+    if (
+      !artifact.json_path
+      || artifactRelative.startsWith('..')
+      || path.isAbsolute(artifactRelative)
+      || !fs.existsSync(artifactPath)
+    ) {
+      throw stateError(
+        'SEM_STATE_INCOMPLETE',
+        `revision ${expectedRevision} 缺少 Artifact JSON: ${artifact.json_path || '(empty)'}`,
+      );
+    }
+    const artifactFacts = readJson(artifactPath, 'SEM_STATE_CORRUPT');
+    if (artifactFacts.revision !== expectedRevision) {
+      throw stateError(
+        'SEM_STATE_REVISION_MISMATCH',
+        `current=${expectedRevision}，artifact=${artifactFacts.revision}`,
+      );
+    }
+  }
+  return { working, diagnostics, fileIndex, artifactIndex };
+}
+
+function pruneStaleArtifacts(changeDir, artifactIndex) {
+  const artifactRoot = path.join(changeDir, 'artifacts');
+  if (!fs.existsSync(artifactRoot)) return;
+  const allowed = new Set((artifactIndex.artifacts || []).map((artifact) => artifact.json_path));
+  const stale = [];
+  (function walk(currentDir, relativePrefix) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.name.endsWith('.ontology.json')) continue;
+      const jsonPath = `artifacts/${relativePath.replace(/\\/g, '/')}`;
+      if (!allowed.has(jsonPath)) stale.push(absolutePath);
+    }
+  }(artifactRoot, ''));
+  for (const filePath of stale) {
+    fs.rmSync(filePath, { force: true });
+  }
+  (function removeEmptyDirs(currentDir) {
+    if (!fs.existsSync(currentDir) || currentDir === artifactRoot) return;
+    const entries = fs.readdirSync(currentDir);
+    for (const entry of entries) {
+      const child = path.join(currentDir, entry);
+      if (fs.statSync(child).isDirectory()) removeEmptyDirs(child);
+    }
+    if (fs.readdirSync(currentDir).length === 0) fs.rmdirSync(currentDir);
+  }(artifactRoot));
+}
+
+function commitRevision(projectRoot, changeName, result, lock) {
+  assertChangeLock(lock);
+  const basePaths = statePaths(projectRoot, changeName);
+  const paths = changeOntologyPaths(projectRoot, changeName);
+  fs.mkdirSync(basePaths.dir, { recursive: true });
+  fs.mkdirSync(paths.changeDir, { recursive: true });
+
+  if (fs.existsSync(paths.working)) {
+    const existing = readJson(paths.working, 'SEM_STATE_CORRUPT');
+    if (existing.revision === result.revision) {
+      readRevisionBundle(paths, result.revision);
+      const artifactIndex = readJson(paths.artifactIndex, 'SEM_STATE_CORRUPT');
+      return {
+        changed: false,
+        paths: {
+          ...paths,
+          current: basePaths.current,
+          artifactFacts: (artifactIndex.artifacts || []).map((artifact) => (
+            path.join(paths.changeDir, artifact.json_path)
+          )),
+        },
+      };
+    }
+  }
+
+  const stagingDir = path.join(basePaths.dir, `.${result.revision}.${lock.token}.staging`);
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+  fs.mkdirSync(stagingDir, { recursive: true });
+  const artifactBundle = buildWorkingArtifactFacts(result);
+  const stagedFiles = {
+    working: path.join(stagingDir, 'working-ontology.json'),
+    diagnostics: path.join(stagingDir, 'diagnostics.json'),
+    fileIndex: path.join(stagingDir, 'file-index.json'),
+    artifactIndex: path.join(stagingDir, 'artifact-index.json'),
+  };
+  fs.writeFileSync(stagedFiles.working, serialized(result.state), 'utf8');
+  fs.writeFileSync(stagedFiles.diagnostics, serialized({
+    schema_version: SCHEMA_VERSION,
+    change: changeName,
+    profile: result.profile,
+    valid: result.valid,
+    revision: result.revision,
+    diagnostics: result.diagnostics,
+  }), 'utf8');
+  fs.writeFileSync(stagedFiles.fileIndex, serialized(result.fileIndex), 'utf8');
+  fs.writeFileSync(stagedFiles.artifactIndex, serialized(artifactBundle.index), 'utf8');
+  for (const artifactFile of artifactBundle.files) {
+    const targetPath = path.join(stagingDir, artifactFile.path);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, serialized(artifactFile.value), 'utf8');
+  }
+  assertChangeLock(lock);
+  readRevisionBundle({
+    changeDir: stagingDir,
+    working: stagedFiles.working,
+    diagnostics: stagedFiles.diagnostics,
+    fileIndex: stagedFiles.fileIndex,
+    artifactIndex: stagedFiles.artifactIndex,
+  }, result.revision);
+
+  atomicWriteIfChanged(paths.working, fs.readFileSync(stagedFiles.working, 'utf8'));
+  atomicWriteIfChanged(paths.diagnostics, fs.readFileSync(stagedFiles.diagnostics, 'utf8'));
+  atomicWriteIfChanged(paths.fileIndex, fs.readFileSync(stagedFiles.fileIndex, 'utf8'));
+  atomicWriteIfChanged(paths.artifactIndex, fs.readFileSync(stagedFiles.artifactIndex, 'utf8'));
+  for (const artifactFile of artifactBundle.files) {
+    const stagedPath = path.join(stagingDir, artifactFile.path);
+    atomicWriteIfChanged(path.join(paths.changeDir, artifactFile.path), fs.readFileSync(stagedPath, 'utf8'));
+  }
+  pruneStaleArtifacts(paths.changeDir, artifactBundle.index);
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+
+  const pointer = {
+    schema_version: 'kld-sdd-state-pointer/v1',
+    change: safeChangeName(changeName),
+    revision: result.revision,
+    change_dir: path.relative(path.resolve(projectRoot), paths.changeDir).replace(/\\/g, '/'),
+    artifact_index: 'artifact-index.json',
+  };
+  assertChangeLock(lock);
+  const changed = atomicWriteIfChanged(basePaths.current, pointer);
+  return {
+    changed,
+    paths: {
+      ...paths,
+      current: basePaths.current,
+      artifactFacts: artifactBundle.index.artifacts.map((artifact) => (
+        path.join(paths.changeDir, artifact.json_path)
+      )),
+    },
+  };
+}
+
+function scanChange(projectRoot, changeName, options = {}) {
+  const parsed = parseChangeArtifacts(projectRoot, changeName, options);
+  const facts = normalizeFacts(parsed);
+  const profile = normalizeProfile(options.profile || 'auto', facts.profile);
+  const identityCatalog = buildIdentityCatalog(projectRoot, { excludeChangeDir: parsed.changeDir });
+  const identityHistory = identityCatalog.records;
+  const identityHistoryHash = sha256(JSON.stringify({
+    records: identityCatalog.records,
+    diagnostics: identityCatalog.diagnostics,
+  }));
+  const effectiveGraph = buildEffectiveGraph(facts, identityCatalog);
+  const validationFacts = {
+    ...facts,
+    diagnostics: [
+      ...(facts.diagnostics || []),
+      ...(identityCatalog.diagnostics || []),
+      ...(effectiveGraph.resolution_diagnostics || []),
+    ],
+  };
+  const validation = validateTraceability(validationFacts, {
+    profile,
+    identityHistory,
+    effectiveGraph,
+  });
+  const reviewStatus = options.markPending && validation.valid ? 'pending' : 'draft';
+  const revisionInput = {
+    schema_version: SCHEMA_VERSION,
+    artifact_schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+    artifact_index_schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
+    change: changeName,
+    profile,
+    files: facts.files,
+    entities: effectiveGraph.effective_entities,
+    relations: effectiveGraph.effective_relations,
+    inherited_references: facts.inherited_references,
+    inherited_relations: facts.inherited_relations,
+    inherited_resolutions: effectiveGraph.inherited_resolutions,
+    diagnostics: validation.diagnostics,
+    identity_history_hash: identityHistoryHash,
+    review_status: reviewStatus,
+  };
+  const revision = sha256(JSON.stringify(revisionInput));
+  const state = JSON.parse(JSON.stringify({
+    schema_version: SCHEMA_VERSION,
+    artifact_schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+    artifact_index_schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
+    change: changeName,
+    change_id: facts.change_id,
+    profile,
+    review_status: reviewStatus,
+    valid: validation.valid,
+    revision,
+    identity_history_hash: identityHistoryHash,
+    artifacts: facts.artifacts,
+    files: facts.files,
+    facts_hash: facts.facts_hash,
+    entities: effectiveGraph.effective_entities,
+    relations: effectiveGraph.effective_relations,
+    current_entities: facts.entities,
+    current_relations: facts.relations,
+    inherited_references: facts.inherited_references,
+    inherited_relations: facts.inherited_relations,
+    inherited_resolutions: effectiveGraph.inherited_resolutions,
+  }));
+  return {
+    profile,
+    valid: validation.valid,
+    revision,
+    state,
+    diagnostics: validation.diagnostics,
+    counts: validation.counts,
+    identityHistoryCount: identityHistory.length,
+    fileIndex: {
+      schema_version: SCHEMA_VERSION,
+      change: changeName,
+      files: facts.files,
+      revision,
+    },
+  };
+}
+
+function reconcileChange(projectRoot, changeName, options = {}) {
+  const execute = (lock) => {
+    assertChangeLock(lock);
+    const result = scanChange(projectRoot, changeName, options);
+    const committed = commitRevision(projectRoot, changeName, result, lock);
+    return {
+      ...result,
+      changed: committed.changed,
+      paths: committed.paths,
+    };
+  };
+
+  if (options.lock) return execute(options.lock);
+  const lock = acquireChangeLock(projectRoot, changeName, options.lockOptions);
+  try {
+    return execute(lock);
+  } finally {
+    releaseChangeLock(lock);
+  }
+}
+
+function readWorkingState(projectRoot, changeName) {
+  const basePaths = statePaths(projectRoot, changeName);
+  const paths = changeOntologyPaths(projectRoot, changeName);
+  if (fs.existsSync(basePaths.current)) {
+    const pointer = readJson(basePaths.current, 'SEM_STATE_POINTER_CORRUPT');
+    if (!pointer.revision || pointer.change !== safeChangeName(changeName)) {
+      throw stateError('SEM_STATE_POINTER_CORRUPT', `current.json 不属于 Change ${changeName}`);
+    }
+    return readRevisionBundle(paths, pointer.revision).working;
+  }
+  if (!fs.existsSync(paths.working)) return null;
+  const working = readJson(paths.working, 'SEM_STATE_CORRUPT');
+  readRevisionBundle(paths, working.revision);
+  return working;
+}
+
+function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState) {
+  const targetDir = path.resolve(archiveDir);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`归档源目录不存在: ${targetDir}`);
+  }
+  const actualFacts = normalizeFacts(parseChangeArtifacts(projectRoot, changeName, {
+    changeDir: targetDir,
+    persistStructuralIdentities: false,
+  }));
+  const scanned = inputState ? null : scanChange(projectRoot, changeName, {
+    changeDir: targetDir,
+    profile: 'auto',
+    markPending: true,
+    persistStructuralIdentities: false,
+  });
+  const state = inputState || (scanned && scanned.state) || readWorkingState(projectRoot, changeName);
+  if (!state) {
+    throw new Error(`不存在工作态本体实例: ${changeName}`);
+  }
+  if (!state.valid) {
+    throw new Error(`工作态本体仍有阻断错误，不能归档: ${changeName}`);
+  }
+  if (!state.facts_hash || state.facts_hash !== actualFacts.facts_hash) {
+    throw new Error(`归档正文与待确认本体事实不一致: ${changeName}`);
+  }
+  const artifactIndexPath = path.join(targetDir, 'artifact-index.json');
+  if (!fs.existsSync(artifactIndexPath)) {
+    throw new Error(`归档目录缺少 artifact-index.json: ${targetDir}`);
+  }
+  const artifactIndex = readJson(artifactIndexPath, 'SEM_STATE_CORRUPT');
+  if (artifactIndex.revision !== state.revision) {
+    throw new Error(`归档 artifact-index 与待确认 revision 不一致: ${changeName}`);
+  }
+  const snapshotId = `SNAP-${sha256(`${changeName}:${state.revision}`).slice(0, 16).toUpperCase()}`;
+  const targetPath = path.join(targetDir, 'archive-ontology.json');
+  const previous = fs.existsSync(targetPath)
+    ? JSON.parse(fs.readFileSync(targetPath, 'utf8'))
+    : null;
+  const previousEntity = previous && previous.source_revision === state.revision
+    ? (previous.entities || []).find((entity) => entity.type === 'OntologySnapshot')
+    : null;
+  const snapshotEntity = {
+    id: snapshotId,
+    anchor_id: snapshotId,
+    type: 'OntologySnapshot',
+    entity_id: previousEntity && previousEntity.entity_id
+      ? previousEntity.entity_id
+      : generateUuidV7(),
+    version_id: previousEntity && previousEntity.version_id
+      ? previousEntity.version_id
+      : generateUuidV7(),
+    predecessor_version_id: null,
+    delta_state: 'added',
+    generation_role: 'produced',
+    content_hash: sha256(JSON.stringify({
+      change: changeName,
+      source_revision: state.revision,
+      facts_hash: state.facts_hash,
+    })),
+    attributes: {
+      source_revision: state.revision,
+      facts_hash: state.facts_hash,
+    },
+    source: {
+      artifact_type: 'snapshot',
+      file: 'archive-ontology.json',
+      line: 1,
+      anchor_id: snapshotId,
+    },
+  };
+  const snapshot = {
+    ...state,
+    review_status: 'confirmed',
+    snapshot_id: snapshotId,
+    snapshot_entity_id: snapshotEntity.entity_id,
+    source_revision: state.revision,
+    confirmed_at: new Date().toISOString(),
+    entities: [
+      ...(state.entities || []).filter((entity) => entity.type !== 'OntologySnapshot'),
+      snapshotEntity,
+    ],
+  };
+  atomicWriteIfChanged(targetPath, snapshot);
+  return snapshot;
+}
+
+module.exports = {
+  resolveChangeDir,
+  changeOntologyPaths,
+  statePaths,
+  atomicWriteIfChanged,
+  readRevisionBundle,
+  commitRevision,
+  scanChange,
+  reconcileChange,
+  readWorkingState,
+  createArchiveSnapshot,
+};

package/skywalk-sdd/ontology/schema.cjs

@@ -0,0 +1,139 @@
+'use strict';
+
+const SCHEMA_VERSION = 'kld-sdd-ontology/v2';
+
+const ENTITY_TYPES = Object.freeze([
+  'Change',
+  'Capability',
+  'SpecificationStatement',
+  'AcceptanceCriterion',
+  'Constraint',
+  'DesignElement',
+  'Task',
+  'Artifact',
+  'DocumentSection',
+  'OntologySnapshot',
+]);
+
+const ID_PREFIX_TYPES = Object.freeze({
+  CHG: 'Change',
+  CAP: 'Capability',
+  STMT: 'SpecificationStatement',
+  AC: 'AcceptanceCriterion',
+  CON: 'Constraint',
+  DES: 'DesignElement',
+  TASK: 'Task',
+  ART: 'Artifact',
+  SEC: 'DocumentSection',
+  SNAP: 'OntologySnapshot',
+});
+
+const RELATION_TYPES = Object.freeze({
+  contains: Object.freeze({
+    domain: Object.freeze(['Change', 'Capability']),
+    range: Object.freeze(['Capability', 'SpecificationStatement']),
+    pairs: Object.freeze([
+      Object.freeze(['Change', 'Capability']),
+      Object.freeze(['Capability', 'SpecificationStatement']),
+    ]),
+  }),
+  acceptedBy: Object.freeze({
+    domain: Object.freeze(['SpecificationStatement']),
+    range: Object.freeze(['AcceptanceCriterion']),
+  }),
+  constrainedBy: Object.freeze({
+    domain: Object.freeze(['SpecificationStatement']),
+    range: Object.freeze(['Constraint']),
+  }),
+  realizes: Object.freeze({
+    domain: Object.freeze(['DesignElement']),
+    range: Object.freeze(['SpecificationStatement']),
+  }),
+  implements: Object.freeze({
+    domain: Object.freeze(['Task']),
+    range: Object.freeze(['DesignElement']),
+  }),
+  covers: Object.freeze({
+    domain: Object.freeze(['Task']),
+    range: Object.freeze(['SpecificationStatement']),
+  }),
+  dependsOn: Object.freeze({
+    domain: Object.freeze(['Task']),
+    range: Object.freeze(['Task']),
+  }),
+  declares: Object.freeze({
+    domain: Object.freeze(['Artifact']),
+    range: Object.freeze(ENTITY_TYPES.filter((type) => !['Artifact', 'DocumentSection', 'OntologySnapshot'].includes(type))),
+  }),
+  sourcedFrom: Object.freeze({
+    domain: Object.freeze(ENTITY_TYPES.filter((type) => !['DocumentSection', 'OntologySnapshot'].includes(type))),
+    range: Object.freeze(['DocumentSection']),
+  }),
+});
+
+const VALID_PROFILES = Object.freeze(['simple', 'full', 'strict']);
+
+const DIAGNOSTIC_CODES = Object.freeze({
+  ID_MISSING: 'SEM_ID_MISSING',
+  ID_INVALID: 'SEM_ID_INVALID',
+  ID_DUPLICATE: 'SEM_ID_DUPLICATE',
+  ARTIFACT_MISSING: 'SEM_ARTIFACT_MISSING',
+  PROFILE_INVALID: 'SEM_PROFILE_INVALID',
+  PROFILE_INFERRED: 'SEM_PROFILE_INFERRED',
+  RELATION_UNKNOWN: 'SEM_RELATION_UNKNOWN',
+  RELATION_TARGET_MISSING: 'SEM_RELATION_TARGET_MISSING',
+  RELATION_DOMAIN_RANGE: 'SEM_RELATION_DOMAIN_RANGE',
+  STMT_WITHOUT_AC: 'SEM_TRACE_STMT_WITHOUT_AC',
+  STMT_WITHOUT_DESIGN: 'SEM_TRACE_STMT_WITHOUT_DESIGN',
+  DESIGN_WITHOUT_TASK: 'SEM_TRACE_DESIGN_WITHOUT_TASK',
+  TASK_DEPENDENCY_CYCLE: 'SEM_TASK_DEPENDENCY_CYCLE',
+  SOURCE_MISSING: 'SEM_SOURCE_MISSING',
+  UUID_MISSING: 'SEM_UUID_MISSING',
+  UUID_INVALID: 'SEM_UUID_INVALID',
+  DELTA_STATE_INVALID: 'SEM_DELTA_STATE_INVALID',
+  ENTITY_IDENTITY_CONFLICT: 'SEM_ENTITY_IDENTITY_CONFLICT',
+  VERSION_IDENTITY_CONFLICT: 'SEM_VERSION_IDENTITY_CONFLICT',
+  VERSION_LINEAGE_MISSING: 'SEM_VERSION_LINEAGE_MISSING',
+  VERSION_LINEAGE_CONFLICT: 'SEM_VERSION_LINEAGE_CONFLICT',
+  INHERITED_SOURCE_MISMATCH: 'SEM_INHERITED_SOURCE_MISMATCH',
+  RELATION_ASSERTION_INVALID: 'SEM_RELATION_ASSERTION_INVALID',
+  RELATION_TARGET_REMOVED: 'SEM_RELATION_TARGET_REMOVED',
+  AC_WITHOUT_STMT: 'SEM_TRACE_AC_WITHOUT_STMT',
+  TASK_WITHOUT_UPSTREAM: 'SEM_TRACE_TASK_WITHOUT_UPSTREAM',
+  CAPABILITY_BOUNDARY: 'SEM_CAPABILITY_BOUNDARY',
+  ARCHIVE_NOT_CONFIRMED: 'SEM_ARCHIVE_NOT_CONFIRMED',
+  ARCHIVE_REVISION_MISMATCH: 'SEM_ARCHIVE_REVISION_MISMATCH',
+  INHERITED_RELATION_MISSING: 'SEM_INHERITED_RELATION_MISSING',
+});
+
+function normalizeProfile(profile, inferredProfile = 'simple') {
+  const normalized = String(profile || 'auto').trim().toLowerCase();
+  if (normalized === 'auto') {
+    return VALID_PROFILES.includes(inferredProfile) ? inferredProfile : 'simple';
+  }
+  if (!VALID_PROFILES.includes(normalized)) {
+    throw new Error(`不支持的语义校验 profile: ${profile}`);
+  }
+  return normalized;
+}
+
+function entityTypeForId(entityId) {
+  const prefix = String(entityId || '').trim().toUpperCase().split('-')[0];
+  return ID_PREFIX_TYPES[prefix] || null;
+}
+
+function relationDefinition(type) {
+  return RELATION_TYPES[type] || null;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  ENTITY_TYPES,
+  ID_PREFIX_TYPES,
+  RELATION_TYPES,
+  VALID_PROFILES,
+  DIAGNOSTIC_CODES,
+  normalizeProfile,
+  entityTypeForId,
+  relationDefinition,
+};

package/skywalk-sdd/ontology/structural-identity.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { SCHEMA_VERSION } = require('./schema.cjs');
+const { generateUuidV7, isValidUuidV7 } = require('./id.cjs');
+
+const REGISTRY_FILE = 'ontology-identities.json';
+
+function registryPath(changeDir) {
+  return path.join(path.resolve(changeDir), REGISTRY_FILE);
+}
+
+function readRegistry(changeDir) {
+  const filePath = registryPath(changeDir);
+  if (!fs.existsSync(filePath)) {
+    return { schema_version: SCHEMA_VERSION, identities: {} };
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return {
+      schema_version: SCHEMA_VERSION,
+      identities: parsed && typeof parsed.identities === 'object' ? parsed.identities : {},
+    };
+  } catch (error) {
+    throw new Error(`结构身份 sidecar 非法: ${filePath}: ${error.message}`);
+  }
+}
+
+function writeRegistry(changeDir, registry) {
+  const filePath = registryPath(changeDir);
+  const content = `${JSON.stringify(registry, null, 2)}\n`;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) return false;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tempPath, content, 'utf8');
+  fs.renameSync(tempPath, filePath);
+  return true;
+}
+
+function ensureStructuralIdentities(changeDir, descriptors, options = {}) {
+  const registry = readRegistry(changeDir);
+  let changed = false;
+  for (const descriptor of descriptors) {
+    const existing = registry.identities[descriptor.key];
+    if (existing) {
+      if (existing.anchor_id !== descriptor.anchor_id || existing.type !== descriptor.type
+        || !isValidUuidV7(existing.entity_id) || !isValidUuidV7(existing.version_id)) {
+        throw new Error(`结构身份 sidecar 与当前结构冲突: ${descriptor.key}`);
+      }
+      if (existing.content_hash !== descriptor.content_hash) {
+        existing.content_hash = descriptor.content_hash;
+        changed = true;
+      }
+      continue;
+    }
+    if (options.persist === false) continue;
+    registry.identities[descriptor.key] = {
+      anchor_id: descriptor.anchor_id,
+      type: descriptor.type,
+      entity_id: generateUuidV7(),
+      version_id: generateUuidV7(),
+      content_hash: descriptor.content_hash,
+    };
+    changed = true;
+  }
+  if (changed && options.persist !== false) writeRegistry(changeDir, registry);
+  return registry;
+}
+
+module.exports = {
+  REGISTRY_FILE,
+  registryPath,
+  readRegistry,
+  writeRegistry,
+  ensureStructuralIdentities,
+};