@kitsy/cnos 1.6.0 → 1.7.0

package/dist/internal.cjs

@@ -40,6 +40,7 @@ __export(internal_exports, {
   clearAllVaultSessionKeys: () => clearAllVaultSessionKeys,
   clearVaultSessionKey: () => clearVaultSessionKey,
   compareSchemaToGraph: () => compareSchemaToGraph,
+  createRemoteRootCacheKey: () => createRemoteRootCacheKey,
   createSecretVault: () => createSecretVault,
   createSecretVaultProvider: () => createSecretVaultProvider,
   deleteLocalSecret: () => deleteLocalSecret,
@@ -56,23 +57,32 @@ __export(internal_exports, {
   getVaultPassphraseEnvVar: () => getVaultPassphraseEnvVar,
   getVaultSessionKeyEnvVar: () => getVaultSessionKeyEnvVar,
   graphRequiresSecretHydration: () => graphRequiresSecretHydration,
+  isDerivedValue: () => isDerivedValue,
+  isImmutableGitRef: () => isImmutableGitRef,
   isPassphraseEnvRef: () => isPassphraseEnvRef,
   isSecretReference: () => isSecretReference,
   listLocalSecrets: () => listLocalSecrets,
   listSecretVaults: () => listSecretVaults,
   loadManifest: () => loadManifest,
+  normalizeDerivedValue: () => normalizeDerivedValue,
+  parseDerivation: () => parseDerivation,
+  parseGitUri: () => parseGitUri,
   parseYaml: () => parseYaml,
   proposeMapping: () => proposeMapping,
   readKeychain: () => readKeychain,
   readLocalSecret: () => readLocalSecret,
+  readRemoteRootCacheMetadata: () => readRemoteRootCacheMetadata,
   readRuntimeGraphFromEnv: () => readRuntimeGraphFromEnv,
   readServerProjectionFromEnv: () => readServerProjectionFromEnv,
   readVaultMetadata: () => readVaultMetadata,
   removeLocalVaultFiles: () => removeLocalVaultFiles,
+  resolveCnosCacheRoot: () => resolveCnosCacheRoot,
   resolveCodegenPaths: () => resolveCodegenPaths,
   resolveConfigDocumentPath: () => resolveConfigDocumentPath,
   resolveConfiguredVaultPassphrase: () => resolveConfiguredVaultPassphrase,
   resolveManifestRoot: () => resolveManifestRoot,
+  resolveRemoteRootCachePaths: () => resolveRemoteRootCachePaths,
+  resolveRootUri: () => resolveRootUri,
   resolveSecretPassphrase: () => resolveSecretPassphrase,
   resolveSecretStoreRoot: () => resolveSecretStoreRoot,
   resolveSecretVaultFile: () => resolveSecretVaultFile,
@@ -85,12 +95,15 @@ __export(internal_exports, {
   serializeSecretPayload: () => serializeSecretPayload,
   serializeServerProjection: () => serializeServerProjection,
   stringifyYaml: () => stringifyYaml,
+  validateDerivedTargetNamespace: () => validateDerivedTargetNamespace,
+  validateParsedDerivation: () => validateParsedDerivation,
   validateRuntime: () => validateRuntime,
   watchFiles: () => watchFiles,
   watchSchema: () => watchSchema,
   writeCodegenOutput: () => writeCodegenOutput,
   writeKeychain: () => writeKeychain,
   writeLocalSecret: () => writeLocalSecret,
+  writeRemoteRootCacheMetadata: () => writeRemoteRootCacheMetadata,
   writeVaultSessionKey: () => writeVaultSessionKey
 });
 module.exports = __toCommonJS(internal_exports);
@@ -124,6 +137,317 @@ var CnosAuthenticationError = class extends CnosError {
     super(message);
   }
 };
+var CnosDerivedExpressionError = class extends CnosError {
+  constructor(message, expression) {
+    super(expression ? `${message} (${expression})` : message);
+    this.expression = expression;
+  }
+  expression;
+};
+
+// ../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/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(path17) {
+  return {
+    type: "ref",
+    path: path17
+  };
+}
+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
+  };
+}
+
+// ../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);
+    }
+  }
+}
+function normalizeDerivedValue(templateOrExpr, expr = false) {
+  return expr ? {
+    $derive: {
+      expr: templateOrExpr
+    }
+  } : {
+    $derive: templateOrExpr
+  };
+}
 
 // ../core/src/keychain/linux.ts
 var import_node_child_process = require("child_process");
@@ -232,17 +556,17 @@ async function writeKeychain(entry, value) {
 }
 
 // ../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");
@@ -253,10 +577,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;
@@ -277,13 +906,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;
     }
@@ -291,27 +920,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 } : {}
   };
 }
@@ -321,21 +945,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;
     }
   }
@@ -345,42 +969,68 @@ 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 } : {}
   };
 }
 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;
 }
 function resolveNamespaceDirectory(workspaceRoot, namespace, profile) {
   const rootFolder = namespace === "value" ? "values" : namespace === "secret" ? "secrets" : namespace;
   if (profile && profile !== "base") {
-    return import_node_path2.default.resolve(workspaceRoot, "profiles", profile, rootFolder);
+    return import_node_path5.default.resolve(workspaceRoot, "profiles", profile, rootFolder);
   }
-  return import_node_path2.default.resolve(workspaceRoot, rootFolder);
+  return import_node_path5.default.resolve(workspaceRoot, rootFolder);
 }
 function resolveConfigDocumentPath(workspaceRoot, namespace, configPath, profile) {
   const namespaceRoot = resolveNamespaceDirectory(workspaceRoot, namespace, profile);
   const fileName = `${configPath.split(".").shift() ?? "app"}.yml`;
-  return import_node_path2.default.resolve(namespaceRoot, fileName);
+  return import_node_path5.default.resolve(namespaceRoot, fileName);
 }
 
 // ../core/src/manifest/normalizeManifest.ts
@@ -434,6 +1084,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) {
@@ -456,7 +1113,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",
@@ -472,6 +1129,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]) => {
@@ -563,6 +1243,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",
@@ -636,6 +1317,7 @@ function normalizeManifest(manifest) {
       }
     },
     namespaces: normalizeNamespaces(manifest.namespaces),
+    runtimeNamespaces,
     vaults: normalizeVaults(manifest.vaults),
     writePolicy: {
       define: {
@@ -654,13 +1336,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);
   }
@@ -670,10 +1356,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
@@ -681,12 +1368,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);
 
 // ../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);
 
 // ../core/src/promotions/validatePromotion.ts
 var DEFAULT_DATA_NAMESPACE = {
@@ -737,42 +1424,42 @@ function validateProjectionIssue(manifest, key, target) {
 }
 
 // ../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/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 writeVaultSessionKey(vault, derivedKey, processEnv) {
   const filePath = buildSessionPath(vault, processEnv);
-  await (0, import_promises7.mkdir)(import_node_path7.default.dirname(filePath), { recursive: true });
+  await (0, import_promises9.mkdir)(import_node_path10.default.dirname(filePath), { recursive: true });
   const document = {
     version: 1,
     vault,
     derivedKey: derivedKey.toString("hex"),
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  await (0, import_promises7.writeFile)(filePath, JSON.stringify(document, null, 2), "utf8");
+  await (0, import_promises9.writeFile)(filePath, JSON.stringify(document, null, 2), "utf8");
   return filePath;
 }
 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;
@@ -784,13 +1471,13 @@ async function readVaultSessionKey(vault, processEnv) {
   }
 }
 async function clearVaultSessionKey(vault, processEnv) {
-  await (0, import_promises7.rm)(buildSessionPath(vault, processEnv), { force: true });
+  await (0, import_promises9.rm)(buildSessionPath(vault, processEnv), { force: true });
 }
 async function clearAllVaultSessionKeys(processEnv) {
   const root = buildSessionRoot(processEnv);
   try {
-    const entries = await (0, import_promises7.readdir)(root);
-    await Promise.all(entries.map((entry) => (0, import_promises7.rm)(import_node_path7.default.join(root, entry), { force: true })));
+    const entries = await (0, import_promises9.readdir)(root);
+    await Promise.all(entries.map((entry) => (0, import_promises9.rm)(import_node_path10.default.join(root, entry), { force: true })));
   } catch {
   }
 }
@@ -812,7 +1499,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();
@@ -844,22 +1531,22 @@ 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 resolveSecretVaultFile(storeRoot, vault = "default") {
   return buildMetaPath(storeRoot, vault);
 }
 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)) {
@@ -872,7 +1559,7 @@ function assertVaultMetadata(value, filePath) {
 }
 async function exists3(targetPath) {
   try {
-    await (0, import_promises8.stat)(targetPath);
+    await (0, import_promises10.stat)(targetPath);
     return true;
   } catch {
     return false;
@@ -899,8 +1586,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();
@@ -925,7 +1612,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");
@@ -956,15 +1643,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") {
@@ -974,11 +1661,11 @@ async function readVaultMetadata(storeRoot, vault = "default") {
   }
 }
 async function listSecretVaults(storeRoot) {
-  const vaultRoot = import_node_path8.default.join(storeRoot, "vaults");
+  const vaultRoot = import_node_path11.default.join(storeRoot, "vaults");
   try {
-    const entries = await (0, import_promises8.readdir)(vaultRoot, { withFileTypes: true });
+    const entries = await (0, import_promises10.readdir)(vaultRoot, { withFileTypes: true });
     const vaults = await Promise.all(
-      entries.filter((entry) => entry.isDirectory()).map(async (entry) => await exists3(import_node_path8.default.join(vaultRoot, entry.name, META_FILENAME)) ? entry.name : void 0)
+      entries.filter((entry) => entry.isDirectory()).map(async (entry) => await exists3(import_node_path11.default.join(vaultRoot, entry.name, META_FILENAME)) ? entry.name : void 0)
     );
     return vaults.filter((value) => Boolean(value)).sort((left, right) => left.localeCompare(right));
   } catch {
@@ -988,7 +1675,7 @@ async function listSecretVaults(storeRoot) {
 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 = {
@@ -1067,7 +1754,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),
@@ -1140,14 +1827,14 @@ function resolveVaultDefinition(vaults, vault = "default") {
   };
 }
 async function removeLocalVaultFiles(storeRoot, vault = "default") {
-  await (0, import_promises8.rm)(import_node_path8.default.join(storeRoot, "vaults", vault), { recursive: true, force: true });
+  await (0, import_promises10.rm)(import_node_path11.default.join(storeRoot, "vaults", vault), { recursive: true, force: true });
 }
 
 // ../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(),
@@ -1414,11 +2101,11 @@ async function resolveVaultAuth(vaultId, definition, processEnv = process.env) {
 }
 
 // ../core/src/runtime/toServerProjection.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 
 // ../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 = {}) {
@@ -1430,8 +2117,8 @@ function normalizeMappingConfig(config = {}) {
 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(path14) {
-  return path14.split(".").map((segment) => toScreamingSnakeSegment(segment)).filter(Boolean).join("_");
+function toScreamingSnake(path17) {
+  return path17.split(".").map((segment) => toScreamingSnakeSegment(segment)).filter(Boolean).join("_");
 }
 function logicalKeyToEnvVar(key, config = {}) {
   const normalized = normalizeMappingConfig(config);
@@ -1455,6 +2142,10 @@ function logicalKeyToEnvVar(key, config = {}) {
 function flattenObject(value, prefix = "") {
   return Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
     const nextKey = prefix ? `${prefix}.${key}` : key;
+    if (isDerivedValue(nestedValue) || isSecretReference(nestedValue)) {
+      accumulator[nextKey] = nestedValue;
+      return accumulator;
+    }
     if (nestedValue && typeof nestedValue === "object" && !Array.isArray(nestedValue)) {
       Object.assign(accumulator, flattenObject(nestedValue, nextKey));
       return accumulator;
@@ -1564,7 +2255,7 @@ async function validateRuntime(runtime) {
 }
 
 // src/runtime/bootstrap.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var CNOS_GRAPH_ENV_VAR = "__CNOS_GRAPH__";
 var CNOS_PROJECTION_ENV_VAR = "__CNOS_PROJECTION__";
 var CNOS_SECRET_PAYLOAD_ENV_VAR = "__CNOS_SECRET_PAYLOAD__";
@@ -1577,7 +2268,11 @@ function deserializeServerProjection(source) {
   if (!payload || payload.version !== 1 || typeof payload.workspace !== "string" || typeof payload.profile !== "string" || typeof payload.resolvedAt !== "string" || typeof payload.configHash !== "string" || !payload.values || typeof payload.values !== "object" || Array.isArray(payload.values) || !payload.secretRefs || typeof payload.secretRefs !== "object" || Array.isArray(payload.secretRefs) || !Array.isArray(payload.publicKeys) || !payload.meta || typeof payload.meta !== "object") {
     throw new Error("Invalid CNOS server projection payload");
   }
-  return payload;
+  return {
+    ...payload,
+    derived: payload.derived && typeof payload.derived === "object" && !Array.isArray(payload.derived) ? payload.derived : {},
+    runtimeNamespaces: Array.isArray(payload.runtimeNamespaces) ? payload.runtimeNamespaces : []
+  };
 }
 function serializeRuntimeGraph(graph) {
   const payload = {
@@ -1622,15 +2317,15 @@ function decryptSecretPayload(serialized, sessionKey) {
   const iv = Buffer.from(payload.iv, "base64");
   const tag = Buffer.from(payload.tag, "base64");
   const ciphertext = Buffer.from(payload.ciphertext, "base64");
-  const decipher = (0, import_node_crypto3.createDecipheriv)("aes-256-gcm", key, iv);
+  const decipher = (0, import_node_crypto4.createDecipheriv)("aes-256-gcm", key, iv);
   decipher.setAuthTag(tag);
   const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
   return JSON.parse(plaintext);
 }
 function serializeSecretPayload(values) {
-  const key = (0, import_node_crypto3.randomBytes)(32);
-  const iv = (0, import_node_crypto3.randomBytes)(12);
-  const cipher = (0, import_node_crypto3.createCipheriv)("aes-256-gcm", key, iv);
+  const key = (0, import_node_crypto4.randomBytes)(32);
+  const iv = (0, import_node_crypto4.randomBytes)(12);
+  const cipher = (0, import_node_crypto4.createCipheriv)("aes-256-gcm", key, iv);
   const ciphertext = Buffer.concat([cipher.update(JSON.stringify(values), "utf8"), cipher.final()]);
   const tag = cipher.getAuthTag();
   return {
@@ -1703,10 +2398,10 @@ function buildNamespaceInterfaces(schema) {
       continue;
     }
     const namespace = logicalKey.slice(0, separatorIndex);
-    const path14 = logicalKey.slice(separatorIndex + 1);
+    const path17 = logicalKey.slice(separatorIndex + 1);
     const existing = namespaceGroups.get(namespace) ?? [];
     existing.push({
-      key: path14,
+      key: path17,
       rule
     });
     namespaceGroups.set(namespace, existing);
@@ -1811,15 +2506,15 @@ function generateCodegenContent(manifest, sourcePath, typeModuleImport = "./cnos
 }
 
 // src/codegen/writeOutput.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);
 function stripTsExtension(filePath) {
   return filePath.replace(/(\.d)?\.[cm]?tsx?$/i, "").replace(/\.[cm]?jsx?$/i, "");
 }
 function resolveCodegenPaths(repoRoot, out) {
-  const typesPath = out ? import_node_path11.default.resolve(repoRoot, out) : import_node_path11.default.join(repoRoot, ".cnos", "types", "cnos.d.ts");
-  const runtimePath = import_node_path11.default.join(import_node_path11.default.dirname(typesPath), "runtime.ts");
-  const typeImportPath = `./${import_node_path11.default.basename(stripTsExtension(typesPath))}`;
+  const typesPath = out ? import_node_path14.default.resolve(repoRoot, out) : import_node_path14.default.join(repoRoot, ".cnos", "types", "cnos.d.ts");
+  const runtimePath = import_node_path14.default.join(import_node_path14.default.dirname(typesPath), "runtime.ts");
+  const typeImportPath = `./${import_node_path14.default.basename(stripTsExtension(typesPath))}`;
   return {
     typesPath,
     runtimePath,
@@ -1828,12 +2523,13 @@ function resolveCodegenPaths(repoRoot, out) {
 }
 async function writeCodegenOutput(options = {}) {
   const loadedManifest = await loadManifest(options.root ? { root: options.root } : {});
-  const paths = resolveCodegenPaths(loadedManifest.repoRoot, options.out);
+  const outputRoot = loadedManifest.rootResolution.remote ? loadedManifest.consumerRoot : loadedManifest.repoRoot;
+  const paths = resolveCodegenPaths(outputRoot, options.out);
   const generated = generateCodegenContent(loadedManifest.manifest, loadedManifest.manifestPath, paths.typeImportPath);
-  await (0, import_promises11.mkdir)(import_node_path11.default.dirname(paths.typesPath), { recursive: true });
-  await (0, import_promises11.mkdir)(import_node_path11.default.dirname(paths.runtimePath), { recursive: true });
-  await (0, import_promises11.writeFile)(paths.typesPath, generated.typesContent, "utf8");
-  await (0, import_promises11.writeFile)(paths.runtimePath, generated.runtimeContent, "utf8");
+  await (0, import_promises13.mkdir)(import_node_path14.default.dirname(paths.typesPath), { recursive: true });
+  await (0, import_promises13.mkdir)(import_node_path14.default.dirname(paths.runtimePath), { recursive: true });
+  await (0, import_promises13.writeFile)(paths.typesPath, generated.typesContent, "utf8");
+  await (0, import_promises13.writeFile)(paths.runtimePath, generated.runtimeContent, "utf8");
   return {
     manifestPath: loadedManifest.manifestPath,
     typesPath: paths.typesPath,
@@ -2019,7 +2715,7 @@ function formatDriftReport(report) {
 }
 
 // src/migrate/applyManifest.ts
-var import_promises12 = require("fs/promises");
+var import_promises14 = require("fs/promises");
 function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
 }
@@ -2054,7 +2750,7 @@ async function applyManifestMappings(proposals, root) {
       promote: Array.from(promoted).sort((left, right) => left.localeCompare(right))
     };
   }
-  await (0, import_promises12.writeFile)(loadedManifest.manifestPath, stringifyYaml(rawManifest), "utf8");
+  await (0, import_promises14.writeFile)(loadedManifest.manifestPath, stringifyYaml(rawManifest), "utf8");
   return {
     manifestPath: loadedManifest.manifestPath,
     appliedMappings,
@@ -2089,7 +2785,7 @@ function proposeMapping(envVar) {
 }
 
 // src/migrate/rewriteSource.ts
-var import_promises13 = require("fs/promises");
+var import_promises15 = require("fs/promises");
 function importStatementFor(kind) {
   return kind === "import-meta-env" ? "import cnos from '@kitsy/cnos/browser';" : "import cnos from '@kitsy/cnos';";
 }
@@ -2110,7 +2806,7 @@ async function rewriteSourceFiles(usages, proposals) {
   const backupFiles = [];
   const skippedUsages = [];
   for (const [filePath, fileUsages] of fileGroups.entries()) {
-    const original = await (0, import_promises13.readFile)(filePath, "utf8");
+    const original = await (0, import_promises15.readFile)(filePath, "utf8");
     let nextSource = original;
     let changed = false;
     const importKinds = /* @__PURE__ */ new Set();
@@ -2137,7 +2833,7 @@ async function rewriteSourceFiles(usages, proposals) {
       continue;
     }
     const backupPath = `${filePath}.bak`;
-    await (0, import_promises13.copyFile)(filePath, backupPath);
+    await (0, import_promises15.copyFile)(filePath, backupPath);
     backupFiles.push(backupPath);
     for (const kind of Array.from(importKinds)) {
       const importStatement = importStatementFor(kind);
@@ -2146,7 +2842,7 @@ async function rewriteSourceFiles(usages, proposals) {
 ${nextSource}`;
       }
     }
-    await (0, import_promises13.writeFile)(filePath, nextSource, "utf8");
+    await (0, import_promises15.writeFile)(filePath, nextSource, "utf8");
     rewrittenFiles.push(filePath);
   }
   return {
@@ -2157,18 +2853,18 @@ ${nextSource}`;
 }
 
 // src/migrate/scanEnvUsage.ts
-var import_promises14 = require("fs/promises");
-var import_node_path12 = __toESM(require("path"), 1);
+var import_promises16 = require("fs/promises");
+var import_node_path15 = __toESM(require("path"), 1);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"]);
 var PROCESS_ENV_DOT = /process\.env\.([A-Z][A-Z0-9_]*)/g;
 var PROCESS_ENV_BRACKET = /process\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/g;
 var IMPORT_META_ENV_DOT = /import\.meta\.env\.([A-Z][A-Z0-9_]*)/g;
 var IMPORT_META_ENV_BRACKET = /import\.meta\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/g;
 async function collectFiles(root) {
-  const entries = await (0, import_promises14.readdir)(root, { withFileTypes: true });
+  const entries = await (0, import_promises16.readdir)(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const filePath = import_node_path12.default.join(root, entry.name);
+    const filePath = import_node_path15.default.join(root, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git") {
         continue;
@@ -2176,7 +2872,7 @@ async function collectFiles(root) {
       files.push(...await collectFiles(filePath));
       continue;
     }
-    if (SOURCE_EXTENSIONS.has(import_node_path12.default.extname(entry.name))) {
+    if (SOURCE_EXTENSIONS.has(import_node_path15.default.extname(entry.name))) {
       files.push(filePath);
     }
   }
@@ -2202,7 +2898,7 @@ async function scanEnvUsage(scanRoot) {
   const files = await collectFiles(scanRoot);
   const usages = [];
   for (const filePath of files) {
-    const source = await (0, import_promises14.readFile)(filePath, "utf8");
+    const source = await (0, import_promises16.readFile)(filePath, "utf8");
     usages.push(...collectMatches(filePath, source, PROCESS_ENV_DOT, "process-env"));
     usages.push(...collectMatches(filePath, source, PROCESS_ENV_BRACKET, "process-env"));
     usages.push(...collectMatches(filePath, source, IMPORT_META_ENV_DOT, "import-meta-env"));
@@ -2243,7 +2939,7 @@ function diffGraphs(previous, next) {
 }
 
 // src/watch/watchFiles.ts
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 async function watchFiles(runtime, root) {
   const manifest = await loadManifest(root ? { root } : {});
   const roots = Array.from(
@@ -2251,7 +2947,7 @@ async function watchFiles(runtime, root) {
   ).sort((left, right) => left.localeCompare(right));
   const files = Array.from(
     new Set(
-      Array.from(runtime.graph.entries.values()).map((entry) => entry.winner.origin?.file).filter((file) => Boolean(file)).map((file) => import_node_path13.default.resolve(manifest.repoRoot, file))
+      Array.from(runtime.graph.entries.values()).map((entry) => entry.winner.origin?.file).filter((file) => Boolean(file)).map((file) => import_node_path16.default.resolve(manifest.repoRoot, file))
     )
   ).sort((left, right) => left.localeCompare(right));
   return {
@@ -2272,6 +2968,7 @@ async function watchFiles(runtime, root) {
   clearAllVaultSessionKeys,
   clearVaultSessionKey,
   compareSchemaToGraph,
+  createRemoteRootCacheKey,
   createSecretVault,
   createSecretVaultProvider,
   deleteLocalSecret,
@@ -2288,23 +2985,32 @@ async function watchFiles(runtime, root) {
   getVaultPassphraseEnvVar,
   getVaultSessionKeyEnvVar,
   graphRequiresSecretHydration,
+  isDerivedValue,
+  isImmutableGitRef,
   isPassphraseEnvRef,
   isSecretReference,
   listLocalSecrets,
   listSecretVaults,
   loadManifest,
+  normalizeDerivedValue,
+  parseDerivation,
+  parseGitUri,
   parseYaml,
   proposeMapping,
   readKeychain,
   readLocalSecret,
+  readRemoteRootCacheMetadata,
   readRuntimeGraphFromEnv,
   readServerProjectionFromEnv,
   readVaultMetadata,
   removeLocalVaultFiles,
+  resolveCnosCacheRoot,
   resolveCodegenPaths,
   resolveConfigDocumentPath,
   resolveConfiguredVaultPassphrase,
   resolveManifestRoot,
+  resolveRemoteRootCachePaths,
+  resolveRootUri,
   resolveSecretPassphrase,
   resolveSecretStoreRoot,
   resolveSecretVaultFile,
@@ -2317,11 +3023,14 @@ async function watchFiles(runtime, root) {
   serializeSecretPayload,
   serializeServerProjection,
   stringifyYaml,
+  validateDerivedTargetNamespace,
+  validateParsedDerivation,
   validateRuntime,
   watchFiles,
   watchSchema,
   writeCodegenOutput,
   writeKeychain,
   writeLocalSecret,
+  writeRemoteRootCacheMetadata,
   writeVaultSessionKey
 });