@thinkingai/ae-cli 6.1.17 → 6.1.19

package/dist/project-semantic-BQ4MPUS5.js

@@ -0,0 +1,1115 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import {
+  assertOutputPathAvailable,
+  downloadAnalysisArtifact,
+  withAsyncArtifactLifecycle
+} from "./chunk-S5PONFBM.js";
+import {
+  createCapabilityCommand
+} from "./chunk-DKEXH6Q5.js";
+import {
+  registerCapabilityGatewayRoute,
+  resolveGatewayDomain
+} from "./chunk-TKHSULJT.js";
+import "./chunk-KEWVSO64.js";
+import {
+  CapabilityGatewayError,
+  buildCapabilityGatewayUrl,
+  executeCapabilityWithEnvelope
+} from "./chunk-GJXRF7Y6.js";
+import "./chunk-Y74WTIKJ.js";
+import "./chunk-RWXIXOZG.js";
+import "./chunk-O6K2ODUE.js";
+import "./chunk-KZ6ZHF5J.js";
+import "./chunk-533JK3YX.js";
+import "./chunk-FR2EDAQM.js";
+
+// src/commands/project-semantic/shared.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+function createProjectSemanticCommand(config) {
+  return createCapabilityCommand({
+    ...config,
+    cliService: "project-semantic",
+    gatewayDomain: "analysis"
+  });
+}
+function optionalString(ctx, name) {
+  const value = ctx.str(name);
+  return value === "" ? void 0 : value;
+}
+function optionalNumber(ctx, name) {
+  return ctx.optionalNum(name);
+}
+function optionalJson(ctx, name) {
+  if (ctx.str(name) === "") {
+    return void 0;
+  }
+  return ctx.json(name);
+}
+function compactInput(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+function readJsonFile(file, maxBytes = 1024 * 1024) {
+  const text = readFileSync(resolve(file), "utf8");
+  if (Buffer.byteLength(text, "utf8") > maxBytes) {
+    throw new Error(`JSON file must not exceed ${maxBytes} bytes.`);
+  }
+  return JSON.parse(text);
+}
+function arrayValue(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON array.`);
+  }
+  return value;
+}
+
+// src/commands/project-semantic/list.ts
+var projectSemanticList = createProjectSemanticCommand({
+  resource: "",
+  command: "list",
+  capabilityId: "business_semantics.catalog.get",
+  description: "List project semantics by lifecycle status; defaults to enabled semantics for consumption.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "status",
+      type: "string",
+      desc: "Lifecycle status: active or disabled. Defaults to active."
+    }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    const status = optionalString(ctx, "status");
+    if (status && !["active", "disabled"].includes(status.toLowerCase())) {
+      throw new Error("--status must be active or disabled.");
+    }
+  },
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    status: optionalString(ctx, "status")?.toLowerCase()
+  })
+});
+
+// src/commands/project-semantic/get.ts
+var projectSemanticGet = createProjectSemanticCommand({
+  resource: "",
+  command: "get",
+  capabilityId: "business_semantics.entry.get",
+  description: "Get one enabled project semantic; use --mark-used only after adopting it.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "id", type: "string", required: true, desc: "Semantic ID returned by project-semantic list." },
+    { name: "mark-used", type: "boolean", desc: "Count this project semantic as used by CLI or Agent." }
+  ],
+  risk: "read",
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id"),
+    id: ctx.str("id"),
+    mark_used: ctx.bool("mark-used")
+  })
+});
+
+// src/commands/project-semantic/enable.ts
+var projectSemanticEnable = createProjectSemanticCommand({
+  resource: "",
+  command: "enable",
+  capabilityId: "business_semantics.entry.enable",
+  description: "Enable one disabled project semantic. Enabled semantics are immediately used by CLI and Agent.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "semantic-id",
+      type: "string",
+      required: true,
+      desc: "Exact disabled semantic ID to enable."
+    },
+    {
+      name: "expected-version",
+      type: "number",
+      required: true,
+      desc: "Latest semantic revision.",
+      min: 1
+    },
+    {
+      name: "reason",
+      type: "string",
+      required: true,
+      desc: "Business reason for enabling."
+    },
+    {
+      name: "request-id",
+      type: "string",
+      desc: "Optional idempotency key; generated when omitted.",
+      maxLength: 128
+    }
+  ],
+  risk: "high-risk-write",
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    semantic_id: ctx.str("semantic-id"),
+    expected_version: ctx.num("expected-version"),
+    reason: ctx.str("reason"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+
+// src/commands/project-semantic/disable.ts
+var projectSemanticDisable = createProjectSemanticCommand({
+  resource: "",
+  command: "disable",
+  capabilityId: "business_semantics.entry.disable",
+  description: "Disable one active project semantic in one step. Disabled semantics stop being used by CLI and Agent.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "semantic-id", type: "string", required: true, desc: "Exact semantic ID to disable." },
+    { name: "expected-version", type: "number", required: true, desc: "Latest semantic revision.", min: 1 },
+    { name: "reason", type: "string", required: true, desc: "Business reason for disabling." },
+    { name: "request-id", type: "string", desc: "Optional idempotency key; generated when omitted.", maxLength: 128 }
+  ],
+  risk: "high-risk-write",
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    semantic_id: ctx.str("semantic-id"),
+    expected_version: ctx.num("expected-version"),
+    reason: ctx.str("reason"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+
+// src/commands/project-semantic/delete.ts
+var projectSemanticDelete = createProjectSemanticCommand({
+  resource: "",
+  command: "delete",
+  capabilityId: "business_semantics.entry.delete",
+  description: "Physically delete one disabled project semantic and its private revisions. Future scans may recommend it again.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "semantic-id",
+      type: "string",
+      required: true,
+      desc: "Exact semantic ID to delete."
+    },
+    {
+      name: "expected-version",
+      type: "number",
+      required: true,
+      desc: "Latest semantic revision.",
+      min: 1
+    },
+    {
+      name: "reason",
+      type: "string",
+      required: true,
+      desc: "Business reason for physical deletion."
+    },
+    {
+      name: "request-id",
+      type: "string",
+      desc: "Optional request ID; generated when omitted.",
+      maxLength: 128
+    }
+  ],
+  risk: "high-risk-write",
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    semantic_id: ctx.str("semantic-id"),
+    expected_version: ctx.num("expected-version"),
+    reason: ctx.str("reason"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+
+// src/commands/project-semantic/delete-impact.ts
+var projectSemanticDeleteImpact = createProjectSemanticCommand({
+  resource: "",
+  command: "delete-impact",
+  capabilityId: "business_semantics.entry.delete_impact",
+  description: "Preview rows affected by physically deleting one disabled project semantic.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "semantic-id",
+      type: "string",
+      required: true,
+      desc: "Exact semantic ID to inspect."
+    }
+  ],
+  risk: "read",
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id"),
+    semantic_id: ctx.str("semantic-id")
+  })
+});
+
+// src/commands/project-semantic/asset-package/materializer.ts
+import { createHash, randomBytes } from "crypto";
+import { createReadStream } from "fs";
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import { createInterface } from "readline";
+import { createGunzip } from "zlib";
+import { basename, dirname, resolve as resolve2 } from "path";
+var MAX_COMPRESSED_BYTES = 64 * 1024 * 1024;
+var MAX_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+var MAX_RECORDS = 2e5;
+var SHA256_PATTERN = /^[0-9a-f]{64}$/;
+var REQUIRED_FILES = [
+  "manifest.json",
+  "indexes/work-units.jsonl",
+  "indexes/asset-directory.jsonl",
+  "indexes/coverage-batches.jsonl",
+  "indexes/definition-families.jsonl",
+  "indexes/governance-coverage.jsonl",
+  "catalog/published.jsonl",
+  "catalog/active-candidates.jsonl",
+  "catalog/rejected-candidates.jsonl"
+];
+async function preflightAssetPackageOutput(args) {
+  await assertOutputPathAvailable(args.output, args.force);
+}
+async function materializeProjectSemanticAssetPackage(args) {
+  const descriptor = packageDescriptor(args.finalDescriptor);
+  const output = resolve2(args.output);
+  const parent = dirname(output);
+  const nonce = `${process.pid}-${randomBytes(6).toString("hex")}`;
+  const staging = resolve2(parent, `.${basename(output)}.staging-${nonce}`);
+  const archive = resolve2(parent, `.${basename(output)}.archive-${nonce}.jsonl.gz`);
+  const backup = resolve2(parent, `.${basename(output)}.backup-${nonce}`);
+  let movedExisting = false;
+  await assertOutputPathAvailable(output, args.force, {
+    run_id: args.runId,
+    artifact_id: args.artifactId
+  });
+  await mkdir(parent, { recursive: true });
+  await mkdir(staging, { recursive: false });
+  try {
+    const download = await downloadAnalysisArtifact(
+      args.ctx.host(),
+      args.runId,
+      args.artifactId,
+      archive,
+      { signal: args.signal, ensureReady: false }
+    );
+    if (download.bytes > MAX_COMPRESSED_BYTES) {
+      throw packageError("Asset package archive exceeds 64 MiB.", "ASSET_PACKAGE_ARCHIVE_TOO_LARGE");
+    }
+    const materialized = await materializeArchive(archive, staging, descriptor);
+    if (args.force && await exists(output)) {
+      await rename(output, backup);
+      movedExisting = true;
+    }
+    await rename(staging, output);
+    if (movedExisting) {
+      await rm(backup, { recursive: true, force: true });
+      movedExisting = false;
+    }
+    return {
+      ...args.finalDescriptor,
+      output_path: output,
+      archive_bytes: download.bytes,
+      record_count: materialized.recordCount,
+      uncompressed_bytes: materialized.uncompressedBytes
+    };
+  } catch (error) {
+    if (movedExisting) {
+      await rename(backup, output).catch(() => void 0);
+    }
+    throw error;
+  } finally {
+    await rm(archive, { force: true }).catch(() => void 0);
+    await rm(staging, { recursive: true, force: true }).catch(() => void 0);
+    if (!movedExisting) {
+      await rm(backup, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+}
+async function materializeArchive(archive, staging, descriptor) {
+  const compressed = await stat(archive);
+  if (compressed.size > MAX_COMPRESSED_BYTES) {
+    throw packageError("Asset package archive exceeds 64 MiB.", "ASSET_PACKAGE_ARCHIVE_TOO_LARGE");
+  }
+  const digest = createHash("sha256");
+  const lines = createInterface({
+    input: createReadStream(archive).pipe(createGunzip()),
+    crlfDelay: Infinity
+  });
+  let recordCount = 0;
+  let uncompressedBytes = 0;
+  let manifest;
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    uncompressedBytes += Buffer.byteLength(line, "utf8") + 1;
+    if (uncompressedBytes > MAX_UNCOMPRESSED_BYTES) {
+      throw packageError(
+        "Asset package archive exceeds 512 MiB after decompression.",
+        "ASSET_PACKAGE_ARCHIVE_TOO_LARGE"
+      );
+    }
+    recordCount += 1;
+    if (recordCount > MAX_RECORDS) {
+      throw packageError("Asset package has too many records.", "ASSET_PACKAGE_RECORD_LIMIT_EXCEEDED");
+    }
+    digest.update(line, "utf8");
+    digest.update("\n", "utf8");
+    const record = parseRecord(line);
+    const target = resolveRecordPath(staging, record.path);
+    await mkdir(dirname(target), { recursive: true });
+    const content = `${JSON.stringify(record.content)}
+`;
+    if (record.append) {
+      await appendFile(target, content, "utf8");
+    } else {
+      await writeFile(target, content, { encoding: "utf8", flag: "wx" });
+    }
+    if (record.path === "manifest.json") {
+      manifest = asObject(record.content);
+    }
+  }
+  const actualHash = digest.digest("hex");
+  if (actualHash !== descriptor.snapshotHash) {
+    throw packageError(
+      `Asset package content hash mismatch: expected ${descriptor.snapshotHash}, received ${actualHash}.`,
+      "ASSET_PACKAGE_HASH_MISMATCH"
+    );
+  }
+  if (!manifest || !Number.isInteger(Number(manifest.project_id))) {
+    throw packageError("Asset package manifest is missing project identity.", "ASSET_PACKAGE_MANIFEST_INVALID");
+  }
+  if (manifest.schema_version !== "1.0") {
+    throw packageError("Project semantic asset package schema 1.0 is required.", "ASSET_PACKAGE_VERSION_MISMATCH");
+  }
+  for (const required of REQUIRED_FILES) {
+    if (!await exists(resolve2(staging, required))) {
+      throw packageError(`Asset package is missing required file ${required}.`, "ASSET_PACKAGE_MANIFEST_INVALID");
+    }
+  }
+  await verifyDetailLocators(staging);
+  await writeFile(resolve2(staging, ".asset-package.json"), JSON.stringify({
+    snapshot_id: descriptor.snapshotId,
+    snapshot_hash: descriptor.snapshotHash,
+    schema_version: "1.0",
+    company_id: Number(manifest.company_id),
+    project_id: Number(manifest.project_id),
+    record_count: recordCount,
+    asset_scope: typeof manifest.asset_scope === "string" ? manifest.asset_scope : "governed",
+    exported_asset_count: Number(manifest.exported_asset_count ?? manifest.authenticated_asset_count),
+    authenticated_asset_count: Number(manifest.authenticated_asset_count),
+    unauthenticated_asset_count: Number(manifest.unauthenticated_asset_count ?? 0),
+    truncated: Boolean(manifest.truncated),
+    counts: manifest.counts,
+    filter_policy: manifest.filter_policy
+  }, null, 2), "utf8");
+  return { recordCount, uncompressedBytes };
+}
+async function verifyDetailLocators(root) {
+  const directory = await readFile(resolve2(root, "indexes/asset-directory.jsonl"), "utf8");
+  for (const line of directory.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const row = asObject(JSON.parse(line));
+    if (!row || row.record_type === "header") continue;
+    const detail = await verifyContentLocator(root, row.detail_locator, "Detail");
+    await verifyContentLocator(root, detail.raw_locator, "Raw detail");
+  }
+}
+async function verifyContentLocator(root, value, label) {
+  const locator = asObject(value);
+  if (!locator || typeof locator.path !== "string" || typeof locator.content_hash !== "string" || !SHA256_PATTERN.test(locator.content_hash)) {
+    throw packageError(
+      `Asset package contains an invalid ${label.toLowerCase()} locator.`,
+      "ASSET_PACKAGE_MANIFEST_INVALID"
+    );
+  }
+  const target = resolveRecordPath(root, locator.path);
+  if (!await exists(target)) {
+    throw packageError(`Asset package is missing ${label.toLowerCase()} file ${locator.path}.`, "ASSET_PACKAGE_MANIFEST_INVALID");
+  }
+  const content = asObject(JSON.parse(await readFile(target, "utf8")));
+  if (!content) {
+    throw packageError(`${label} file is not a JSON object: ${locator.path}.`, "ASSET_PACKAGE_MANIFEST_INVALID");
+  }
+  const actualHash = createHash("sha256").update(JSON.stringify(content), "utf8").digest("hex");
+  if (actualHash !== locator.content_hash) {
+    throw packageError(`${label} content hash mismatch for ${locator.path}.`, "ASSET_PACKAGE_HASH_MISMATCH");
+  }
+  return content;
+}
+function parseRecord(line) {
+  const value = JSON.parse(line);
+  const record = asObject(value);
+  if (!record || typeof record.path !== "string") {
+    throw packageError("Asset package record is missing path.", "ASSET_PACKAGE_RECORD_INVALID");
+  }
+  if (!Object.prototype.hasOwnProperty.call(record, "content")) {
+    throw packageError("Asset package record is missing content.", "ASSET_PACKAGE_RECORD_INVALID");
+  }
+  return {
+    path: record.path,
+    append: Boolean(record.append),
+    content: record.content
+  };
+}
+function resolveRecordPath(root, path) {
+  if (path.startsWith("/") || path.includes("\0")) {
+    throw packageError(`Invalid asset package path: ${path}`, "ASSET_PACKAGE_PATH_INVALID");
+  }
+  const target = resolve2(root, path);
+  const normalizedRoot = `${resolve2(root)}/`;
+  if (!target.startsWith(normalizedRoot)) {
+    throw packageError(`Invalid asset package path: ${path}`, "ASSET_PACKAGE_PATH_INVALID");
+  }
+  return target;
+}
+function packageDescriptor(descriptor) {
+  const snapshotHash = stringValue(descriptor.snapshot_hash, "snapshot_hash").toLowerCase();
+  if (!SHA256_PATTERN.test(snapshotHash)) {
+    throw packageError("Asset package export returned invalid snapshot_hash.", "ASSET_PACKAGE_DESCRIPTOR_INVALID");
+  }
+  return {
+    snapshotId: typeof descriptor.snapshot_id === "string" ? descriptor.snapshot_id : void 0,
+    snapshotHash
+  };
+}
+function asObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  return value;
+}
+function stringValue(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw packageError(`${label} must be a non-empty string.`, "ASSET_PACKAGE_DESCRIPTOR_INVALID");
+  }
+  return value;
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function packageError(message, code) {
+  return new CapabilityGatewayError(message, code, 422);
+}
+
+// src/commands/project-semantic/asset-package/export.ts
+var ASSET_PACKAGE_EXPORT_CAPABILITY = "business_semantics.asset_package.export";
+var ASSET_SCOPES = /* @__PURE__ */ new Set(["governed", "collaborative", "all_visible"]);
+function assetScope(ctx) {
+  const value = ctx.str("asset-scope") || "governed";
+  if (!ASSET_SCOPES.has(value)) {
+    throw new Error("asset-scope must be one of: governed, collaborative, all_visible");
+  }
+  return value;
+}
+var assetPackageExportCommand = {
+  service: "project-semantic",
+  resource: "asset-package",
+  command: "export",
+  description: "Export and materialize a project asset package for CLI Agent semantic recommendation.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    {
+      name: "asset-scope",
+      type: "string",
+      required: false,
+      desc: "Asset scope: governed, collaborative, or all_visible. Defaults to governed."
+    }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: buildCapabilityGatewayUrl(
+      ctx.host(),
+      resolveGatewayDomain("analysis", "analysis"),
+      `capabilities/${ASSET_PACKAGE_EXPORT_CAPABILITY}/execute`
+    ),
+    body: { input: { project_id: ctx.num("project-id"), asset_scope: assetScope(ctx) } }
+  }),
+  execute: async (ctx) => {
+    const projectId = ctx.num("project-id");
+    const scope = assetScope(ctx);
+    const response = await executeCapabilityWithEnvelope(
+      ctx.host(),
+      resolveGatewayDomain("analysis", "analysis"),
+      ASSET_PACKAGE_EXPORT_CAPABILITY,
+      { project_id: projectId, asset_scope: scope }
+    );
+    return response.data;
+  }
+};
+var projectSemanticAssetPackageExport = withAsyncArtifactLifecycle(assetPackageExportCommand, {
+  preflightOutput: ({ output, force }) => preflightAssetPackageOutput({ output, force }),
+  materialize: materializeProjectSemanticAssetPackage
+});
+
+// src/commands/project-semantic/candidate/submit.ts
+var projectSemanticCandidateSubmit = createProjectSemanticCommand({
+  resource: "candidate",
+  command: "submit",
+  capabilityId: "business_semantics.candidate.submit",
+  description: "Submit CLI-Agent generated project semantic candidates grouped by topic domain.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "topic-groups", type: "json", desc: "Topic-domain grouped recommendations JSON array." },
+    { name: "submit-file", type: "string", desc: "JSON file containing topic_groups or an array of groups." },
+    { name: "snapshot-hash", type: "string", desc: "Optional exported asset package SHA-256." },
+    { name: "request-id", type: "string", desc: "Optional idempotency key; generated when omitted.", maxLength: 128 }
+  ],
+  risk: "write",
+  validate: validateSubmitSource,
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    snapshot_hash: optionalString(ctx, "snapshot-hash"),
+    topic_groups: topicGroups(ctx),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+function validateSubmitSource(ctx) {
+  topicGroups(ctx);
+}
+function topicGroups(ctx) {
+  const hasInline = ctx.str("topic-groups") !== "";
+  const hasFile = ctx.str("submit-file") !== "";
+  if (hasInline === hasFile) {
+    throw new Error("Provide exactly one of --topic-groups or --submit-file.");
+  }
+  const raw = hasInline ? optionalJson(ctx, "topic-groups") : readJsonFile(ctx.str("submit-file"), 2 * 1024 * 1024);
+  const groups = Array.isArray(raw) ? raw : arrayValue(raw?.topic_groups, "--submit-file topic_groups");
+  if (groups.length < 1 || groups.length > 100) {
+    throw new Error("topic_groups must contain 1 to 100 groups.");
+  }
+  return groups;
+}
+
+// src/commands/project-semantic/candidate/enable.ts
+var projectSemanticCandidateEnable = createProjectSemanticCommand({
+  resource: "candidate",
+  command: "enable",
+  capabilityId: "business_semantics.candidate.enable",
+  description: "Enable recommended project semantic candidates. Enabled semantics are immediately used by CLI and Agent.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "candidate-ids",
+      type: "json",
+      required: true,
+      desc: "JSON array of candidate IDs to enable."
+    },
+    { name: "note", type: "string", desc: "Optional enable note." },
+    {
+      name: "request-id",
+      type: "string",
+      desc: "Optional idempotency key; generated when omitted.",
+      maxLength: 128
+    }
+  ],
+  risk: "high-risk-write",
+  validate: (ctx) => candidateIds(ctx),
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    candidate_ids: candidateIds(ctx),
+    publish_note: optionalString(ctx, "note"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+function candidateIds(ctx) {
+  const values = arrayValue(
+    optionalJson(ctx, "candidate-ids"),
+    "--candidate-ids"
+  );
+  if (values.length < 1 || values.some((value) => typeof value !== "string" || value.trim() === "")) {
+    throw new Error("--candidate-ids must be a non-empty JSON string array.");
+  }
+  return values;
+}
+
+// src/commands/project-semantic/candidate/validate.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync, readFileSync as readFileSync2, statSync } from "fs";
+import { join, resolve as resolve3 } from "path";
+var SEMANTIC_TYPES = /* @__PURE__ */ new Set([
+  "business_concept",
+  "business_rule",
+  "asset_semantics",
+  "calculation_convention"
+]);
+var projectSemanticCandidateValidate = {
+  service: "project-semantic",
+  resource: "candidate",
+  command: "validate",
+  description: "Validate deterministic candidate contracts against a certified project-semantic asset package.",
+  flags: [
+    { name: "asset-package", type: "string", required: true, desc: "Materialized authenticated project asset package directory." },
+    { name: "submit-file", type: "string", required: true, desc: "Agent-authored JSON containing topic_groups." }
+  ],
+  risk: "read",
+  execute: async (ctx) => validateCandidateFile(
+    loadStructuredPackage(ctx.str("asset-package")),
+    readJsonFile(ctx.str("submit-file"), 4 * 1024 * 1024)
+  )
+};
+function validateCandidateFile(assetPackage, submitFile) {
+  const submitRecord = recordValue(submitFile, "submit file");
+  const assets = assetPackage.assets;
+  const groups = arrayValue(submitRecord.topic_groups, "submit file topic_groups").map((item) => recordValue(item, "topic group"));
+  const assetKeys = new Set(assets.flatMap(assetIdentityKeys));
+  const assetByIdentityKey = /* @__PURE__ */ new Map();
+  assets.forEach((asset) => {
+    assetIdentityKeys(asset).forEach((key) => assetByIdentityKey.set(key, asset));
+  });
+  const candidates = groups.flatMap(
+    (group) => arrayValue(group.candidates, "topic group candidates").map((item) => ({
+      group,
+      candidate: recordValue(item, "candidate")
+    }))
+  );
+  const errors = [];
+  const warnings = [];
+  const titles = /* @__PURE__ */ new Map();
+  const bodies = /* @__PURE__ */ new Map();
+  const blockingCatalog = assetPackage.catalogEntries.filter((entry) => entry.catalog_kind !== "rejected");
+  const rejectedCatalog = assetPackage.catalogEntries.filter((entry) => entry.catalog_kind === "rejected");
+  let unresolvedResourceRefCount = 0;
+  if (groups.length < 1 || groups.length > 100) {
+    errors.push("topic_groups must contain 1 to 100 groups.");
+  }
+  if (candidates.length < 1 || candidates.length > 200) {
+    errors.push("The candidate batch must contain 1 to 200 candidates.");
+  }
+  groups.forEach((group, groupIndex) => {
+    const groupLabel = `topic_groups[${groupIndex}]`;
+    requireText(group, "topic_domain_key", groupLabel, errors);
+    requireText(group, "topic_domain_title", groupLabel, errors);
+    requireText(group, "topic_group_key", groupLabel, errors);
+    requireText(group, "topic_group_title", groupLabel, errors);
+    requireText(group, "topic_group_reason", groupLabel, errors);
+  });
+  candidates.forEach(({ candidate }, index) => {
+    const label = `candidate[${index}]`;
+    const semanticType = requireText(candidate, "semantic_type", label, errors).toLowerCase();
+    const title = requireText(candidate, "title", label, errors);
+    requireText(candidate, "summary", label, errors);
+    const content = requireText(candidate, "content", label, errors);
+    requireText(candidate, "recommendation_reason", label, errors);
+    if (!SEMANTIC_TYPES.has(semanticType)) {
+      errors.push(`${label}.semantic_type is unsupported.`);
+    }
+    increment(titles, normalize(title));
+    increment(bodies, normalize(content));
+    const semanticTypeAndBody = semanticContentFingerprint(semanticType, content);
+    const duplicateEntry = blockingCatalog.find((entry) => normalize(textValue(entry.title)) === normalize(title) || textValue(entry.content_fingerprint) === semanticTypeAndBody);
+    if (duplicateEntry) {
+      errors.push(`${label} duplicates an existing ${catalogLabel(duplicateEntry)} semantic: ${textValue(duplicateEntry.title)}.`);
+    }
+    const rejectedEntry = rejectedCatalog.find((entry) => normalize(textValue(entry.title)) === normalize(title) || textValue(entry.content_fingerprint) === semanticTypeAndBody);
+    if (rejectedEntry && !hasMaterialChange(candidate)) {
+      warnings.push(`${label} matches rejected candidate ${textValue(rejectedEntry.candidate_id)}; provide change_kind and target_candidate_id for a material revision.`);
+    }
+    const refs = arrayValue(candidate.resource_refs, `${label}.resource_refs`).map((item) => recordValue(item, "resource ref"));
+    if (refs.length === 0) {
+      errors.push(`${label}.resource_refs must bind certified evidence from the asset package.`);
+    }
+    refs.forEach((ref) => {
+      if (!resourceIdentityKeys(ref).some((key) => assetKeys.has(key))) {
+        unresolvedResourceRefCount += 1;
+      }
+    });
+  });
+  const duplicateTitles = duplicateCount(titles);
+  const duplicateBodies = duplicateCount(bodies);
+  if (duplicateTitles > 0) {
+    errors.push(`${duplicateTitles} duplicate candidate titles were generated.`);
+  }
+  if (duplicateBodies > 0) {
+    errors.push(`${duplicateBodies} duplicate semantic bodies were generated.`);
+  }
+  if (unresolvedResourceRefCount > 0) {
+    errors.push(`${unresolvedResourceRefCount} resource_refs do not resolve to the authenticated asset package.`);
+  }
+  const oneCandidatePerAsset = candidates.length > 1 && candidates.every(
+    ({ candidate }) => Array.isArray(candidate.resource_refs) && candidate.resource_refs.length === 1
+  );
+  return {
+    passed: errors.length === 0 && warnings.length === 0,
+    topic_domain_count: groups.length,
+    candidate_count: candidates.length,
+    authenticated_asset_count: assets.length,
+    unresolved_resource_ref_count: unresolvedResourceRefCount,
+    duplicate_title_count: duplicateTitles,
+    duplicate_body_count: duplicateBodies,
+    one_candidate_per_asset: oneCandidatePerAsset,
+    catalog_entry_count: assetPackage.catalogEntries.length,
+    package_kind: "structured_directory",
+    snapshot_hash: assetPackage.snapshotHash,
+    topic_groups: topicGroupSummaries(groups, assetByIdentityKey),
+    errors,
+    warnings
+  };
+}
+function topicGroupSummaries(groups, assetByIdentityKey) {
+  return groups.map((group) => {
+    const candidates = arrayValue(group.candidates, "topic group candidates").map((item) => recordValue(item, "candidate"));
+    return {
+      topic_domain_key: textValue(group.topic_domain_key),
+      topic_domain_title: textValue(group.topic_domain_title),
+      topic_group_key: textValue(group.topic_group_key),
+      topic_group_title: textValue(group.topic_group_title),
+      candidate_count: candidates.length,
+      topic_group_reason: textValue(group.topic_group_reason),
+      candidates: candidates.map((candidate, index) => candidateSummary(candidate, index, assetByIdentityKey))
+    };
+  });
+}
+function candidateSummary(candidate, index, assetByIdentityKey) {
+  const refs = Array.isArray(candidate.resource_refs) ? candidate.resource_refs.map((item) => recordValue(item, "resource ref")) : [];
+  return {
+    index: index + 1,
+    semantic_type: textValue(candidate.semantic_type).toLowerCase(),
+    title: textValue(candidate.title),
+    summary: textValue(candidate.summary),
+    resource_ref_count: refs.length,
+    evidence_assets: refs.map((ref) => resourceRefSummary(ref, assetByIdentityKey))
+  };
+}
+function resourceRefSummary(ref, assetByIdentityKey) {
+  const matchedAsset = resourceIdentityKeys(ref).map((key) => assetByIdentityKey.get(key)).find(Boolean);
+  return {
+    resource_type: textValue(ref.asset_type || ref.resource_type || ref.type).toLowerCase(),
+    resource_key: textValue(ref.resource_key || ref.asset_id || ref.id || ref.evidence_id || ref.name),
+    title: textValue(ref.title || ref.display_name || matchedAsset?.title || matchedAsset?.display_name || matchedAsset?.name)
+  };
+}
+function loadStructuredPackage(path) {
+  const packagePath = resolve3(path);
+  const stats = statSync(packagePath);
+  if (!stats.isDirectory()) {
+    throw new Error("asset-package must be a materialized structured package directory.");
+  }
+  recordValue(readJsonFile(join(packagePath, "manifest.json"), 4 * 1024 * 1024), "asset package manifest");
+  const descriptor = recordValue(readJsonFile(join(packagePath, ".asset-package.json"), 64 * 1024), "asset package descriptor");
+  const snapshotHash = textValue(descriptor.snapshot_hash);
+  if (!snapshotHash) {
+    throw new Error("asset package descriptor must contain snapshot_hash.");
+  }
+  const assets = readJsonlFile(join(packagePath, "indexes", "asset-directory.jsonl"), "asset directory").filter((row) => row.record_type !== "header");
+  if (assets.length === 0) {
+    throw new Error("asset directory must contain at least one asset.");
+  }
+  return {
+    assets,
+    catalogEntries: loadCatalogEntries(packagePath),
+    snapshotHash
+  };
+}
+function loadCatalogEntries(packagePath) {
+  return [
+    ["published", join(packagePath, "catalog", "published.jsonl")],
+    ["disabled", join(packagePath, "catalog", "disabled.jsonl")],
+    ["active", join(packagePath, "catalog", "active-candidates.jsonl")],
+    ["rejected", join(packagePath, "catalog", "rejected-candidates.jsonl")]
+  ].flatMap(([kind, file]) => {
+    if (!existsSync(file)) {
+      return [];
+    }
+    return readJsonlFile(file, `${kind} semantic catalog`).filter((row) => row.record_type !== "header").map((row) => ({ ...row, catalog_kind: kind }));
+  });
+}
+function semanticContentFingerprint(semanticType, content) {
+  const normalized = `${semanticType.trim().toLowerCase()}
+${normalizeSemanticText(content)}`;
+  return createHash2("sha256").update(normalized).digest("hex");
+}
+function normalizeSemanticText(value) {
+  return value.toLowerCase().replace(/\s+/g, "").replace(/[，。；：、,.!?！？:;]/g, "");
+}
+function catalogLabel(entry) {
+  if (entry.catalog_kind === "published") {
+    return "published";
+  }
+  return entry.catalog_kind === "disabled" ? "disabled" : "active candidate";
+}
+function hasMaterialChange(candidate) {
+  return textValue(candidate.change_kind) !== "" && textValue(candidate.target_candidate_id) !== "";
+}
+function readJsonlFile(file, label) {
+  const text = readFileSync2(file, "utf8");
+  const rows = [];
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    if (!line.trim()) {
+      continue;
+    }
+    rows.push(recordValue(JSON.parse(line), `${label} line ${index + 1}`));
+  }
+  return rows;
+}
+function assetIdentityKeys(asset) {
+  const type = textValue(asset.asset_type || asset.resource_type || asset.type).toLowerCase();
+  return [asset.asset_id, asset.asset_name, asset.name, asset.resource_key, asset.id].concat(asset.evidence_id).flatMap((value) => identityValueKeys(type, value));
+}
+function resourceIdentityKeys(ref) {
+  const type = textValue(ref.asset_type || ref.resource_type || ref.type).toLowerCase();
+  return [ref.asset_id, ref.asset_name, ref.name, ref.resource_key, ref.id].concat(ref.evidence_id).flatMap((value) => identityValueKeys(type, value));
+}
+function identityValueKeys(type, value) {
+  const key = textValue(value);
+  if (!type || !key) {
+    return [];
+  }
+  const variants = /* @__PURE__ */ new Set([key]);
+  const typedPrefix = `${type}_`;
+  if (key.startsWith(typedPrefix) && key.length > typedPrefix.length) {
+    variants.add(key.slice(typedPrefix.length));
+  }
+  const lastColon = key.lastIndexOf(":");
+  if (lastColon >= 0 && lastColon < key.length - 1) {
+    variants.add(key.slice(lastColon + 1));
+  }
+  return Array.from(variants).map((item) => `${type}:${item}`);
+}
+function recordValue(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return value;
+}
+function requireText(record, field, label, errors) {
+  const value = textValue(record[field]);
+  if (!value) {
+    errors.push(`${label}.${field} is required.`);
+  }
+  return value;
+}
+function textValue(value) {
+  return typeof value === "string" ? value.trim() : typeof value === "number" ? String(value) : "";
+}
+function normalize(value) {
+  return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function increment(values, key) {
+  if (key) {
+    values.set(key, (values.get(key) || 0) + 1);
+  }
+}
+function duplicateCount(values) {
+  return Array.from(values.values()).reduce((sum, count) => sum + Math.max(0, count - 1), 0);
+}
+
+// src/commands/project-semantic/candidate/list.ts
+var projectSemanticCandidateList = createProjectSemanticCommand({
+  resource: "candidate",
+  command: "list",
+  capabilityId: "business_semantics.candidate.list",
+  description: "List Agent recommendations grouped by topic domain.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "status", type: "string", desc: "Internal recommendation status filter." },
+    { name: "topic-group-id", type: "string", desc: "Optional exact topic group ID." },
+    { name: "limit", type: "number", desc: "Directory page size.", min: 1, max: 200 },
+    { name: "offset", type: "number", desc: "Zero-based directory page offset.", min: 0 }
+  ],
+  risk: "read",
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    status: optionalString(ctx, "status"),
+    topic_group_id: optionalString(ctx, "topic-group-id"),
+    limit: optionalNumber(ctx, "limit"),
+    offset: optionalNumber(ctx, "offset")
+  })
+});
+
+// src/commands/project-semantic/candidate/get.ts
+var projectSemanticCandidateGet = createProjectSemanticCommand({
+  resource: "candidate",
+  command: "get",
+  capabilityId: "business_semantics.candidate.get",
+  description: "Get one project semantic candidate with evidence and structured asset bindings.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "candidate-id", type: "string", required: true, desc: "Exact candidate ID." }
+  ],
+  risk: "read",
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id"),
+    candidate_id: ctx.str("candidate-id")
+  })
+});
+
+// src/commands/project-semantic/candidate/edit.ts
+var projectSemanticCandidateEdit = createProjectSemanticCommand({
+  resource: "candidate",
+  command: "edit",
+  capabilityId: "business_semantics.candidate.edit",
+  description: "Edit one recommendation before enabling it.",
+  flags: [
+    {
+      name: "project-id",
+      type: "number",
+      required: true,
+      desc: "Numeric project ID.",
+      alias: "p",
+      min: 1
+    },
+    {
+      name: "candidate-id",
+      type: "string",
+      required: true,
+      desc: "Exact candidate ID."
+    },
+    {
+      name: "expected-version",
+      type: "number",
+      required: true,
+      desc: "Latest optimistic-lock version.",
+      min: 1
+    },
+    {
+      name: "semantic-type",
+      type: "string",
+      desc: "business_concept, business_rule, asset_semantics, or calculation_convention."
+    },
+    { name: "title", type: "string", desc: "Edited title." },
+    { name: "summary", type: "string", desc: "Edited summary." },
+    { name: "content", type: "string", desc: "Edited content." },
+    { name: "keywords", type: "json", desc: "Edited keyword array." },
+    {
+      name: "resource-refs",
+      type: "json",
+      desc: "Edited structured asset binding array."
+    },
+    {
+      name: "request-id",
+      type: "string",
+      desc: "Optional idempotency key; generated when omitted.",
+      maxLength: 128
+    }
+  ],
+  risk: "write",
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    candidate_id: ctx.str("candidate-id"),
+    expected_version: ctx.num("expected-version"),
+    semantic_type: optionalString(ctx, "semantic-type"),
+    title: optionalString(ctx, "title"),
+    summary: optionalString(ctx, "summary"),
+    content: optionalString(ctx, "content"),
+    keywords: optionalJson(ctx, "keywords"),
+    resource_refs: optionalJson(ctx, "resource-refs"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+
+// src/commands/project-semantic/release/list.ts
+var projectSemanticReleaseList = createProjectSemanticCommand({
+  resource: "release",
+  command: "list",
+  capabilityId: "business_semantics.release.list",
+  description: "List project semantic releases and the current release version.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 }
+  ],
+  risk: "read",
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id")
+  })
+});
+
+// src/commands/project-semantic/release/publish.ts
+var projectSemanticReleasePublish = createProjectSemanticCommand({
+  resource: "release",
+  command: "publish",
+  capabilityId: "business_semantics.release.publish",
+  description: "Publish explicitly approved candidates into the project semantic catalog.",
+  flags: [
+    { name: "project-id", type: "number", required: true, desc: "Numeric project ID.", alias: "p", min: 1 },
+    { name: "candidate-ids", type: "json", required: true, desc: "JSON array of approved candidate IDs." },
+    { name: "expected-release-version", type: "number", required: true, desc: "Current release version, or 0 when no release exists.", min: 0 },
+    { name: "publish-note", type: "string", desc: "Optional publication note." },
+    { name: "request-id", type: "string", desc: "Optional idempotency key; generated when omitted.", maxLength: 128 }
+  ],
+  risk: "high-risk-write",
+  validate: (ctx) => candidateIds2(ctx),
+  buildInput: (ctx) => compactInput({
+    project_id: ctx.num("project-id"),
+    candidate_ids: candidateIds2(ctx),
+    expected_release_version: ctx.num("expected-release-version"),
+    publish_note: optionalString(ctx, "publish-note"),
+    request_id: optionalString(ctx, "request-id")
+  })
+});
+function candidateIds2(ctx) {
+  const values = arrayValue(optionalJson(ctx, "candidate-ids"), "--candidate-ids");
+  if (values.length < 1 || values.some((value) => typeof value !== "string" || value.trim() === "")) {
+    throw new Error("--candidate-ids must be a non-empty JSON string array.");
+  }
+  return values;
+}
+
+// src/commands/project-semantic/index.ts
+registerCapabilityGatewayRoute("project-semantic", {
+  gatewayDomain: "analysis"
+});
+var commands = [
+  projectSemanticList,
+  projectSemanticGet,
+  projectSemanticEnable,
+  projectSemanticDisable,
+  projectSemanticDeleteImpact,
+  projectSemanticDelete,
+  projectSemanticAssetPackageExport,
+  projectSemanticCandidateValidate,
+  projectSemanticCandidateSubmit,
+  projectSemanticCandidateEnable,
+  projectSemanticCandidateList,
+  projectSemanticCandidateGet,
+  projectSemanticCandidateEdit,
+  projectSemanticReleaseList,
+  projectSemanticReleasePublish
+];
+var project_semantic_default = commands;
+export {
+  project_semantic_default as default
+};