@kitsy/cnos 1.6.1 → 1.8.0

package/dist/build/index.cjs

@@ -73,16 +73,673 @@ var CnosKeyNotFoundError = class extends CnosError {
   }
   key;
 };
+var CnosDerivedExpressionError = class extends CnosError {
+  constructor(message, expression) {
+    super(expression ? `${message} (${expression})` : message);
+    this.expression = expression;
+  }
+  expression;
+};
+var CnosDerivedCycleError = class extends CnosError {
+  constructor(message) {
+    super(message);
+  }
+};
+var CnosDerivedResolutionError = class extends CnosError {
+  constructor(key, message) {
+    super(message);
+    this.key = key;
+  }
+  key;
+};
+var CnosRuntimeProviderError = class extends CnosError {
+  constructor(message) {
+    super(message);
+  }
+};
+
+// ../core/src/derive/builtins.ts
+function stringify(value) {
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+var DERIVE_BUILTINS = {
+  concat: (...args) => args.map((value) => stringify(value)).join(""),
+  coalesce: (...args) => args.find((value) => value !== void 0 && value !== null),
+  when: (condition, whenTrue, whenFalse) => condition ? whenTrue : whenFalse,
+  exists: (value) => value !== void 0 && value !== null,
+  eq: (left, right) => left === right,
+  ne: (left, right) => left !== right
+};
+
+// ../core/src/derive/depGraph.ts
+function detectDerivationCycles(dependencyMap) {
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const stack = [];
+  const visit = (key) => {
+    if (visited.has(key)) {
+      return;
+    }
+    if (visiting.has(key)) {
+      const start = stack.indexOf(key);
+      const cycle = [...stack.slice(start), key].join(" -> ");
+      throw new CnosDerivedCycleError(`Derivation cycle detected: ${cycle}`);
+    }
+    visiting.add(key);
+    stack.push(key);
+    for (const dependency of dependencyMap.get(key) ?? []) {
+      visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(key);
+    visited.add(key);
+  };
+  for (const key of dependencyMap.keys()) {
+    visit(key);
+  }
+}
+
+// ../core/src/derive/parser.ts
+function isWhitespace(value) {
+  return value === " " || value === "\n" || value === "\r" || value === "	";
+}
+function skipWhitespace(state) {
+  while (isWhitespace(state.source[state.index])) {
+    state.index += 1;
+  }
+}
+function isIdentifierStart(value) {
+  return typeof value === "string" && /[A-Za-z_]/.test(value);
+}
+function isIdentifierPart(value) {
+  return typeof value === "string" && /[A-Za-z0-9_.-]/.test(value);
+}
+function errorAt(state, message) {
+  throw new CnosDerivedExpressionError(`${message} at position ${state.index + 1}`, state.source);
+}
+function parseStringLiteral(state) {
+  const quote = state.source[state.index];
+  if (quote !== "'") {
+    errorAt(state, "Expected string literal");
+  }
+  state.index += 1;
+  let value = "";
+  while (state.index < state.source.length) {
+    const current = state.source[state.index];
+    if (current === "\\") {
+      const next = state.source[state.index + 1];
+      if (next === void 0) {
+        errorAt(state, "Unterminated escape sequence");
+      }
+      value += next;
+      state.index += 2;
+      continue;
+    }
+    if (current === "'") {
+      state.index += 1;
+      return {
+        type: "literal",
+        value
+      };
+    }
+    value += current;
+    state.index += 1;
+  }
+  errorAt(state, "Unterminated string literal");
+}
+function parseNumberLiteral(state) {
+  const start = state.index;
+  while (/[0-9]/.test(state.source[state.index] ?? "")) {
+    state.index += 1;
+  }
+  if (state.source[state.index] === ".") {
+    state.index += 1;
+    while (/[0-9]/.test(state.source[state.index] ?? "")) {
+      state.index += 1;
+    }
+  }
+  return {
+    type: "literal",
+    value: Number(state.source.slice(start, state.index))
+  };
+}
+function parseIdentifier(state) {
+  if (!isIdentifierStart(state.source[state.index])) {
+    errorAt(state, "Expected identifier");
+  }
+  const start = state.index;
+  state.index += 1;
+  while (isIdentifierPart(state.source[state.index])) {
+    state.index += 1;
+  }
+  return state.source.slice(start, state.index);
+}
+function parseArguments(state) {
+  const args = [];
+  skipWhitespace(state);
+  if (state.source[state.index] === ")") {
+    state.index += 1;
+    return args;
+  }
+  while (state.index < state.source.length) {
+    args.push(parseExpressionNode(state));
+    skipWhitespace(state);
+    const current = state.source[state.index];
+    if (current === ",") {
+      state.index += 1;
+      skipWhitespace(state);
+      continue;
+    }
+    if (current === ")") {
+      state.index += 1;
+      return args;
+    }
+    errorAt(state, 'Expected "," or ")"');
+  }
+  errorAt(state, "Unterminated function call");
+}
+function parseIdentifierOrCall(state) {
+  const identifier = parseIdentifier(state);
+  skipWhitespace(state);
+  if (state.source[state.index] === "(") {
+    if (!(identifier in DERIVE_BUILTINS)) {
+      throw new CnosDerivedExpressionError(`Unknown derive function: ${identifier}`, state.source);
+    }
+    state.index += 1;
+    return {
+      type: "call",
+      name: identifier,
+      args: parseArguments(state)
+    };
+  }
+  if (identifier === "true" || identifier === "false") {
+    return {
+      type: "literal",
+      value: identifier === "true"
+    };
+  }
+  if (identifier === "null") {
+    return {
+      type: "literal",
+      value: null
+    };
+  }
+  return {
+    type: "ref",
+    path: identifier
+  };
+}
+function parseExpressionNode(state) {
+  skipWhitespace(state);
+  const current = state.source[state.index];
+  if (current === "'") {
+    return parseStringLiteral(state);
+  }
+  if (/[0-9]/.test(current ?? "")) {
+    return parseNumberLiteral(state);
+  }
+  if (isIdentifierStart(current)) {
+    return parseIdentifierOrCall(state);
+  }
+  errorAt(state, "Unexpected token");
+}
+function parseExpression(source) {
+  const state = {
+    source,
+    index: 0
+  };
+  const ast = parseExpressionNode(state);
+  skipWhitespace(state);
+  if (state.index !== source.length) {
+    errorAt(state, "Unexpected trailing input");
+  }
+  return ast;
+}
+
+// ../core/src/derive/templateParser.ts
+function toLiteral(value) {
+  return {
+    type: "literal",
+    value
+  };
+}
+function toRef(path16) {
+  return {
+    type: "ref",
+    path: path16
+  };
+}
+function parseTemplate(source) {
+  const parts = [];
+  let cursor = 0;
+  while (cursor < source.length) {
+    const start = source.indexOf("${", cursor);
+    if (start < 0) {
+      if (cursor < source.length) {
+        parts.push(toLiteral(source.slice(cursor)));
+      }
+      break;
+    }
+    if (start > cursor) {
+      parts.push(toLiteral(source.slice(cursor, start)));
+    }
+    const end = source.indexOf("}", start + 2);
+    if (end < 0) {
+      throw new CnosDerivedExpressionError(`Invalid derivation template: unclosed \${...} at position ${start + 1}`, source);
+    }
+    const ref = source.slice(start + 2, end).trim();
+    if (!ref) {
+      throw new CnosDerivedExpressionError(`Invalid derivation template: empty reference at position ${start + 1}`, source);
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(ref)) {
+      throw new CnosDerivedExpressionError(`Invalid derivation template reference "${ref}"`, source);
+    }
+    parts.push(toRef(ref));
+    cursor = end + 1;
+  }
+  if (parts.length === 0) {
+    return toLiteral("");
+  }
+  if (parts.length === 1) {
+    return parts[0];
+  }
+  return {
+    type: "call",
+    name: "concat",
+    args: parts
+  };
+}
+
+// ../core/src/derive/evaluator.ts
+function isDerivedValue(value) {
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && "$derive" in value
+  );
+}
+function extractRefs(node, refs = /* @__PURE__ */ new Set()) {
+  if (node.type === "ref") {
+    refs.add(node.path);
+    return refs;
+  }
+  if (node.type === "call") {
+    for (const arg of node.args) {
+      extractRefs(arg, refs);
+    }
+  }
+  return refs;
+}
+function parseDerivation(value) {
+  const source = typeof value.$derive === "string" ? value.$derive : value.$derive?.expr;
+  if (typeof source !== "string") {
+    throw new CnosDerivedExpressionError("Derived value requires either a template string or { expr } object");
+  }
+  const type = typeof value.$derive === "string" ? "template" : "expression";
+  const ast = type === "template" ? parseTemplate(source) : parseExpression(source);
+  const refs = Array.from(extractRefs(ast)).sort((left, right) => left.localeCompare(right));
+  return {
+    type,
+    raw: source,
+    ast,
+    refs,
+    runtimeRefs: [],
+    isRuntimeDependent: false
+  };
+}
+function normalizeConcatValue(value) {
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function evaluateNode(node, resolveRef) {
+  switch (node.type) {
+    case "literal":
+      return node.value;
+    case "ref":
+      return resolveRef(node.path);
+    case "call": {
+      const args = node.args.map((arg) => evaluateNode(arg, resolveRef));
+      switch (node.name) {
+        case "concat":
+          return args.map((value) => normalizeConcatValue(value)).join("");
+        case "coalesce":
+          return DERIVE_BUILTINS.coalesce(...args);
+        case "when":
+          return DERIVE_BUILTINS.when(args[0], args[1], args[2]);
+        case "exists":
+          return DERIVE_BUILTINS.exists(args[0]);
+        case "eq":
+          return DERIVE_BUILTINS.eq(args[0], args[1]);
+        case "ne":
+          return DERIVE_BUILTINS.ne(args[0], args[1]);
+        default:
+          throw new CnosDerivedExpressionError(`Unknown derive function: ${String(node.name)}`);
+      }
+    }
+    default:
+      throw new CnosDerivedExpressionError(`Unsupported derive AST node ${node.type ?? "unknown"}`);
+  }
+}
+function evaluateDerivation(options) {
+  const missingRefs = /* @__PURE__ */ new Set();
+  const value = evaluateNode(options.parsed.ast, (ref) => {
+    const resolved = options.resolveRef(ref);
+    if (resolved === void 0) {
+      missingRefs.add(ref);
+      options.onMissing?.(ref);
+    }
+    return resolved;
+  });
+  if (missingRefs.size > 0 && options.parsed.ast.type === "ref") {
+    throw new CnosDerivedResolutionError(
+      options.key,
+      `Unable to resolve derived config key ${options.key} because ${Array.from(missingRefs).join(", ")} is missing.`
+    );
+  }
+  return value;
+}
+
+// ../core/src/derive/validate.ts
+var FORBIDDEN_TARGET_NAMESPACES = /* @__PURE__ */ new Set(["public", "meta", "secret"]);
+var FORBIDDEN_REF_NAMESPACES = /* @__PURE__ */ new Set(["public", "secret"]);
+function validateDerivedTargetNamespace(manifest, namespace) {
+  if (FORBIDDEN_TARGET_NAMESPACES.has(namespace)) {
+    throw new CnosManifestError(`Cannot define derived values under namespace "${namespace}".`);
+  }
+  if (manifest.runtimeNamespaces[namespace]) {
+    throw new CnosManifestError(`Cannot define derived values under runtime namespace "${namespace}".`);
+  }
+}
+function validateParsedDerivation(manifest, parsed) {
+  for (const ref of parsed.refs) {
+    const namespace = ref.split(".")[0] ?? "";
+    if (FORBIDDEN_REF_NAMESPACES.has(namespace)) {
+      throw new CnosDerivedExpressionError(`Derived expressions cannot reference ${namespace}.* keys.`, parsed.raw);
+    }
+    if (manifest.runtimeNamespaces[namespace]) {
+      continue;
+    }
+    if (!manifest.namespaces[namespace] && namespace !== "value" && namespace !== "meta") {
+      throw new CnosDerivedExpressionError(`Unknown derive reference namespace: ${namespace}`, parsed.raw);
+    }
+  }
+}
+
+// ../core/src/derive/runtime.ts
+function namespaceForKey(key) {
+  return key.split(".")[0] ?? "";
+}
+function dependencyNamespaces(key, entries, memo) {
+  if (memo.has(key)) {
+    return memo.get(key);
+  }
+  const entry = entries.get(key);
+  if (!entry) {
+    memo.set(key, []);
+    return [];
+  }
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const ref of entry.parsed.refs) {
+    const namespace = namespaceForKey(ref);
+    if (!entries.has(ref)) {
+      namespaces.add(namespace);
+      continue;
+    }
+    for (const dependencyNamespace of dependencyNamespaces(ref, entries, memo)) {
+      namespaces.add(dependencyNamespace);
+    }
+  }
+  const result = Array.from(namespaces).sort((left, right) => left.localeCompare(right));
+  memo.set(key, result);
+  return result;
+}
+function isRuntimeDependentKey(key, entries, manifest, memo) {
+  if (memo.has(key)) {
+    return memo.get(key);
+  }
+  const entry = entries.get(key);
+  if (!entry) {
+    memo.set(key, false);
+    return false;
+  }
+  for (const ref of entry.parsed.refs) {
+    const namespace = namespaceForKey(ref);
+    if (manifest.runtimeNamespaces[namespace]) {
+      memo.set(key, true);
+      return true;
+    }
+    if (entries.has(ref) && isRuntimeDependentKey(ref, entries, manifest, memo)) {
+      memo.set(key, true);
+      return true;
+    }
+  }
+  memo.set(key, false);
+  return false;
+}
+function prepareEntries(graph, manifest) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const [key, entry] of graph.entries) {
+    if (!isDerivedValue(entry.value)) {
+      continue;
+    }
+    const namespaceDefinition = manifest.namespaces[entry.namespace];
+    if (!namespaceDefinition || namespaceDefinition.kind === "data") {
+      validateDerivedTargetNamespace(manifest, entry.namespace);
+    }
+    const parsed = parseDerivation(entry.value);
+    validateParsedDerivation(manifest, parsed);
+    entries.set(key, {
+      key,
+      namespace: entry.namespace,
+      value: entry.value,
+      parsed
+    });
+  }
+  detectDerivationCycles(
+    new Map(
+      Array.from(entries.values()).map((entry) => [
+        entry.key,
+        entry.parsed.refs.filter((ref) => entries.has(ref))
+      ])
+    )
+  );
+  const runtimeMemo = /* @__PURE__ */ new Map();
+  const namespaceMemo = /* @__PURE__ */ new Map();
+  for (const entry of entries.values()) {
+    entry.parsed.isRuntimeDependent = isRuntimeDependentKey(entry.key, entries, manifest, runtimeMemo);
+    entry.parsed.runtimeRefs = entry.parsed.refs.filter((ref) => manifest.runtimeNamespaces[namespaceForKey(ref)]);
+    if (entry.parsed.runtimeRefs.length === 0 && entry.parsed.isRuntimeDependent) {
+      entry.parsed.runtimeRefs = dependencyNamespaces(entry.key, entries, namespaceMemo).filter((namespace) => manifest.runtimeNamespaces[namespace]).map((namespace) => `${namespace}.*`);
+    }
+  }
+  return entries;
+}
+function createDerivedRuntimeSupport(graph, manifest, runtimeProviders) {
+  const entries = prepareEntries(graph, manifest);
+  const configCache = /* @__PURE__ */ new Map();
+  const runtimeDependencyMemo = /* @__PURE__ */ new Map();
+  const support = {};
+  Object.assign(support, {
+    runtimeProviders,
+    read(key, readBase) {
+      const namespace = namespaceForKey(key);
+      if (runtimeProviders.has(namespace)) {
+        const provider = runtimeProviders.get(namespace);
+        return provider(key.slice(namespace.length + 1));
+      }
+      if (entries.has(key)) {
+        return readDerived(key, readBase);
+      }
+      return readBase(key);
+    },
+    describe(key, readBase) {
+      const entry = entries.get(key);
+      if (!entry) {
+        return void 0;
+      }
+      const runtimeNamespaces = Array.from(
+        new Set(
+          entry.parsed.refs.map((ref) => namespaceForKey(ref)).filter((namespace) => manifest.runtimeNamespaces[namespace])
+        )
+      ).sort((left, right) => left.localeCompare(right));
+      return {
+        key,
+        type: entry.parsed.type,
+        expression: entry.parsed.raw,
+        dependencies: entry.parsed.refs.map((ref) => {
+          const namespace = namespaceForKey(ref);
+          return {
+            key: ref,
+            value: support.read(ref, readBase),
+            ...manifest.runtimeNamespaces[namespace] ? {
+              runtimeNamespace: namespace
+            } : {}
+          };
+        }),
+        runtimeDependent: entry.parsed.isRuntimeDependent,
+        runtimeNamespaces,
+        ...entry.parsed.isRuntimeDependent ? {
+          promotionWarning: "Cannot be promoted to browser/public."
+        } : {}
+      };
+    },
+    isDerivedKey(key) {
+      return entries.has(key);
+    },
+    isRuntimeDependentKey(key) {
+      if (runtimeDependencyMemo.has(key)) {
+        return runtimeDependencyMemo.get(key);
+      }
+      const value = entries.get(key)?.parsed.isRuntimeDependent ?? false;
+      runtimeDependencyMemo.set(key, value);
+      return value;
+    },
+    toConcreteValue(key, readBase, mode) {
+      const entry = entries.get(key);
+      if (!entry) {
+        return support.read(key, readBase);
+      }
+      if (!entry.parsed.isRuntimeDependent) {
+        return support.read(key, readBase);
+      }
+      if (mode === "server" || mode === "runtime") {
+        return support.read(key, readBase);
+      }
+      for (const ref of entry.parsed.refs) {
+        const namespace = namespaceForKey(ref);
+        const runtimeNamespace = manifest.runtimeNamespaces[namespace];
+        if (!runtimeNamespace) {
+          continue;
+        }
+        if (runtimeNamespace.serverOnly) {
+          throw new CnosDerivedResolutionError(
+            key,
+            `Cannot resolve ${key} for ${mode} output because it depends on runtime namespace ${namespace}.`
+          );
+        }
+        if (!runtimeProviders.has(namespace)) {
+          if (mode === "env") {
+            return void 0;
+          }
+          throw new CnosDerivedResolutionError(
+            key,
+            `Cannot resolve ${key} for ${mode} output because runtime namespace ${namespace} has no registered provider.`
+          );
+        }
+      }
+      return support.read(key, readBase);
+    },
+    toServerFormula(key) {
+      const entry = entries.get(key);
+      if (!entry || !entry.parsed.isRuntimeDependent) {
+        return void 0;
+      }
+      return {
+        expr: entry.parsed.raw,
+        deps: entry.parsed.refs.filter((ref) => !manifest.runtimeNamespaces[namespaceForKey(ref)]),
+        runtimeRefs: entry.parsed.refs.filter((ref) => manifest.runtimeNamespaces[namespaceForKey(ref)])
+      };
+    },
+    derivedKeys: Array.from(entries.keys()).sort((left, right) => left.localeCompare(right))
+  });
+  const readDerived = (key, readBase, evaluationStack = /* @__PURE__ */ new Set()) => {
+    const entry = entries.get(key);
+    if (!entry) {
+      return readBase(key);
+    }
+    if (!entry.parsed.isRuntimeDependent && configCache.has(key)) {
+      return configCache.get(key);
+    }
+    const value = evaluateDerivation({
+      key,
+      parsed: entry.parsed,
+      resolveRef: (ref) => {
+        const namespace = namespaceForKey(ref);
+        if (runtimeProviders.has(namespace)) {
+          const provider = runtimeProviders.get(namespace);
+          return provider(ref.slice(namespace.length + 1));
+        }
+        if (entries.has(ref)) {
+          if (evaluationStack.has(ref)) {
+            throw new CnosDerivedResolutionError(key, `Unable to resolve derived config key ${key} because of a recursive dependency on ${ref}.`);
+          }
+          evaluationStack.add(ref);
+          const resolved = readDerived(ref, readBase, evaluationStack);
+          evaluationStack.delete(ref);
+          return resolved;
+        }
+        return readBase(ref);
+      }
+    });
+    if (!entry.parsed.isRuntimeDependent) {
+      configCache.set(key, value);
+    }
+    return value;
+  };
+  for (const key of Array.from(entries.keys()).sort((left, right) => left.localeCompare(right))) {
+    const entry = entries.get(key);
+    if (!entry.parsed.isRuntimeDependent) {
+      readDerived(key, (ref) => graph.entries.get(ref)?.value);
+    }
+  }
+  return support;
+}
+function registerRuntimeProvider(manifest, runtimeProviders, namespace, provider) {
+  const definition = manifest.runtimeNamespaces[namespace];
+  if (!definition) {
+    throw new CnosRuntimeProviderError(`Cannot register runtime provider for undeclared namespace "${namespace}".`);
+  }
+  if (definition.builtIn) {
+    throw new CnosRuntimeProviderError(`Cannot override built-in runtime namespace "${namespace}".`);
+  }
+  runtimeProviders.set(namespace, provider);
+}
 
 // ../core/src/runtime/inspect.ts
-function inspectValue(graph, key) {
+function inspectValue(graph, key, helpers = {}) {
   const entry = graph.entries.get(key);
   if (!entry) {
     throw new CnosKeyNotFoundError(key);
   }
+  const derived = helpers.describeDerived?.(key);
   return {
     key: entry.key,
-    value: entry.value,
+    value: helpers.read ? helpers.read(entry.key) : entry.value,
     namespace: entry.namespace,
     profile: graph.profile,
     profileSource: graph.profileSource,
@@ -103,7 +760,10 @@ function inspectValue(graph, key) {
       workspaceId: override.workspaceId,
       value: override.value,
       ...override.origin ? { origin: override.origin } : {}
-    }))
+    })),
+    ...derived ? {
+      derived
+    } : {}
   };
 }
 
@@ -181,17 +841,17 @@ async function readKeychain(entry) {
 }
 
 // ../core/src/manifest/loadManifest.ts
-var import_promises3 = require("fs/promises");
-var import_node_path3 = __toESM(require("path"), 1);
+var import_promises5 = require("fs/promises");
+var import_node_path6 = __toESM(require("path"), 1);
 
 // ../core/src/utils/path.ts
-var import_promises2 = require("fs/promises");
-var import_node_os = __toESM(require("os"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
+var import_promises4 = require("fs/promises");
+var import_node_os3 = __toESM(require("os"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 
 // ../core/src/discovery/findCnosrc.ts
-var import_promises = require("fs/promises");
-var import_node_path = __toESM(require("path"), 1);
+var import_promises3 = require("fs/promises");
+var import_node_path4 = __toESM(require("path"), 1);
 
 // ../core/src/utils/yaml.ts
 var import_yaml = require("yaml");
@@ -202,10 +862,315 @@ function stringifyYaml(value) {
   return (0, import_yaml.stringify)(value);
 }
 
+// ../core/src/discovery/resolveRoot.ts
+var import_promises2 = require("fs/promises");
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_child_process4 = require("child_process");
+var import_node_os2 = __toESM(require("os"), 1);
+
+// ../core/src/discovery/parseGitUri.ts
+function isGitRootUri(uri) {
+  return /^git\+[a-z]+:\/\//i.test(uri);
+}
+function parseGitUri(uri) {
+  if (!isGitRootUri(uri)) {
+    throw new CnosDiscoveryError(`Unsupported git root URI: ${uri}`);
+  }
+  const withoutPrefix = uri.slice("git+".length);
+  const hashIndex = withoutPrefix.indexOf("#");
+  if (hashIndex < 0) {
+    throw new CnosDiscoveryError(
+      `Git root URI must include a #ref (tag, branch, or commit). Got: ${uri}`
+    );
+  }
+  const cloneUrl = withoutPrefix.slice(0, hashIndex);
+  const fragment = withoutPrefix.slice(hashIndex + 1);
+  const separatorIndex = fragment.indexOf(":");
+  const ref = (separatorIndex >= 0 ? fragment.slice(0, separatorIndex) : fragment).trim();
+  const subpath = (separatorIndex >= 0 ? fragment.slice(separatorIndex + 1) : ".cnos").trim() || ".cnos";
+  const protocol = cloneUrl.slice(0, cloneUrl.indexOf("://"));
+  if (!cloneUrl || !ref) {
+    throw new CnosDiscoveryError(
+      `Git root URI must include both a clone URL and #ref. Got: ${uri}`
+    );
+  }
+  return {
+    uri,
+    cloneUrl,
+    ref,
+    subpath,
+    transport: protocol === "https" ? "https" : protocol === "ssh" ? "ssh" : protocol === "file" ? "file" : "custom"
+  };
+}
+
+// ../core/src/discovery/cache/cacheManager.ts
+var SEMVER_TAG_RE = /^v?\d+\.\d+(?:\.\d+)?(?:[-+][A-Za-z0-9.-]+)?$/;
+var COMMIT_SHA_RE = /^[0-9a-f]{40}$/i;
+function isImmutableGitRef(ref) {
+  return SEMVER_TAG_RE.test(ref) || COMMIT_SHA_RE.test(ref);
+}
+function resolveRemoteRootCacheTtlSeconds(mode = "runtime", processEnv = process.env, override) {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 0) {
+    return override;
+  }
+  const fromEnv = Number(processEnv.CNOS_CACHE_TTL ?? "");
+  if (Number.isFinite(fromEnv) && fromEnv >= 0) {
+    return fromEnv;
+  }
+  switch (mode) {
+    case "build":
+      return 0;
+    case "dev":
+      return 30;
+    case "runtime":
+    default:
+      return 300;
+  }
+}
+function isRemoteRootCacheFresh(metadata, options) {
+  if (!metadata || options.forceRefresh) {
+    return false;
+  }
+  if (metadata.uri !== options.uri || metadata.ref !== options.ref) {
+    return false;
+  }
+  if (metadata.isImmutable) {
+    return true;
+  }
+  const ttlSeconds = resolveRemoteRootCacheTtlSeconds(
+    options.mode,
+    options.processEnv,
+    options.ttlSeconds
+  );
+  if (ttlSeconds <= 0) {
+    return false;
+  }
+  const cachedAtMs = Date.parse(metadata.cachedAt);
+  if (Number.isNaN(cachedAtMs)) {
+    return false;
+  }
+  return Date.now() - cachedAtMs <= ttlSeconds * 1e3;
+}
+
+// ../core/src/discovery/cache/cacheMetadata.ts
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+async function readRemoteRootCacheMetadata(metaPath) {
+  try {
+    const source = await (0, import_promises.readFile)(metaPath, "utf8");
+    const parsed = JSON.parse(source);
+    if (!parsed || typeof parsed.uri !== "string" || typeof parsed.cloneUrl !== "string" || typeof parsed.ref !== "string" || typeof parsed.subpath !== "string" || typeof parsed.resolvedCommit !== "string" || typeof parsed.cachedAt !== "string" || typeof parsed.isImmutable !== "boolean") {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function writeRemoteRootCacheMetadata(metaPath, metadata) {
+  await (0, import_promises.mkdir)(import_node_path.default.dirname(metaPath), { recursive: true });
+  await (0, import_promises.writeFile)(metaPath, `${JSON.stringify(metadata, null, 2)}
+`, "utf8");
+}
+
+// ../core/src/discovery/cache/cachePaths.ts
+var import_node_crypto = require("crypto");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+function resolveCnosCacheRoot(processEnv = process.env) {
+  return import_node_path2.default.resolve(
+    expandHomePath(processEnv.CNOS_CACHE_DIR ?? import_node_path2.default.join(import_node_os.default.homedir(), ".cnos", "cache"))
+  );
+}
+function createRemoteRootCacheKey(uri) {
+  return (0, import_node_crypto.createHash)("sha256").update(uri).digest("hex");
+}
+function resolveRemoteRootCachePaths(uri, processEnv = process.env) {
+  const cacheRoot = resolveCnosCacheRoot(processEnv);
+  const cacheDir = import_node_path2.default.join(cacheRoot, "roots", createRemoteRootCacheKey(uri));
+  return {
+    cacheRoot,
+    cacheDir,
+    repoDir: import_node_path2.default.join(cacheDir, "repo"),
+    metaPath: import_node_path2.default.join(cacheDir, ".cnos-cache-meta.json")
+  };
+}
+
+// ../core/src/discovery/resolveRoot.ts
+async function pathExists(targetPath) {
+  try {
+    await (0, import_promises2.access)(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function expandHomePath2(targetPath) {
+  if (targetPath === "~") {
+    return import_node_os2.default.homedir();
+  }
+  if (targetPath.startsWith("~/") || targetPath.startsWith("~\\")) {
+    return import_node_path3.default.join(import_node_os2.default.homedir(), targetPath.slice(2));
+  }
+  return targetPath;
+}
+function isLocalRootUri(rootUri) {
+  return !isGitRootUri2(rootUri) && !isCnosHostedRootUri(rootUri);
+}
+function isCnosHostedRootUri(rootUri) {
+  return rootUri.startsWith("cnos://");
+}
+function isGitRootUri2(rootUri) {
+  return rootUri.startsWith("git+");
+}
+async function runGitCommand(args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process4.spawn)("git", args, {
+      cwd: options.cwd,
+      env: options.processEnv ?? process.env,
+      shell: process.platform === "win32",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      reject(
+        new CnosDiscoveryError(
+          `Failed to run git. Make sure git is installed and available on PATH. ${error.message}`
+        )
+      );
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout.trim());
+        return;
+      }
+      const details = stderr.trim() || stdout.trim();
+      reject(
+        new CnosDiscoveryError(
+          details ? `Git command failed: ${details}` : `Git command failed with exit code ${code ?? 1}`
+        )
+      );
+    });
+  });
+}
+async function resolveLocalRoot(rootUri, cnosrcDir) {
+  const candidateRoot = rootUri.startsWith("~") ? expandHomePath2(rootUri) : rootUri;
+  const manifestRoot = import_node_path3.default.resolve(cnosrcDir, candidateRoot);
+  const manifestPath = import_node_path3.default.join(manifestRoot, "cnos.yml");
+  if (!await pathExists(manifestPath)) {
+    throw new CnosDiscoveryError(`.cnosrc.yml points to ${manifestRoot} but no cnos.yml found there.`);
+  }
+  return {
+    manifestRoot,
+    resolution: {
+      rootUri,
+      protocol: "local",
+      remote: false,
+      readOnly: false
+    }
+  };
+}
+async function ensureGitCheckout(parsed, repoDir, processEnv) {
+  const hasRepo = await pathExists(import_node_path3.default.join(repoDir, ".git"));
+  if (!hasRepo) {
+    await (0, import_promises2.mkdir)(import_node_path3.default.dirname(repoDir), { recursive: true });
+    await runGitCommand(["clone", "--no-checkout", parsed.cloneUrl, repoDir], { processEnv });
+  } else {
+    await runGitCommand(["-C", repoDir, "remote", "set-url", "origin", parsed.cloneUrl], {
+      processEnv
+    });
+  }
+  await runGitCommand(["-C", repoDir, "fetch", "--tags", "--force", "origin"], { processEnv });
+  await runGitCommand(["-C", repoDir, "checkout", "--force", parsed.ref], { processEnv });
+  await runGitCommand(["-C", repoDir, "clean", "-fdx"], { processEnv });
+}
+async function resolveGitRoot(rootUri, options = {}) {
+  const processEnv = options.processEnv ?? process.env;
+  const parsed = parseGitUri(rootUri);
+  const cachePaths = resolveRemoteRootCachePaths(rootUri, processEnv);
+  const metadata = await readRemoteRootCacheMetadata(cachePaths.metaPath);
+  const immutable = isImmutableGitRef(parsed.ref);
+  const cacheFresh = isRemoteRootCacheFresh(metadata, {
+    uri: rootUri,
+    ref: parsed.ref,
+    ...options.cacheMode ? { mode: options.cacheMode } : {},
+    processEnv,
+    ...typeof options.cacheTtlSeconds === "number" ? { ttlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  if (!cacheFresh) {
+    try {
+      await ensureGitCheckout(parsed, cachePaths.repoDir, processEnv);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const authHint = parsed.transport === "ssh" ? " Check your SSH key and git access." : " Check the URL and your git credential helper or token setup.";
+      throw new CnosDiscoveryError(`Failed to resolve remote git root ${rootUri}. ${message}${authHint}`);
+    }
+    const resolvedCommit = await runGitCommand(["-C", cachePaths.repoDir, "rev-parse", "HEAD"], {
+      processEnv
+    });
+    await writeRemoteRootCacheMetadata(cachePaths.metaPath, {
+      uri: rootUri,
+      cloneUrl: parsed.cloneUrl,
+      ref: parsed.ref,
+      subpath: parsed.subpath,
+      resolvedCommit,
+      cachedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      isImmutable: immutable
+    });
+  }
+  const nextMetadata = metadata && cacheFresh ? metadata : await readRemoteRootCacheMetadata(cachePaths.metaPath);
+  const manifestRoot = import_node_path3.default.join(cachePaths.repoDir, parsed.subpath);
+  if (!await pathExists(import_node_path3.default.join(manifestRoot, "cnos.yml"))) {
+    throw new CnosDiscoveryError(
+      `Git root ${rootUri} resolved to ${manifestRoot} but no cnos.yml was found there. Check the :subpath segment.`
+    );
+  }
+  return {
+    manifestRoot,
+    resolution: {
+      rootUri,
+      protocol: "git",
+      remote: true,
+      readOnly: true,
+      cacheDir: cachePaths.cacheDir,
+      cacheMetaPath: cachePaths.metaPath,
+      ref: parsed.ref,
+      subpath: parsed.subpath,
+      immutable,
+      ...nextMetadata?.resolvedCommit ? { resolvedCommit: nextMetadata.resolvedCommit } : {},
+      ...nextMetadata?.cachedAt ? { cachedAt: nextMetadata.cachedAt } : {}
+    }
+  };
+}
+async function resolveRootUri(rootUri, cnosrcDir, options = {}) {
+  if (isLocalRootUri(rootUri)) {
+    return resolveLocalRoot(rootUri, cnosrcDir);
+  }
+  if (isGitRootUri2(rootUri)) {
+    return resolveGitRoot(rootUri, options);
+  }
+  if (isCnosHostedRootUri(rootUri)) {
+    throw new CnosDiscoveryError(
+      `The cnos:// remote root protocol is reserved but not implemented yet. Use git+https:// or git+ssh:// for now.`
+    );
+  }
+  throw new CnosDiscoveryError(
+    `Unknown root protocol: ${rootUri}. Supported root protocols are local paths, git+https://..., and git+ssh://....`
+  );
+}
+
 // ../core/src/discovery/findCnosrc.ts
 async function exists(targetPath) {
   try {
-    await (0, import_promises.access)(targetPath);
+    await (0, import_promises3.access)(targetPath);
     return true;
   } catch {
     return false;
@@ -226,13 +1191,13 @@ function validateCnosrc(value, filePath) {
   };
 }
 async function findCnosrc(startDir = process.cwd(), maxLevels = 3) {
-  let current = import_node_path.default.resolve(startDir);
+  let current = import_node_path4.default.resolve(startDir);
   for (let depth = 0; depth <= maxLevels; depth += 1) {
-    const candidate = import_node_path.default.join(current, ".cnosrc.yml");
+    const candidate = import_node_path4.default.join(current, ".cnosrc.yml");
     if (await exists(candidate)) {
       return candidate;
     }
-    const parent = import_node_path.default.dirname(current);
+    const parent = import_node_path4.default.dirname(current);
     if (parent === current) {
       break;
     }
@@ -240,27 +1205,22 @@ async function findCnosrc(startDir = process.cwd(), maxLevels = 3) {
   }
   return void 0;
 }
-async function discoverCnosAnchor(startDir = process.cwd(), maxLevels = 3) {
+async function discoverCnosAnchor(startDir = process.cwd(), maxLevels = 3, options = {}) {
   const anchorPath = await findCnosrc(startDir, maxLevels);
   if (!anchorPath) {
     throw new CnosDiscoveryError(
       "No .cnosrc.yml found. Run cnos init or create .cnosrc.yml in your package root."
     );
   }
-  const source = await (0, import_promises.readFile)(anchorPath, "utf8");
+  const source = await (0, import_promises3.readFile)(anchorPath, "utf8");
   const parsed = validateCnosrc(parseYaml(source), anchorPath);
-  const consumerRoot = import_node_path.default.dirname(anchorPath);
-  const manifestRoot = import_node_path.default.resolve(consumerRoot, parsed.root);
-  const manifestPath = import_node_path.default.join(manifestRoot, "cnos.yml");
-  if (!await exists(manifestPath)) {
-    throw new CnosDiscoveryError(
-      `.cnosrc.yml points to ${manifestRoot} but no cnos.yml found there.`
-    );
-  }
+  const consumerRoot = import_node_path4.default.dirname(anchorPath);
+  const resolvedRoot = await resolveRootUri(parsed.root, consumerRoot, options);
   return {
     anchorPath,
     consumerRoot,
-    manifestRoot,
+    manifestRoot: resolvedRoot.manifestRoot,
+    rootResolution: resolvedRoot.resolution,
     ...parsed.workspace ? { workspace: parsed.workspace } : {}
   };
 }
@@ -270,21 +1230,21 @@ var PRIMARY_CNOS_DIR = ".cnos";
 var LEGACY_CNOS_DIR = "cnos";
 async function exists2(filePath) {
   try {
-    await (0, import_promises2.access)(filePath);
+    await (0, import_promises4.access)(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function resolveCnosRoot(root = process.cwd()) {
-  const basePath = import_node_path2.default.resolve(root);
+  const basePath = import_node_path5.default.resolve(root);
   const candidates = [
-    import_node_path2.default.join(basePath, PRIMARY_CNOS_DIR),
-    import_node_path2.default.join(basePath, LEGACY_CNOS_DIR),
+    import_node_path5.default.join(basePath, PRIMARY_CNOS_DIR),
+    import_node_path5.default.join(basePath, LEGACY_CNOS_DIR),
     basePath
   ];
   for (const candidate of candidates) {
-    if (await exists2(import_node_path2.default.join(candidate, "cnos.yml"))) {
+    if (await exists2(import_node_path5.default.join(candidate, "cnos.yml"))) {
       return candidate;
     }
   }
@@ -294,18 +1254,44 @@ async function resolveCnosRoot(root = process.cwd()) {
 }
 async function resolveManifestRoot(options = {}) {
   if (options.root) {
+    if (options.root.startsWith("git+") || options.root.startsWith("cnos://")) {
+      const consumerRoot2 = import_node_path5.default.resolve(options.cwd ?? process.cwd());
+      const resolvedRoot2 = await resolveRootUri(options.root, consumerRoot2, {
+        ...options.processEnv ? { processEnv: options.processEnv } : {},
+        ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+        ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+        ...options.forceRefresh ? { forceRefresh: true } : {}
+      });
+      return {
+        manifestRoot: resolvedRoot2.manifestRoot,
+        consumerRoot: consumerRoot2,
+        rootResolution: resolvedRoot2.resolution
+      };
+    }
     const manifestRoot = await resolveCnosRoot(options.root);
-    const resolvedRoot = import_node_path2.default.resolve(options.root);
-    const consumerRoot = import_node_path2.default.basename(manifestRoot) === PRIMARY_CNOS_DIR || import_node_path2.default.basename(manifestRoot) === LEGACY_CNOS_DIR ? import_node_path2.default.dirname(manifestRoot) : resolvedRoot;
+    const resolvedRoot = import_node_path5.default.resolve(options.root);
+    const consumerRoot = import_node_path5.default.basename(manifestRoot) === PRIMARY_CNOS_DIR || import_node_path5.default.basename(manifestRoot) === LEGACY_CNOS_DIR ? import_node_path5.default.dirname(manifestRoot) : resolvedRoot;
     return {
       manifestRoot,
-      consumerRoot
+      consumerRoot,
+      rootResolution: {
+        rootUri: manifestRoot,
+        protocol: "local",
+        remote: false,
+        readOnly: false
+      }
     };
   }
-  const discovered = await discoverCnosAnchor(options.cwd ?? process.cwd());
+  const discovered = await discoverCnosAnchor(options.cwd ?? process.cwd(), 3, {
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   return {
     manifestRoot: discovered.manifestRoot,
     consumerRoot: discovered.consumerRoot,
+    rootResolution: discovered.rootResolution,
     anchorPath: discovered.anchorPath,
     ...discovered.workspace ? { workspace: discovered.workspace } : {}
   };
@@ -318,10 +1304,10 @@ function interpolatePathTemplate(template, tokens) {
 }
 function expandHomePath(targetPath) {
   if (targetPath === "~") {
-    return import_node_os.default.homedir();
+    return import_node_os3.default.homedir();
   }
   if (targetPath.startsWith("~/") || targetPath.startsWith("~\\")) {
-    return import_node_path2.default.join(import_node_os.default.homedir(), targetPath.slice(2));
+    return import_node_path5.default.join(import_node_os3.default.homedir(), targetPath.slice(2));
   }
   return targetPath;
 }
@@ -339,7 +1325,7 @@ function stripWorkspaceTemplatePrefix(template) {
 function resolveWorkspaceScopedPath(workspaceRoot, template, tokens) {
   const relativeTemplate = stripWorkspaceTemplatePrefix(template);
   const interpolated = interpolatePathTemplate(relativeTemplate, tokens);
-  return import_node_path2.default.resolve(workspaceRoot, interpolated);
+  return import_node_path5.default.resolve(workspaceRoot, interpolated);
 }
 function toPortablePath(targetPath) {
   return targetPath.replace(/\\/g, "/");
@@ -405,6 +1391,13 @@ var DEFAULT_NAMESPACES = {
     readonly: true
   }
 };
+var DEFAULT_RUNTIME_NAMESPACES = {
+  process: {
+    description: "Live process runtime values.",
+    serverOnly: true,
+    builtIn: true
+  }
+};
 function validateResolveFrom(resolveFrom) {
   const validValues = ["cli.profile", "env.CNOS_PROFILE", "default"];
   for (const entry of resolveFrom) {
@@ -427,7 +1420,7 @@ function normalizeWorkspaceItems(items) {
 }
 function normalizeNamespaces(namespaces) {
   const normalized = Object.fromEntries(
-    Object.entries(namespaces ?? {}).map(([namespace, definition]) => [
+    Object.entries(namespaces ?? {}).filter(([namespace]) => namespace !== "runtime").map(([namespace, definition]) => [
       namespace,
       {
         kind: definition.kind ?? "data",
@@ -443,6 +1436,29 @@ function normalizeNamespaces(namespaces) {
     ...normalized
   };
 }
+function normalizeRuntimeNamespaces(namespaces) {
+  const runtimeEntries = namespaces?.runtime ?? {};
+  const normalized = Object.fromEntries(
+    Object.entries(runtimeEntries).map(([namespace, definition]) => [
+      namespace,
+      {
+        ...definition.description?.trim() ? {
+          description: definition.description.trim()
+        } : {},
+        serverOnly: definition.server_only ?? true
+      }
+    ])
+  );
+  for (const namespace of Object.keys(normalized)) {
+    if (DEFAULT_NAMESPACES[namespace] || namespace === "runtime") {
+      throw new CnosManifestError(`Runtime namespace "${namespace}" conflicts with a built-in or reserved namespace.`);
+    }
+  }
+  return {
+    ...DEFAULT_RUNTIME_NAMESPACES,
+    ...normalized
+  };
+}
 function normalizeVaults(vaults) {
   return Object.fromEntries(
     Object.entries(vaults ?? {}).map(([name, definition]) => {
@@ -534,6 +1550,7 @@ function normalizeManifest(manifest) {
   const defaultProfile = manifest.profiles?.default?.trim() || "base";
   const workspaceItems = normalizeWorkspaceItems(manifest.workspaces?.items);
   const resolveFrom = validateResolveFrom(manifest.profiles?.resolveFrom ?? DEFAULT_RESOLVE_FROM);
+  const runtimeNamespaces = normalizeRuntimeNamespaces(manifest.namespaces);
   const filesystemValues = {
     root: "./",
     format: "yaml",
@@ -607,6 +1624,7 @@ function normalizeManifest(manifest) {
       }
     },
     namespaces: normalizeNamespaces(manifest.namespaces),
+    runtimeNamespaces,
     vaults: normalizeVaults(manifest.vaults),
     writePolicy: {
       define: {
@@ -625,13 +1643,17 @@ function normalizeManifest(manifest) {
 async function loadManifest(options = {}) {
   const resolved = await resolveManifestRoot({
     ...options.root ? { root: options.root } : {},
-    ...options.cwd ? { cwd: options.cwd } : {}
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
   });
   const manifestRoot = resolved.manifestRoot;
-  const manifestPath = import_node_path3.default.join(manifestRoot, "cnos.yml");
+  const manifestPath = import_node_path6.default.join(manifestRoot, "cnos.yml");
   let source;
   try {
-    source = await (0, import_promises3.readFile)(manifestPath, "utf8");
+    source = await (0, import_promises5.readFile)(manifestPath, "utf8");
   } catch {
     throw new CnosManifestError("Unable to read CNOS manifest", manifestPath);
   }
@@ -641,10 +1663,11 @@ async function loadManifest(options = {}) {
   }
   return {
     manifestRoot,
-    repoRoot: import_node_path3.default.dirname(manifestRoot),
+    repoRoot: import_node_path6.default.dirname(manifestRoot),
     consumerRoot: resolved.consumerRoot,
     ...resolved.anchorPath ? { anchorPath: resolved.anchorPath } : {},
     ...resolved.workspace ? { anchoredWorkspace: resolved.workspace } : {},
+    rootResolution: resolved.rootResolution,
     manifestPath,
     manifest: normalizeManifest(rawManifest),
     rawManifest
@@ -652,12 +1675,12 @@ async function loadManifest(options = {}) {
 }
 
 // ../core/src/manifest/loadWorkspaceFile.ts
-var import_promises4 = require("fs/promises");
-var import_node_path4 = __toESM(require("path"), 1);
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"), 1);
 async function loadWorkspaceFile(repoRoot) {
-  const workspaceFilePath = import_node_path4.default.join(repoRoot, ".cnos-workspace.yml");
+  const workspaceFilePath = import_node_path7.default.join(repoRoot, ".cnos-workspace.yml");
   try {
-    const source = await (0, import_promises4.readFile)(workspaceFilePath, "utf8");
+    const source = await (0, import_promises6.readFile)(workspaceFilePath, "utf8");
     const parsed = parseYaml(source);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new CnosManifestError(".cnos-workspace.yml must be a YAML object", workspaceFilePath);
@@ -680,11 +1703,11 @@ async function loadWorkspaceFile(repoRoot) {
 }
 
 // ../core/src/profiles/expandProfileChain.ts
-var import_promises5 = require("fs/promises");
-var import_node_path5 = __toESM(require("path"), 1);
+var import_promises7 = require("fs/promises");
+var import_node_path8 = __toESM(require("path"), 1);
 async function fileExists(targetPath) {
   try {
-    await (0, import_promises5.access)(targetPath);
+    await (0, import_promises7.access)(targetPath);
     return true;
   } catch {
     return false;
@@ -718,11 +1741,11 @@ async function loadProfileDefinition(profileName, options) {
     return normalizeProfileDefinition(profileName, void 0);
   }
   for (const workspaceRoot of [...workspaceRoots].reverse()) {
-    const profilePath = import_node_path5.default.join(workspaceRoot.path, "profiles", `${profileName}.yml`);
+    const profilePath = import_node_path8.default.join(workspaceRoot.path, "profiles", `${profileName}.yml`);
     if (!await fileExists(profilePath)) {
       continue;
     }
-    const document = await (0, import_promises5.readFile)(profilePath, "utf8");
+    const document = await (0, import_promises7.readFile)(profilePath, "utf8");
     const parsed = parseYaml(document);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new CnosManifestError("Profile definition must be a YAML object", profilePath);
@@ -730,7 +1753,7 @@ async function loadProfileDefinition(profileName, options) {
     const definition = normalizeProfileDefinition(
       profileName,
       parsed,
-      options.manifestRoot ? toPortablePath(import_node_path5.default.relative(import_node_path5.default.dirname(options.manifestRoot), profilePath)) : toPortablePath(profilePath)
+      options.manifestRoot ? toPortablePath(import_node_path8.default.relative(import_node_path8.default.dirname(options.manifestRoot), profilePath)) : toPortablePath(profilePath)
     );
     if (definition.name !== profileName) {
       throw new CnosManifestError(
@@ -1012,8 +2035,8 @@ function createProfileAwareResolver() {
 }
 
 // ../core/src/workspaces/resolveWorkspaceContext.ts
-var import_promises6 = require("fs/promises");
-var import_node_path6 = __toESM(require("path"), 1);
+var import_promises8 = require("fs/promises");
+var import_node_path9 = __toESM(require("path"), 1);
 
 // ../core/src/workspaces/expandWorkspaceChain.ts
 function expandWorkspaceChain(workspaceId, items) {
@@ -1052,14 +2075,14 @@ function expandWorkspaceChain(workspaceId, items) {
 // ../core/src/workspaces/resolveWorkspaceContext.ts
 async function exists3(targetPath) {
   try {
-    await (0, import_promises6.access)(targetPath);
+    await (0, import_promises8.access)(targetPath);
     return true;
   } catch {
     return false;
   }
 }
 async function resolveLocalWorkspaceRoot(manifestRoot, workspaceId, manifest) {
-  const workspaceRoot = import_node_path6.default.join(manifestRoot, "workspaces", workspaceId);
+  const workspaceRoot = import_node_path9.default.join(manifestRoot, "workspaces", workspaceId);
   if (await exists3(workspaceRoot)) {
     return workspaceRoot;
   }
@@ -1067,7 +2090,7 @@ async function resolveLocalWorkspaceRoot(manifestRoot, workspaceId, manifest) {
     ([namespace, definition]) => namespace !== "value" && namespace !== "secret" && definition.kind === "data" && !definition.sensitive
   ).map(([namespace]) => namespace);
   const legacyMarkers = ["values", "secrets", "env", "profiles", ...customDataNamespaceRoots].map(
-    (segment) => import_node_path6.default.join(manifestRoot, segment)
+    (segment) => import_node_path9.default.join(manifestRoot, segment)
   );
   if ((await Promise.all(legacyMarkers.map((marker) => exists3(marker)))).some(Boolean)) {
     return manifestRoot;
@@ -1115,26 +2138,26 @@ function resolveGlobalRoot(manifest, workspaceFile, options) {
   }
   if (options.globalRoot) {
     return {
-      value: import_node_path6.default.resolve(expandHomePath(options.globalRoot)),
+      value: import_node_path9.default.resolve(expandHomePath(options.globalRoot)),
       source: "cli"
     };
   }
   if (workspaceFile?.globalRoot) {
     return {
-      value: import_node_path6.default.resolve(expandHomePath(workspaceFile.globalRoot)),
+      value: import_node_path9.default.resolve(expandHomePath(workspaceFile.globalRoot)),
       source: "workspace-file"
     };
   }
   if (manifest.workspaces.global.root) {
     return {
-      value: import_node_path6.default.resolve(expandHomePath(manifest.workspaces.global.root)),
+      value: import_node_path9.default.resolve(expandHomePath(manifest.workspaces.global.root)),
       source: "manifest"
     };
   }
   const cnosHome = options.processEnv?.CNOS_HOME;
   if (cnosHome) {
     return {
-      value: import_node_path6.default.resolve(expandHomePath(cnosHome)),
+      value: import_node_path9.default.resolve(expandHomePath(cnosHome)),
       source: "CNOS_HOME"
     };
   }
@@ -1156,7 +2179,7 @@ async function resolveWorkspaceContext(manifest, options) {
       workspaceRoots.push({
         scope: "global",
         workspaceId: chainWorkspaceId,
-        path: import_node_path6.default.join(globalRoot.value, "workspaces", globalWorkspaceId)
+        path: import_node_path9.default.join(globalRoot.value, "workspaces", globalWorkspaceId)
       });
     }
   }
@@ -1279,6 +2302,10 @@ function applySchemaRules(graph, schema) {
       }
       continue;
     }
+    if (isDerivedValue(resolvedEntry.value)) {
+      nextEntries.set(key, resolvedEntry);
+      continue;
+    }
     const coercedValue = coerceValue(resolvedEntry.value, rule);
     const nextResolvedEntry = coercedValue === resolvedEntry.value ? resolvedEntry : {
       ...resolvedEntry,
@@ -1348,26 +2375,26 @@ async function runPipeline(options) {
 }
 
 // ../core/src/secrets/auditLog.ts
-var import_promises9 = require("fs/promises");
-var import_node_path9 = __toESM(require("path"), 1);
+var import_promises11 = require("fs/promises");
+var import_node_path12 = __toESM(require("path"), 1);
 
 // ../core/src/utils/secretStore.ts
-var import_node_crypto = require("crypto");
-var import_promises8 = require("fs/promises");
-var import_node_path8 = __toESM(require("path"), 1);
+var import_node_crypto2 = require("crypto");
+var import_promises10 = require("fs/promises");
+var import_node_path11 = __toESM(require("path"), 1);
 
 // ../core/src/secrets/sessionStore.ts
-var import_promises7 = require("fs/promises");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_promises9 = require("fs/promises");
+var import_node_path10 = __toESM(require("path"), 1);
 function buildSessionRoot(processEnv = process.env) {
-  return import_node_path7.default.join(import_node_path7.default.resolve(expandHomePath(processEnv.CNOS_SECRET_HOME ?? "~/.cnos/secrets")), "sessions");
+  return import_node_path10.default.join(import_node_path10.default.resolve(expandHomePath(processEnv.CNOS_SECRET_HOME ?? "~/.cnos/secrets")), "sessions");
 }
 function buildSessionPath(vault, processEnv) {
-  return import_node_path7.default.join(buildSessionRoot(processEnv), `${vault}.json`);
+  return import_node_path10.default.join(buildSessionRoot(processEnv), `${vault}.json`);
 }
 async function readVaultSessionKey(vault, processEnv) {
   try {
-    const source = await (0, import_promises7.readFile)(buildSessionPath(vault, processEnv), "utf8");
+    const source = await (0, import_promises9.readFile)(buildSessionPath(vault, processEnv), "utf8");
     const document = JSON.parse(source);
     if (document.version !== 1 || typeof document.derivedKey !== "string") {
       return void 0;
@@ -1396,7 +2423,7 @@ function isSecretReference(value) {
   return isObject(value) && typeof value.provider === "string" && value.provider.trim().length > 0 && typeof value.ref === "string" && value.ref.trim().length > 0 && (value.vault === void 0 && true || typeof value.vault === "string" && value.vault.trim().length > 0) && Object.keys(value).every((key) => ["provider", "ref", "vault"].includes(key));
 }
 function resolveSecretStoreRoot(processEnv = process.env) {
-  return import_node_path8.default.resolve(expandHomePath(processEnv.CNOS_SECRET_HOME ?? "~/.cnos/secrets"));
+  return import_node_path11.default.resolve(expandHomePath(processEnv.CNOS_SECRET_HOME ?? "~/.cnos/secrets"));
 }
 function normalizeVaultToken(vault = "default") {
   return vault.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
@@ -1425,19 +2452,19 @@ function resolveVaultSessionKey(vault = "default", processEnv = process.env) {
   }
 }
 function deriveVaultKey(passphrase, salt, iterations = PBKDF2_ITERATIONS) {
-  return (0, import_node_crypto.pbkdf2Sync)(passphrase, salt, iterations, KEY_LENGTH, "sha512");
+  return (0, import_node_crypto2.pbkdf2Sync)(passphrase, salt, iterations, KEY_LENGTH, "sha512");
 }
 function buildMetaPath(storeRoot, vault = "default") {
-  return import_node_path8.default.join(storeRoot, "vaults", vault, META_FILENAME);
+  return import_node_path11.default.join(storeRoot, "vaults", vault, META_FILENAME);
 }
 function buildKeystorePath(storeRoot, vault = "default") {
-  return import_node_path8.default.join(storeRoot, "vaults", vault, KEYSTORE_FILENAME);
+  return import_node_path11.default.join(storeRoot, "vaults", vault, KEYSTORE_FILENAME);
 }
 function buildLegacyVaultFile(storeRoot, vault = "default") {
-  return import_node_path8.default.join(storeRoot, "vaults", `${vault}.json`);
+  return import_node_path11.default.join(storeRoot, "vaults", `${vault}.json`);
 }
 function buildLegacyVaultStoreRoot(storeRoot, vault = "default") {
-  return import_node_path8.default.join(storeRoot, "vaults", vault, "store");
+  return import_node_path11.default.join(storeRoot, "vaults", vault, "store");
 }
 function assertVaultMetadata(value, filePath) {
   if (!isObject(value)) {
@@ -1450,7 +2477,7 @@ function assertVaultMetadata(value, filePath) {
 }
 async function exists4(targetPath) {
   try {
-    await (0, import_promises8.stat)(targetPath);
+    await (0, import_promises10.stat)(targetPath);
     return true;
   } catch {
     return false;
@@ -1477,8 +2504,8 @@ async function assertNoLegacyVaultFormat(storeRoot, vault = "default") {
   );
 }
 function encryptPayload(payload, key) {
-  const iv = (0, import_node_crypto.randomBytes)(IV_LENGTH);
-  const cipher = (0, import_node_crypto.createCipheriv)("aes-256-gcm", key, iv);
+  const iv = (0, import_node_crypto2.randomBytes)(IV_LENGTH);
+  const cipher = (0, import_node_crypto2.createCipheriv)("aes-256-gcm", key, iv);
   const plaintext = Buffer.from(JSON.stringify(payload), "utf8");
   const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -1503,7 +2530,7 @@ function decryptPayload(buffer, key) {
   const iv = buffer.subarray(ivOffset, tagOffset);
   const tag = buffer.subarray(tagOffset, cipherOffset);
   const ciphertext = buffer.subarray(cipherOffset);
-  const decipher = (0, import_node_crypto.createDecipheriv)("aes-256-gcm", key, iv);
+  const decipher = (0, import_node_crypto2.createDecipheriv)("aes-256-gcm", key, iv);
   decipher.setAuthTag(tag);
   try {
     const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
@@ -1534,15 +2561,15 @@ function buildInitialPayload() {
 async function writeVaultFiles(storeRoot, vault, meta, payload, key) {
   const metaPath = buildMetaPath(storeRoot, vault);
   const keystorePath = buildKeystorePath(storeRoot, vault);
-  await (0, import_promises8.mkdir)(import_node_path8.default.dirname(metaPath), { recursive: true });
-  await (0, import_promises8.writeFile)(metaPath, stringifyYaml(meta), "utf8");
-  await (0, import_promises8.writeFile)(keystorePath, encryptPayload(payload, key));
+  await (0, import_promises10.mkdir)(import_node_path11.default.dirname(metaPath), { recursive: true });
+  await (0, import_promises10.writeFile)(metaPath, stringifyYaml(meta), "utf8");
+  await (0, import_promises10.writeFile)(keystorePath, encryptPayload(payload, key));
 }
 async function readVaultMetadata(storeRoot, vault = "default") {
   await assertNoLegacyVaultFormat(storeRoot, vault);
   const metaPath = buildMetaPath(storeRoot, vault);
   try {
-    const source = await (0, import_promises8.readFile)(metaPath, "utf8");
+    const source = await (0, import_promises10.readFile)(metaPath, "utf8");
     return assertVaultMetadata(parseYaml(source), metaPath);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -1554,7 +2581,7 @@ async function readVaultMetadata(storeRoot, vault = "default") {
 async function createSecretVault(storeRoot, vault, passphrase) {
   const normalizedVault = vault.trim() || "default";
   await assertNoLegacyVaultFormat(storeRoot, normalizedVault);
-  const salt = (0, import_node_crypto.randomBytes)(SALT_LENGTH);
+  const salt = (0, import_node_crypto2.randomBytes)(SALT_LENGTH);
   const key = deriveVaultKey(passphrase, salt, PBKDF2_ITERATIONS);
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const meta = {
@@ -1633,7 +2660,7 @@ async function loadVaultPayload(storeRoot, vault, auth) {
   if (!key) {
     throw new CnosAuthenticationError(`Vault "${vault}" requires authentication before access.`);
   }
-  const buffer = await (0, import_promises8.readFile)(buildKeystorePath(storeRoot, vault));
+  const buffer = await (0, import_promises10.readFile)(buildKeystorePath(storeRoot, vault));
   return {
     meta,
     payload: decryptPayload(buffer, key),
@@ -1708,9 +2735,9 @@ function resolveVaultDefinition(vaults, vault = "default") {
 
 // ../core/src/secrets/auditLog.ts
 async function appendAuditEvent(event, processEnv = process.env) {
-  const auditFile = processEnv.CNOS_AUDIT_FILE ?? import_node_path9.default.join(resolveSecretStoreRoot(processEnv), "audit", "access.log");
-  await (0, import_promises9.mkdir)(import_node_path9.default.dirname(auditFile), { recursive: true });
-  await (0, import_promises9.appendFile)(
+  const auditFile = processEnv.CNOS_AUDIT_FILE ?? import_node_path12.default.join(resolveSecretStoreRoot(processEnv), "audit", "access.log");
+  await (0, import_promises11.mkdir)(import_node_path12.default.dirname(auditFile), { recursive: true });
+  await (0, import_promises11.appendFile)(
     auditFile,
     `${JSON.stringify({
       ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2068,7 +3095,7 @@ function setNestedValue(target, pathSegments, value) {
   target[head] = nextTarget;
   setNestedValue(nextTarget, tail, value);
 }
-function toNamespaceObject(graph, namespace) {
+function toNamespaceObject(graph, namespace, readValueForKey = (key) => graph.entries.get(key)?.value) {
   const output = {};
   const resolvedEntries = Array.from(graph.entries.values()).sort(
     (left, right) => left.key.localeCompare(right.key)
@@ -2078,7 +3105,11 @@ function toNamespaceObject(graph, namespace) {
       continue;
     }
     const valuePath = namespace ? stripNamespace(entry.key) : entry.key;
-    setNestedValue(output, valuePath.split("."), entry.value);
+    const value = readValueForKey(entry.key);
+    if (value === void 0) {
+      continue;
+    }
+    setNestedValue(output, valuePath.split("."), value);
   }
   return output;
 }
@@ -2088,12 +3119,6 @@ function readValue(graph, key) {
   return graph.entries.get(key)?.value;
 }
 
-// ../core/src/runtime/readOr.ts
-function readOrValue(graph, key, fallback) {
-  const value = readValue(graph, key);
-  return value === void 0 ? fallback : value;
-}
-
 // ../core/src/runtime/require.ts
 function requireValue(graph, key) {
   const value = readValue(graph, key);
@@ -2103,8 +3128,38 @@ function requireValue(graph, key) {
   return value;
 }
 
+// ../core/src/runtime/runtimeProviders.ts
+function createDefaultRuntimeProviders(manifest, processEnv) {
+  const providers = /* @__PURE__ */ new Map();
+  if (manifest.runtimeNamespaces.process) {
+    providers.set("process", (key) => {
+      const segments = key.split(".");
+      if (segments[0] === "env") {
+        return processEnv[segments.slice(1).join(".")];
+      }
+      if (key === "cwd") {
+        return process.cwd();
+      }
+      if (key === "platform") {
+        return process.platform;
+      }
+      if (key === "arch") {
+        return process.arch;
+      }
+      if (key === "pid") {
+        return process.pid;
+      }
+      if (key === "node.version") {
+        return process.version;
+      }
+      return void 0;
+    });
+  }
+  return providers;
+}
+
 // ../core/src/runtime/toServerProjection.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 function stableSortObject(value) {
   return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
 }
@@ -2113,12 +3168,14 @@ function stripValuePrefix(key) {
 }
 function configHash(values) {
   const serialized = JSON.stringify(stableSortObject(values));
-  return (0, import_node_crypto2.createHash)("sha256").update(serialized).digest("hex");
+  return (0, import_node_crypto3.createHash)("sha256").update(serialized).digest("hex");
 }
-function toServerProjection(graph, manifest, cnosVersion = "0.0.0-dev") {
+function toServerProjection(graph, manifest, cnosVersion = "0.0.0-dev", helpers = {}) {
   const values = {};
+  const derived = {};
   const secretRefs = {};
   const namespaces = /* @__PURE__ */ new Set();
+  const runtimeNamespaces = /* @__PURE__ */ new Set();
   const publicKeys = Array.from(graph.entries.values()).filter((entry) => entry.namespace === "public").map((entry) => entry.key.slice("public.".length)).sort((left, right) => left.localeCompare(right));
   for (const [key, entry] of graph.entries) {
     if (entry.namespace === "secret" && isSecretReference(entry.value)) {
@@ -2130,12 +3187,33 @@ function toServerProjection(graph, manifest, cnosVersion = "0.0.0-dev") {
       continue;
     }
     if (entry.namespace === "value") {
-      values[stripValuePrefix(key)] = entry.value;
+      if (helpers.isRuntimeDependent?.(key)) {
+        const formula = helpers.toServerFormula?.(key);
+        if (formula) {
+          derived[stripValuePrefix(key)] = formula;
+          for (const ref of formula.runtimeRefs) {
+            runtimeNamespaces.add(ref.split(".")[0] ?? "");
+          }
+        }
+        continue;
+      }
+      const value = helpers.read ? helpers.read(key) : entry.value;
+      values[stripValuePrefix(key)] = value;
       continue;
     }
     const namespaceDefinition = manifest.namespaces[entry.namespace];
     if (namespaceDefinition && namespaceDefinition.kind === "data" && !namespaceDefinition.sensitive && entry.namespace !== "public") {
-      values[key] = entry.value;
+      if (helpers.isRuntimeDependent?.(key)) {
+        const formula = helpers.toServerFormula?.(key);
+        if (formula) {
+          derived[key] = formula;
+          for (const ref of formula.runtimeRefs) {
+            runtimeNamespaces.add(ref.split(".")[0] ?? "");
+          }
+        }
+        continue;
+      }
+      values[key] = helpers.read ? helpers.read(key) : entry.value;
       namespaces.add(entry.namespace);
     }
   }
@@ -2146,8 +3224,10 @@ function toServerProjection(graph, manifest, cnosVersion = "0.0.0-dev") {
     resolvedAt: graph.resolvedAt,
     configHash: configHash(values),
     values: stableSortObject(values),
+    derived: stableSortObject(derived),
     secretRefs: stableSortObject(secretRefs),
     publicKeys,
+    runtimeNamespaces: Array.from(runtimeNamespaces).sort((left, right) => left.localeCompare(right)),
     meta: {
       workspace: graph.workspace.workspaceId,
       profile: graph.profile,
@@ -2170,7 +3250,7 @@ function normalizeEnvValue(value) {
   }
   return JSON.stringify(value);
 }
-function toEnv(graph, manifest, options = {}) {
+function toEnv(graph, manifest, options = {}, helpers = {}) {
   const includeSecrets = options.includeSecrets ?? true;
   const output = {};
   const mappedEntries = Object.entries(manifest.envMapping.explicit).sort(
@@ -2191,7 +3271,11 @@ function toEnv(graph, manifest, options = {}) {
     if (isSecretReference(entry.value)) {
       continue;
     }
-    output[envVar] = normalizeEnvValue(entry.value);
+    const value = helpers.read ? helpers.read(logicalKey) : entry.value;
+    if (value === void 0) {
+      continue;
+    }
+    output[envVar] = normalizeEnvValue(value);
   }
   return output;
 }
@@ -2228,20 +3312,43 @@ function resolvePublicPrefix(manifest, options) {
   }
   return manifest.public.frameworks[options.framework] ?? "";
 }
-function toPublicEnv(graph, manifest, options = {}) {
+function toPublicEnv(graph, manifest, options = {}, helpers = {}) {
   const prefix = resolvePublicPrefix(manifest, options);
   const output = {};
   const promotions = Array.from(graph.entries.values()).filter((entry) => entry.namespace === "public").sort((left, right) => left.key.localeCompare(right.key));
   for (const resolved of promotions) {
+    if (helpers.isRuntimeDependent?.(resolved.key)) {
+      const value2 = helpers.read?.(resolved.key);
+      if (value2 === void 0) {
+        throw new CnosManifestError(`Cannot build public output for ${resolved.key} because it depends on runtime-only values.`);
+      }
+    }
     const baseEnvVar = fallbackPublicEnvVar(stripNamespace(resolved.key));
     const envVar = prefix && !baseEnvVar.startsWith(prefix) ? `${prefix}${baseEnvVar}` : baseEnvVar;
-    output[envVar] = normalizeEnvValue2(resolved.value);
+    const value = helpers.read ? helpers.read(resolved.key) : resolved.value;
+    if (value === void 0) {
+      continue;
+    }
+    output[envVar] = normalizeEnvValue2(value);
   }
   return output;
 }
 
 // ../core/src/orchestrator/runtime.ts
 function createRuntime(manifest, graph, plugins = [], secretCache, processEnv = process.env, cnosVersion = "0.0.0-dev") {
+  const runtimeProviders = createDefaultRuntimeProviders(manifest, processEnv);
+  const derivedSupport = createDerivedRuntimeSupport(graph, manifest, runtimeProviders);
+  function resolveProjectedSourceKey(key) {
+    if (!key.startsWith("public.")) {
+      return key;
+    }
+    const promotedFrom = graph.entries.get(key)?.winner.metadata?.promotedFrom;
+    if (typeof promotedFrom === "string") {
+      return promotedFrom;
+    }
+    const fallback = `value.${key.slice("public.".length)}`;
+    return graph.entries.has(fallback) ? fallback : key;
+  }
   async function refreshSecretEntry(key) {
     const entry = graph.entries.get(key);
     if (!entry || entry.namespace !== "secret" || !isSecretReference(entry.value)) {
@@ -2273,6 +3380,19 @@ function createRuntime(manifest, graph, plugins = [], secretCache, processEnv =
     }
   }
   function readLogicalKey(key) {
+    const resolved = derivedSupport.read(key, (ref) => {
+      const entry2 = graph.entries.get(ref);
+      if (!entry2) {
+        return void 0;
+      }
+      if (!secretCache) {
+        return entry2.value;
+      }
+      return resolveSecretEntryValue(ref, entry2.value, secretCache);
+    });
+    if (resolved !== void 0 || graph.entries.has(key) || manifest.runtimeNamespaces[key.split(".")[0] ?? ""]) {
+      return resolved;
+    }
     const entry = graph.entries.get(key);
     if (!entry) {
       return void 0;
@@ -2297,34 +3417,64 @@ function createRuntime(manifest, graph, plugins = [], secretCache, processEnv =
       return value;
     },
     readOr(key, fallback) {
-      return readOrValue(graph, key, fallback);
+      const value = readLogicalKey(key);
+      return value === void 0 ? fallback : value;
     },
-    value(path13) {
-      return readLogicalKey(toLogicalKey("value", path13));
+    value(path16) {
+      return readLogicalKey(toLogicalKey("value", path16));
     },
-    secret(path13) {
-      return readLogicalKey(toLogicalKey("secret", path13));
+    secret(path16) {
+      return readLogicalKey(toLogicalKey("secret", path16));
     },
-    meta(path13) {
-      return readLogicalKey(toLogicalKey("meta", path13));
+    meta(path16) {
+      return readLogicalKey(toLogicalKey("meta", path16));
     },
     inspect(key) {
-      return inspectValue(graph, key);
+      return inspectValue(graph, key, {
+        read: (ref) => readLogicalKey(ref),
+        describeDerived: (ref) => derivedSupport.describe(ref, (candidate) => {
+          const entry = graph.entries.get(candidate);
+          if (!entry) {
+            return void 0;
+          }
+          if (!secretCache) {
+            return entry.value;
+          }
+          return resolveSecretEntryValue(candidate, entry.value, secretCache);
+        })
+      });
     },
     toObject() {
-      return toNamespaceObject(graph);
+      return toNamespaceObject(graph, void 0, (key) => readLogicalKey(key));
     },
     toNamespace(namespace) {
-      return toNamespaceObject(graph, namespace);
+      return toNamespaceObject(graph, namespace, (key) => readLogicalKey(key));
     },
     toEnv(options) {
-      return toEnv(graph, manifest, options);
+      return toEnv(graph, manifest, options, {
+        read: (key) => readLogicalKey(key),
+        isRuntimeDependent: (key) => derivedSupport.isRuntimeDependentKey(key)
+      });
     },
     toPublicEnv(options) {
-      return toPublicEnv(graph, manifest, options);
+      return toPublicEnv(graph, manifest, options, {
+        read: (key) => derivedSupport.toConcreteValue(
+          resolveProjectedSourceKey(key),
+          (candidate) => readLogicalKey(candidate),
+          "public"
+        ),
+        isRuntimeDependent: (key) => derivedSupport.isRuntimeDependentKey(resolveProjectedSourceKey(key))
+      });
     },
     toServerProjection() {
-      return toServerProjection(graph, manifest, cnosVersion);
+      return toServerProjection(graph, manifest, cnosVersion, {
+        read: (key) => derivedSupport.toConcreteValue(key, (candidate) => readLogicalKey(candidate), "server"),
+        isRuntimeDependent: (key) => derivedSupport.isRuntimeDependentKey(key),
+        toServerFormula: (key) => derivedSupport.toServerFormula(key)
+      });
+    },
+    registerRuntimeProvider(namespace, provider) {
+      registerRuntimeProvider(manifest, runtimeProviders, namespace, provider);
     },
     async refreshSecrets() {
       await refreshAllSecrets();
@@ -2431,7 +3581,11 @@ function appendMetaEntries(graph, cnosVersion) {
 async function createCnos(options = {}) {
   const loadedManifest = await loadManifest({
     ...options.root ? { root: options.root } : {},
-    ...options.cwd ? { cwd: options.cwd } : {}
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
   });
   for (const key of loadedManifest.manifest.public.promote) {
     ensureProjectionAllowed(loadedManifest.manifest, key, "public");
@@ -2492,8 +3646,8 @@ async function createCnos(options = {}) {
 }
 
 // ../core/src/runtime/dump.ts
-var import_promises10 = require("fs/promises");
-var import_node_path10 = __toESM(require("path"), 1);
+var import_promises12 = require("fs/promises");
+var import_node_path13 = __toESM(require("path"), 1);
 
 // ../core/src/utils/envNaming.ts
 function normalizeMappingConfig(config = {}) {
@@ -2502,8 +3656,8 @@ function normalizeMappingConfig(config = {}) {
     explicit: config.explicit ?? {}
   };
 }
-function fromScreamingSnake(path13) {
-  return path13.split("_").map((segment) => segment.trim().toLowerCase()).filter(Boolean).join(".");
+function fromScreamingSnake(path16) {
+  return path16.split("_").map((segment) => segment.trim().toLowerCase()).filter(Boolean).join(".");
 }
 function envVarToLogicalKey(envVar, config = {}) {
   const normalized = normalizeMappingConfig(config);
@@ -2530,7 +3684,7 @@ function envVarToLogicalKey(envVar, config = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos",
-  version: "1.6.1",
+  version: "1.8.0",
   description: "Batteries-included CNOS runtime package wired with the official plugins.",
   type: "module",
   main: "./dist/index.cjs",
@@ -2729,8 +3883,8 @@ function createCliArgsPlugin() {
 }
 
 // ../../plugins/dotenv/src/index.ts
-var import_promises11 = require("fs/promises");
-var import_node_path11 = __toESM(require("path"), 1);
+var import_promises13 = require("fs/promises");
+var import_node_path14 = __toESM(require("path"), 1);
 var DOTENV_PLUGIN_ID = "@kitsy/cnos/plugins/dotenv";
 function parseDoubleQuoted(value) {
   return value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
@@ -2787,7 +3941,7 @@ function dotenvEntriesFromObject(values, mapping = {}, originFile, workspaceId =
 }
 async function readIfPresent(filePath) {
   try {
-    return await (0, import_promises11.readFile)(filePath, "utf8");
+    return await (0, import_promises13.readFile)(filePath, "utf8");
   } catch {
     return void 0;
   }
@@ -2806,7 +3960,7 @@ function createDotenvPlugin() {
           workspace: workspaceRoot.workspaceId
         });
         for (const fileName of fileNames) {
-          const absolutePath = import_node_path11.default.join(envRoot, fileName);
+          const absolutePath = import_node_path14.default.join(envRoot, fileName);
           const document = await readIfPresent(absolutePath);
           if (!document) {
             continue;
@@ -2815,7 +3969,7 @@ function createDotenvPlugin() {
             ...dotenvEntriesFromObject(
               parseDotenv(document),
               config.envMapping,
-              toPortablePath(import_node_path11.default.relative(import_node_path11.default.dirname(context.manifestRoot), absolutePath)),
+              toPortablePath(import_node_path14.default.relative(import_node_path14.default.dirname(context.manifestRoot), absolutePath)),
               workspaceRoot.workspaceId
             )
           );
@@ -2853,16 +4007,16 @@ function createPublicEnvExportPlugin() {
 }
 
 // ../../plugins/filesystem/src/filesystemSecretsReader.ts
-var import_promises13 = require("fs/promises");
+var import_promises15 = require("fs/promises");
 
 // ../../plugins/filesystem/src/helpers.ts
-var import_promises12 = require("fs/promises");
-var import_node_path12 = __toESM(require("path"), 1);
+var import_promises14 = require("fs/promises");
+var import_node_path15 = __toESM(require("path"), 1);
 var YAML_EXTENSIONS = /* @__PURE__ */ new Set([".yml", ".yaml"]);
 var FILESYSTEM_PLUGIN_ID = "@kitsy/cnos/plugins/filesystem";
 async function existsDirectory(targetPath) {
   try {
-    const stat2 = await (0, import_promises12.readdir)(targetPath);
+    const stat2 = await (0, import_promises14.readdir)(targetPath);
     void stat2;
     return true;
   } catch {
@@ -2870,15 +4024,15 @@ async function existsDirectory(targetPath) {
   }
 }
 async function collectYamlFiles(root) {
-  const entries = await (0, import_promises12.readdir)(root, { withFileTypes: true });
+  const entries = await (0, import_promises14.readdir)(root, { withFileTypes: true });
   const results = [];
   for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const absolutePath = import_node_path12.default.join(root, entry.name);
+    const absolutePath = import_node_path15.default.join(root, entry.name);
     if (entry.isDirectory()) {
       results.push(...await collectYamlFiles(absolutePath));
       continue;
     }
-    if (entry.isFile() && YAML_EXTENSIONS.has(import_node_path12.default.extname(entry.name).toLowerCase())) {
+    if (entry.isFile() && YAML_EXTENSIONS.has(import_node_path15.default.extname(entry.name).toLowerCase())) {
       results.push(absolutePath);
     }
   }
@@ -2886,16 +4040,16 @@ async function collectYamlFiles(root) {
 }
 async function collectFilesystemLayerFiles(manifestRoot, workspaceRoots, sourceRoot, activeLayers) {
   const files = [];
-  const repoRoot = import_node_path12.default.dirname(manifestRoot);
+  const repoRoot = import_node_path15.default.dirname(manifestRoot);
   for (const workspaceRoot of workspaceRoots) {
-    const resolvedRoot = import_node_path12.default.resolve(workspaceRoot.path, sourceRoot);
+    const resolvedRoot = import_node_path15.default.resolve(workspaceRoot.path, sourceRoot);
     for (const layer of activeLayers) {
-      const layerRoot = import_node_path12.default.join(resolvedRoot, layer);
+      const layerRoot = import_node_path15.default.join(resolvedRoot, layer);
       if (!await existsDirectory(layerRoot)) {
         continue;
       }
       for (const absolutePath of await collectYamlFiles(layerRoot)) {
-        const relativePath = import_node_path12.default.relative(repoRoot, absolutePath);
+        const relativePath = import_node_path15.default.relative(repoRoot, absolutePath);
         files.push({
           absolutePath,
           relativePath: toPortablePath(relativePath.startsWith("..") ? absolutePath : relativePath),
@@ -2915,7 +4069,7 @@ function assertObjectDocument(value, filePath) {
 function flattenConfigObject(value, options = {}, prefix = "") {
   return Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
     const nextKey = prefix ? `${prefix}.${key}` : key;
-    if (nestedValue && typeof nestedValue === "object" && !Array.isArray(nestedValue) && !options.stopAtLeaf?.(nestedValue)) {
+    if (nestedValue && typeof nestedValue === "object" && !Array.isArray(nestedValue) && !isDerivedValue(nestedValue) && !options.stopAtLeaf?.(nestedValue)) {
       Object.assign(
         accumulator,
         flattenConfigObject(nestedValue, options, nextKey)
@@ -2972,7 +4126,7 @@ function createFilesystemSecretsPlugin() {
       );
       const entries = [];
       for (const file of files) {
-        const document = await (0, import_promises13.readFile)(file.absolutePath, "utf8");
+        const document = await (0, import_promises15.readFile)(file.absolutePath, "utf8");
         const fileEntries = filesystemSecretsReader(file.relativePath, document, file.workspaceId);
         for (const entry of fileEntries) {
           const metadata = toSecretReferenceMetadata(entry.value);
@@ -2988,7 +4142,7 @@ function createFilesystemSecretsPlugin() {
 }
 
 // ../../plugins/filesystem/src/filesystemValuesReader.ts
-var import_promises14 = require("fs/promises");
+var import_promises16 = require("fs/promises");
 function filesystemValuesReader(filePath, document, workspaceId = "default") {
   return yamlObjectToEntries(document, filePath, "value", "filesystem-values", workspaceId);
 }
@@ -3009,7 +4163,7 @@ function createFilesystemValuesPlugin() {
       ).map(([namespace]) => namespace);
       const entries = [];
       for (const file of files) {
-        const document = await (0, import_promises14.readFile)(file.absolutePath, "utf8");
+        const document = await (0, import_promises16.readFile)(file.absolutePath, "utf8");
         entries.push(...filesystemValuesReader(file.relativePath, document, file.workspaceId));
       }
       for (const namespace of customNamespaces) {
@@ -3024,7 +4178,7 @@ function createFilesystemValuesPlugin() {
           layers
         );
         for (const file of namespaceFiles) {
-          const document = await (0, import_promises14.readFile)(file.absolutePath, "utf8");
+          const document = await (0, import_promises16.readFile)(file.absolutePath, "utf8");
           entries.push(...yamlObjectToEntries(document, file.relativePath, namespace, "filesystem-values", file.workspaceId));
         }
       }
@@ -3179,21 +4333,34 @@ async function createCnos2(options = {}) {
 
 // src/build/index.ts
 async function resolveBrowserData(options = {}) {
-  const runtime = await createCnos2(options);
+  const runtime = await createCnos2({
+    ...options,
+    cacheMode: options.cacheMode ?? "build"
+  });
   const browserData = {};
-  for (const [key, entry] of runtime.graph.entries) {
+  for (const [key] of runtime.graph.entries) {
     if (!key.startsWith("public.")) {
       continue;
     }
-    browserData[key] = entry.value;
+    const inspect = runtime.inspect(key);
+    if (inspect.derived?.runtimeDependent) {
+      throw new Error(
+        `Cannot build browser projection: ${key} depends on runtime namespaces ${inspect.derived.runtimeNamespaces.join(", ") || "runtime"}.`
+      );
+    }
+    const value = runtime.read(key);
+    if (value === void 0) {
+      continue;
+    }
+    browserData[key] = value;
   }
   return browserData;
 }
 function toScreamingSnakeSegment(segment) {
   return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
 }
-function toScreamingSnake(path13) {
-  return path13.split(".").map((segment) => toScreamingSnakeSegment(segment)).filter(Boolean).join("_");
+function toScreamingSnake(path16) {
+  return path16.split(".").map((segment) => toScreamingSnakeSegment(segment)).filter(Boolean).join("_");
 }
 function stripPublicNamespace(key) {
   return key.startsWith("public.") ? key.slice("public.".length) : key;
@@ -3225,17 +4392,26 @@ function toFrameworkEnv(browserData, framework = "generic", options = {}) {
 }
 async function resolveFrameworkEnv(options = {}, framework = "generic", envOptions = {}) {
   if (framework === "generic") {
-    const browserData = await resolveBrowserData(options);
+    const browserData = await resolveBrowserData({
+      ...options,
+      cacheMode: options.cacheMode ?? "build"
+    });
     return toFrameworkEnv(browserData, framework, envOptions);
   }
-  const runtime = await createCnos2(options);
+  const runtime = await createCnos2({
+    ...options,
+    cacheMode: options.cacheMode ?? "build"
+  });
   return runtime.toPublicEnv({
     framework,
     ...envOptions.prefix ? { prefix: envOptions.prefix } : {}
   });
 }
 async function resolveServerProjection(options = {}) {
-  const runtime = await createCnos2(options);
+  const runtime = await createCnos2({
+    ...options,
+    cacheMode: options.cacheMode ?? "build"
+  });
   return runtime.toServerProjection();
 }
 // Annotate the CommonJS export names for ESM import in node: