@senad-d/observme 0.1.3 → 0.1.5

package/src/config/project-paths.ts

@@ -1,4 +1,8 @@
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { constants } from "node:fs";
+import type { BigIntStats } from "node:fs";
+import { lstat, mkdir, open, realpath, stat, unlink } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 export interface ProjectLocalFilePathOptions {
   readonly cwd?: string;
@@ -9,17 +13,107 @@ export interface ProjectLocalFilePathOptions {
   readonly inputLabel: string;
 }
 
+export interface ProjectLocalFileOperationHooks {
+  readonly beforeOpen?: () => Promise<void> | void;
+}
+
+export type ExclusiveProjectLocalFileCreateStatus = "created" | "exists";
+
+interface FileIdentity {
+  readonly device: bigint;
+  readonly inode: bigint;
+}
+
+interface CanonicalProjectPathSnapshot {
+  readonly rootPath: string;
+  readonly canonicalRootPath: string;
+  readonly canonicalCandidatePath: string;
+  readonly rootIdentity: FileIdentity;
+  readonly inputLabel: string;
+}
+
 const parentSegment = "..";
+const unsafeProjectPathErrorCode = "OBSERVME_UNSAFE_PROJECT_PATH";
 
 export function resolveProjectLocalFilePath(options: ProjectLocalFilePathOptions): string {
   const root = resolve(options.cwd ?? process.cwd());
   const candidatePath = resolveProjectLocalCandidatePath(root, options);
 
-  if (!isPathInsideOrSame(root, candidatePath)) throw new Error(createUnsafeProjectPathMessage(options.inputLabel));
+  assertProjectContainment(root, candidatePath, options.inputLabel);
   if (shouldPreserveRelativeOverride(options)) return options.overridePath!;
   return candidatePath;
 }
 
+/**
+ * Project-local I/O policy: lexical paths and their canonical targets must remain
+ * inside one stable canonical root. Safe in-root symlinks are pinned to their
+ * canonical target, missing final paths are supported, and an opened file's
+ * device/inode identity is verified before bytes are read or written.
+ */
+export async function resolveCanonicalProjectLocalFilePath(
+  options: ProjectLocalFilePathOptions,
+): Promise<string> {
+  return (await createCanonicalProjectPathSnapshot(options)).canonicalCandidatePath;
+}
+
+export async function readCanonicalProjectLocalFileText(
+  options: ProjectLocalFilePathOptions,
+  hooks: ProjectLocalFileOperationHooks = {},
+): Promise<string | undefined> {
+  const snapshot = await createCanonicalProjectPathSnapshot(options);
+  await hooks.beforeOpen?.();
+
+  let fileHandle: FileHandle | undefined;
+
+  try {
+    fileHandle = await openProjectFileForRead(snapshot);
+    if (!fileHandle) return undefined;
+    await assertOpenedProjectFileIsStable(snapshot, fileHandle);
+    return await fileHandle.readFile({ encoding: "utf8" });
+  } finally {
+    await closeFileHandle(fileHandle);
+  }
+}
+
+export async function createCanonicalProjectLocalFileExclusively(
+  options: ProjectLocalFilePathOptions,
+  content: string,
+  hooks: ProjectLocalFileOperationHooks = {},
+): Promise<ExclusiveProjectLocalFileCreateStatus> {
+  const initialSnapshot = await createCanonicalProjectPathSnapshot(options);
+  await mkdir(dirname(initialSnapshot.canonicalCandidatePath), { recursive: true });
+  const snapshot = await createCanonicalProjectPathSnapshot(options);
+  await hooks.beforeOpen?.();
+
+  let fileHandle: FileHandle | undefined;
+  let openedIdentity: FileIdentity | undefined;
+
+  try {
+    fileHandle = await openProjectFileForExclusiveCreate(snapshot);
+    if (!fileHandle) {
+      await assertExistingProjectFileIsSafe(options);
+      return "exists";
+    }
+
+    openedIdentity = toFileIdentity(await fileHandle.stat({ bigint: true }));
+    await assertOpenedProjectFileIsStable(snapshot, fileHandle);
+    await fileHandle.writeFile(content, { encoding: "utf8" });
+    await assertOpenedProjectFileIsStable(snapshot, fileHandle);
+    return "created";
+  } catch (error) {
+    await closeFileHandle(fileHandle);
+    fileHandle = undefined;
+    if (openedIdentity) await removeCreatedFileIfIdentityMatches(snapshot, openedIdentity);
+    throw error;
+  } finally {
+    await closeFileHandle(fileHandle);
+  }
+}
+
+export function isUnsafeProjectPathError(error: unknown): boolean {
+  return isErrorWithCode(error) && error.code === unsafeProjectPathErrorCode;
+}
+
 function resolveProjectLocalCandidatePath(root: string, options: ProjectLocalFilePathOptions): string {
   if (options.overridePath !== undefined) return resolveOverridePath(root, options.overridePath, options.inputLabel);
   return resolveConfigDirPath(root, options);
@@ -30,16 +124,16 @@ function shouldPreserveRelativeOverride(options: ProjectLocalFilePathOptions): b
 }
 
 function resolveOverridePath(root: string, overridePath: string, inputLabel: string): string {
-  if (isRelativeTraversalPath(overridePath)) throw new Error(createUnsafeProjectPathMessage(inputLabel));
+  if (isRelativeTraversalPath(overridePath)) throw createUnsafeProjectPathError(inputLabel);
   return isAbsolute(overridePath) ? resolve(overridePath) : resolve(root, overridePath);
 }
 
 function resolveConfigDirPath(root: string, options: ProjectLocalFilePathOptions): string {
   const configDirName = options.configDirName ?? options.defaultConfigDirName;
 
-  if (!configDirName) throw new Error(createUnsafeProjectPathMessage(options.inputLabel));
-  if (isAbsolute(configDirName)) throw new Error(createUnsafeProjectPathMessage(options.inputLabel));
-  if (hasParentSegment(configDirName)) throw new Error(createUnsafeProjectPathMessage(options.inputLabel));
+  if (!configDirName) throw createUnsafeProjectPathError(options.inputLabel);
+  if (isAbsolute(configDirName)) throw createUnsafeProjectPathError(options.inputLabel);
+  if (hasParentSegment(configDirName)) throw createUnsafeProjectPathError(options.inputLabel);
   return resolve(root, join(configDirName, options.fileName));
 }
 
@@ -51,11 +145,229 @@ function hasParentSegment(pathInput: string): boolean {
   return pathInput.split(/[\\/]+/u).includes(parentSegment);
 }
 
+function assertProjectContainment(root: string, candidatePath: string, inputLabel: string): void {
+  if (!isPathInsideOrSame(root, candidatePath)) throw createUnsafeProjectPathError(inputLabel);
+}
+
+async function createCanonicalProjectPathSnapshot(
+  options: ProjectLocalFilePathOptions,
+): Promise<CanonicalProjectPathSnapshot> {
+  try {
+    const rootPath = resolve(options.cwd ?? process.cwd());
+    const candidatePath = resolveProjectLocalCandidatePath(rootPath, options);
+    assertProjectContainment(rootPath, candidatePath, options.inputLabel);
+
+    const canonicalRootPath = await realpath(rootPath);
+    const rootStats = await stat(canonicalRootPath, { bigint: true });
+    if (!rootStats.isDirectory()) throw createUnsafeProjectPathError(options.inputLabel);
+
+    const canonicalCandidatePath = await resolveCanonicalPathWithMissingComponents(candidatePath);
+    assertProjectContainment(canonicalRootPath, canonicalCandidatePath, options.inputLabel);
+
+    return {
+      rootPath,
+      canonicalRootPath,
+      canonicalCandidatePath,
+      rootIdentity: toFileIdentity(rootStats),
+      inputLabel: options.inputLabel,
+    };
+  } catch (error) {
+    if (isUnsafeProjectPathError(error)) throw error;
+    throw createUnsafeProjectPathError(options.inputLabel);
+  }
+}
+
+async function openProjectFileForRead(snapshot: CanonicalProjectPathSnapshot): Promise<FileHandle | undefined> {
+  try {
+    return await open(snapshot.canonicalCandidatePath, createReadOpenFlags());
+  } catch (error) {
+    if (!isMissingPathError(error) && !isNotDirectoryError(error)) {
+      if (isSymlinkLoopError(error)) throw createUnsafeProjectPathError(snapshot.inputLabel);
+      throw error;
+    }
+
+    await assertMissingProjectPathIsSafe(snapshot);
+    return undefined;
+  }
+}
+
+async function openProjectFileForExclusiveCreate(
+  snapshot: CanonicalProjectPathSnapshot,
+): Promise<FileHandle | undefined> {
+  try {
+    return await open(snapshot.canonicalCandidatePath, createExclusiveWriteOpenFlags(), 0o600);
+  } catch (error) {
+    if (isFileAlreadyExistsError(error)) return undefined;
+    if (isSymlinkLoopError(error)) throw createUnsafeProjectPathError(snapshot.inputLabel);
+    throw error;
+  }
+}
+
+function createReadOpenFlags(): number {
+  return constants.O_RDONLY | optionalOpenFlag(constants.O_NOFOLLOW) | optionalOpenFlag(constants.O_NONBLOCK);
+}
+
+function createExclusiveWriteOpenFlags(): number {
+  return constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | optionalOpenFlag(constants.O_NOFOLLOW);
+}
+
+function optionalOpenFlag(flag: number | undefined): number {
+  return typeof flag === "number" ? flag : 0;
+}
+
+async function assertOpenedProjectFileIsStable(
+  snapshot: CanonicalProjectPathSnapshot,
+  fileHandle: FileHandle,
+): Promise<void> {
+  try {
+    await assertCanonicalRootIsStable(snapshot);
+    const currentCanonicalPath = await realpath(snapshot.canonicalCandidatePath);
+    assertProjectContainment(snapshot.canonicalRootPath, currentCanonicalPath, snapshot.inputLabel);
+
+    const openedStats = await fileHandle.stat({ bigint: true });
+    const currentPathStats = await stat(currentCanonicalPath, { bigint: true });
+    if (!openedStats.isFile() || !currentPathStats.isFile()) {
+      throw createUnsafeProjectPathError(snapshot.inputLabel);
+    }
+    if (!hasSameFileIdentity(openedStats, currentPathStats)) {
+      throw createUnsafeProjectPathError(snapshot.inputLabel);
+    }
+  } catch (error) {
+    if (isUnsafeProjectPathError(error)) throw error;
+    throw createUnsafeProjectPathError(snapshot.inputLabel);
+  }
+}
+
+async function assertMissingProjectPathIsSafe(snapshot: CanonicalProjectPathSnapshot): Promise<void> {
+  try {
+    await assertCanonicalRootIsStable(snapshot);
+    const currentCanonicalPath = await resolveCanonicalPathWithMissingComponents(
+      snapshot.canonicalCandidatePath,
+    );
+    assertProjectContainment(snapshot.canonicalRootPath, currentCanonicalPath, snapshot.inputLabel);
+  } catch (error) {
+    if (isUnsafeProjectPathError(error)) throw error;
+    throw createUnsafeProjectPathError(snapshot.inputLabel);
+  }
+}
+
+async function assertExistingProjectFileIsSafe(options: ProjectLocalFilePathOptions): Promise<void> {
+  const snapshot = await createCanonicalProjectPathSnapshot(options);
+
+  try {
+    await assertCanonicalRootIsStable(snapshot);
+    const existingStats = await stat(snapshot.canonicalCandidatePath, { bigint: true });
+    if (!existingStats.isFile()) throw createUnsafeProjectPathError(snapshot.inputLabel);
+  } catch (error) {
+    if (isUnsafeProjectPathError(error)) throw error;
+    throw createUnsafeProjectPathError(snapshot.inputLabel);
+  }
+}
+
+async function assertCanonicalRootIsStable(snapshot: CanonicalProjectPathSnapshot): Promise<void> {
+  const currentCanonicalRoot = await realpath(snapshot.rootPath);
+  const currentRootStats = await stat(currentCanonicalRoot, { bigint: true });
+  if (!currentRootStats.isDirectory()) throw createUnsafeProjectPathError(snapshot.inputLabel);
+  if (!hasSameIdentity(snapshot.rootIdentity, toFileIdentity(currentRootStats))) {
+    throw createUnsafeProjectPathError(snapshot.inputLabel);
+  }
+}
+
+async function removeCreatedFileIfIdentityMatches(
+  snapshot: CanonicalProjectPathSnapshot,
+  openedIdentity: FileIdentity,
+): Promise<void> {
+  try {
+    const currentStats = await lstat(snapshot.canonicalCandidatePath, { bigint: true });
+    if (!hasSameIdentity(openedIdentity, toFileIdentity(currentStats))) return;
+    await unlink(snapshot.canonicalCandidatePath);
+  } catch {
+    return;
+  }
+}
+
+async function closeFileHandle(fileHandle: FileHandle | undefined): Promise<void> {
+  if (!fileHandle) return;
+
+  try {
+    await fileHandle.close();
+  } catch {
+    return;
+  }
+}
+
+function toFileIdentity(stats: BigIntStats): FileIdentity {
+  return { device: stats.dev, inode: stats.ino };
+}
+
+function hasSameFileIdentity(left: BigIntStats, right: BigIntStats): boolean {
+  return hasSameIdentity(toFileIdentity(left), toFileIdentity(right));
+}
+
+function hasSameIdentity(left: FileIdentity, right: FileIdentity): boolean {
+  return left.device === right.device && left.inode === right.inode;
+}
+
+async function resolveCanonicalPathWithMissingComponents(candidatePath: string): Promise<string> {
+  const missingComponents: string[] = [];
+  let currentPath = candidatePath;
+
+  while (true) {
+    try {
+      const canonicalExistingPath = await realpath(currentPath);
+      missingComponents.reverse();
+      return resolve(canonicalExistingPath, ...missingComponents);
+    } catch (error) {
+      if (!isMissingPathError(error) || await pathEntryExists(currentPath)) throw error;
+      const parentPath = dirname(currentPath);
+      if (parentPath === currentPath) throw error;
+      missingComponents.push(basename(currentPath));
+      currentPath = parentPath;
+    }
+  }
+}
+
+async function pathEntryExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (isMissingPathError(error)) return false;
+    throw error;
+  }
+}
+
+function isMissingPathError(error: unknown): error is NodeJS.ErrnoException {
+  return isErrorWithCode(error) && error.code === "ENOENT";
+}
+
+function isNotDirectoryError(error: unknown): error is NodeJS.ErrnoException {
+  return isErrorWithCode(error) && error.code === "ENOTDIR";
+}
+
+function isSymlinkLoopError(error: unknown): error is NodeJS.ErrnoException {
+  return isErrorWithCode(error) && error.code === "ELOOP";
+}
+
+function isFileAlreadyExistsError(error: unknown): error is NodeJS.ErrnoException {
+  return isErrorWithCode(error) && error.code === "EEXIST";
+}
+
+function isErrorWithCode(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+
 function isPathInsideOrSame(root: string, candidatePath: string): boolean {
   const pathFromRoot = relative(root, candidatePath);
   return pathFromRoot === "" || (!pathFromRoot.startsWith(parentSegment) && !isAbsolute(pathFromRoot));
 }
 
+function createUnsafeProjectPathError(inputLabel: string): NodeJS.ErrnoException {
+  const error = new Error(createUnsafeProjectPathMessage(inputLabel)) as NodeJS.ErrnoException;
+  error.code = unsafeProjectPathErrorCode;
+  return error;
+}
+
 function createUnsafeProjectPathMessage(inputLabel: string): string {
   return `Unsafe ObservMe ${inputLabel}: path input must stay inside the active project root.`;
 }

package/src/config/query-limits.ts

@@ -0,0 +1,10 @@
+export const QUERY_RESULT_COUNT_MINIMUM = 1;
+export const QUERY_RESULT_COUNT_MAXIMUM = 100;
+
+export function normalizeQueryResultCount(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value < QUERY_RESULT_COUNT_MINIMUM) {
+    return QUERY_RESULT_COUNT_MINIMUM;
+  }
+
+  return Math.min(Math.trunc(value), QUERY_RESULT_COUNT_MAXIMUM);
+}

package/src/config/schema.ts

@@ -1,5 +1,6 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import { QUERY_RESULT_COUNT_MAXIMUM, QUERY_RESULT_COUNT_MINIMUM } from "./query-limits.ts";
 
 const observMeEnvironments = ["production", "development", "test"] as const;
 const privacyPathModes = ["hash", "basename", "full", "drop"] as const;
@@ -8,8 +9,11 @@ export type ObservMeEnvironment = (typeof observMeEnvironments)[number];
 export type OtlpProtocol = "http/protobuf";
 export type PrivacyPathMode = (typeof privacyPathModes)[number];
 
+export const ACTIVE_AGENT_LEASE_DURATION_MILLIS_MINIMUM = 10_000;
+export const ACTIVE_AGENT_LEASE_DURATION_MILLIS_MAXIMUM = 300_000;
+export const ACTIVE_AGENT_LEASE_EXPORT_SAFETY_MARGIN_MILLIS = 5_000;
+
 export interface OtlpTlsConfig {
-  enabled: boolean;
   insecureSkipVerify: boolean;
 }
 
@@ -71,6 +75,7 @@ export interface MetricsConfig {
   enabled: boolean;
   exportIntervalMillis: number;
   exportTimeoutMillis: number;
+  activeAgentLeaseDurationMillis: number;
   labels?: string[];
 }
 
@@ -173,7 +178,6 @@ export interface ObservMeConfig {
   enabled: boolean;
   environment: ObservMeEnvironment;
   tenant: string;
-  replayOnStart: boolean;
   otlp: OtlpConfig;
   resource: ResourceConfig;
   workflow: WorkflowConfig;
@@ -192,6 +196,10 @@ const environmentSchema = StringEnum(observMeEnvironments);
 const otlpProtocolSchema = Type.Literal("http/protobuf");
 const stringRecordSchema = Type.Record(Type.String(), Type.String());
 const positiveIntegerSchema = Type.Integer({ minimum: 1 });
+const queryResultCountSchema = Type.Integer({
+  minimum: QUERY_RESULT_COUNT_MINIMUM,
+  maximum: QUERY_RESULT_COUNT_MAXIMUM,
+});
 const ratioSchema = Type.Number({ minimum: 0, maximum: 1 });
 const pathModeSchema = StringEnum(privacyPathModes);
 
@@ -208,7 +216,6 @@ export const observMeConfigSchema = Type.Object(
     enabled: Type.Boolean(),
     environment: environmentSchema,
     tenant: Type.String({ minLength: 1 }),
-    replayOnStart: Type.Boolean(),
     otlp: Type.Object(
       {
         endpoint: Type.String({ minLength: 1 }),
@@ -217,7 +224,6 @@ export const observMeConfigSchema = Type.Object(
         headers: stringRecordSchema,
         tls: Type.Object(
           {
-            enabled: Type.Boolean(),
             insecureSkipVerify: Type.Boolean(),
           },
           { additionalProperties: false },
@@ -288,6 +294,10 @@ export const observMeConfigSchema = Type.Object(
         enabled: Type.Boolean(),
         exportIntervalMillis: positiveIntegerSchema,
         exportTimeoutMillis: positiveIntegerSchema,
+        activeAgentLeaseDurationMillis: Type.Integer({
+          minimum: ACTIVE_AGENT_LEASE_DURATION_MILLIS_MINIMUM,
+          maximum: ACTIVE_AGENT_LEASE_DURATION_MILLIS_MAXIMUM,
+        }),
         labels: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
       },
       { additionalProperties: false },
@@ -352,10 +362,10 @@ export const observMeConfigSchema = Type.Object(
       {
         enabled: Type.Boolean(),
         timeoutMs: positiveIntegerSchema,
-        maxLogs: positiveIntegerSchema,
-        maxTraces: positiveIntegerSchema,
-        maxMetricSeries: positiveIntegerSchema,
-        maxAgents: positiveIntegerSchema,
+        maxLogs: queryResultCountSchema,
+        maxTraces: queryResultCountSchema,
+        maxMetricSeries: queryResultCountSchema,
+        maxAgents: queryResultCountSchema,
         links: Type.Object(
           {
             traceUrlTemplate: Type.String(),

package/src/config/transport-security.ts

@@ -0,0 +1,107 @@
+import type { ObservMeConfig } from "./schema.ts";
+
+const tlsVerificationEnabled = "TLS certificate verification enabled";
+const tlsVerificationDisabled = "TLS certificate verification disabled";
+const plaintextHttp = "plaintext HTTP";
+const inactiveObservMe = "inactive (ObservMe disabled)";
+const inactiveSignals = "inactive (all OTLP signals disabled)";
+const inactiveGrafana = "inactive (Grafana queries disabled)";
+const unknownTransport = "unknown or invalid transport";
+
+interface OtlpSignalTransport {
+  readonly name: "traces" | "metrics" | "logs";
+  readonly endpoint: string;
+  readonly enabled: boolean;
+}
+
+export interface ObsTransportSecuritySnapshot {
+  readonly collector: string;
+  readonly grafana: string;
+}
+
+export function describeOtlpTransportSecurity(config: ObservMeConfig): string {
+  if (!config.enabled) return inactiveObservMe;
+
+  const signals = getOtlpSignalTransports(config).filter(signal => signal.enabled);
+  if (signals.length === 0) return inactiveSignals;
+
+  const descriptions = signals.map(signal => ({
+    name: signal.name,
+    description: describeEndpointTransportSecurity(
+      signal.endpoint,
+      config.otlp.tls.insecureSkipVerify,
+      config.privacy.allowInsecureTransport,
+    ),
+  }));
+  const uniqueDescriptions = new Set(descriptions.map(signal => signal.description));
+  if (uniqueDescriptions.size === 1) return descriptions[0]?.description ?? unknownTransport;
+
+  return descriptions.map(signal => `${signal.name}: ${signal.description}`).join(", ");
+}
+
+export function describeGrafanaTransportSecurity(config: ObservMeConfig): string {
+  if (!config.query.enabled) return inactiveGrafana;
+  return describeEndpointTransportSecurity(
+    config.query.grafana.url,
+    config.query.grafana.tls.insecureSkipVerify,
+    config.privacy.allowInsecureTransport,
+  );
+}
+
+export function createObsTransportSecuritySnapshot(config: ObservMeConfig): ObsTransportSecuritySnapshot {
+  return {
+    collector: describeEndpointTransportSecurity(
+      config.otlp.endpoint,
+      config.otlp.tls.insecureSkipVerify,
+      config.privacy.allowInsecureTransport,
+    ),
+    grafana: describeGrafanaTransportSecurity(config),
+  };
+}
+
+export function describeEndpointTransportSecurity(
+  endpoint: string,
+  insecureSkipVerify: boolean,
+  allowInsecureTransport: boolean,
+): string {
+  const protocol = readEndpointProtocol(endpoint);
+  if (protocol === "https:") {
+    return insecureSkipVerify
+      ? describeAcknowledgedInsecurity(tlsVerificationDisabled, allowInsecureTransport)
+      : tlsVerificationEnabled;
+  }
+  if (protocol === "http:") return describeAcknowledgedInsecurity(plaintextHttp, allowInsecureTransport);
+  return unknownTransport;
+}
+
+function getOtlpSignalTransports(config: ObservMeConfig): OtlpSignalTransport[] {
+  return [
+    {
+      name: "traces",
+      endpoint: config.otlp.signalEndpoints?.traces ?? config.otlp.endpoint,
+      enabled: config.traces.enabled,
+    },
+    {
+      name: "metrics",
+      endpoint: config.otlp.signalEndpoints?.metrics ?? config.otlp.endpoint,
+      enabled: config.metrics.enabled,
+    },
+    {
+      name: "logs",
+      endpoint: config.otlp.signalEndpoints?.logs ?? config.otlp.endpoint,
+      enabled: config.logs.enabled,
+    },
+  ];
+}
+
+function readEndpointProtocol(endpoint: string): string | undefined {
+  try {
+    return new URL(endpoint.trim()).protocol;
+  } catch {
+    return undefined;
+  }
+}
+
+function describeAcknowledgedInsecurity(description: string, allowInsecureTransport: boolean): string {
+  return allowInsecureTransport ? `${description} (explicitly acknowledged)` : description;
+}