@celilo/cli 0.3.30 → 0.4.0-alpha.0

package/src/variables/computed/computed-integration.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Integration test: computed capability fields end-to-end through the
+ * DB-backed resolver. Exercises registration folding a `computed:` entry
+ * into stored capability data, then resolving `$capability:X.field` by
+ * evaluating the DSL in the provider's context (typed secret lookup).
+ *
+ * Isolation: CELILO_DATA_DIR is pointed at a temp dir and a throwaway master
+ * key is written there, so this never touches the operator's real key/db.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerModuleCapabilities } from '../../capabilities/registration';
+import { type DbClient, closeDb, createDbClient } from '../../db/client';
+import type { ModuleManifest } from '../../manifest/schema';
+import { encryptSecret } from '../../secrets/encryption';
+import { generateMasterKey, writeMasterKey } from '../../secrets/master-key';
+import { buildResolutionContext } from '../context';
+import { parseVariables } from '../parser';
+import { resolveVariable } from '../resolver';
+import type { ResolutionContext } from '../types';
+import { COMPUTED_MARKER_KEY } from './marker';
+
+let testDir: string;
+let originalDataDir: string | undefined;
+let db: DbClient;
+
+/** Fresh manifest per call — never share a mutable manifest across tests. */
+function namecheapManifest(computedValue = 'keys(secret.ddns_passwords)'): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'namecheap',
+    name: 'Namecheap',
+    version: '4.1.0',
+    description: 'test',
+    provides: {
+      capabilities: [
+        {
+          name: 'dns_registrar',
+          version: '4.1.0',
+          data: { provider: 'namecheap' },
+          computed: [{ name: 'domain_list', type: 'computed', value: computedValue }],
+        },
+      ],
+    },
+  } as unknown as ModuleManifest;
+}
+
+/** Build a resolution context whose capabilities map comes from the DB. */
+function contextFromDb(moduleId: string): ResolutionContext {
+  const rows = db.$client.prepare('SELECT capability_name, data FROM capabilities').all() as Array<{
+    capability_name: string;
+    data: string;
+  }>;
+  const capMap: Record<string, Record<string, unknown>> = {};
+  for (const row of rows) {
+    capMap[row.capability_name] = JSON.parse(row.data);
+  }
+  return {
+    moduleId,
+    selfConfig: {},
+    systemConfig: {},
+    systemSecrets: {},
+    secrets: {},
+    capabilities: capMap,
+  };
+}
+
+beforeEach(async () => {
+  testDir = mkdtempSync(join(tmpdir(), 'celilo-computed-'));
+  originalDataDir = process.env.CELILO_DATA_DIR;
+  process.env.CELILO_DATA_DIR = testDir;
+  await writeMasterKey(generateMasterKey());
+
+  db = createDbClient({ path: join(testDir, 'test.db') });
+
+  db.$client
+    .prepare(
+      'INSERT INTO modules (id, name, version, state, manifest_data, source_path) VALUES (?, ?, ?, ?, ?, ?)',
+    )
+    .run('namecheap', 'Namecheap', '4.1.0', 'INSTALLED', '{}', '/tmp/namecheap');
+  db.$client
+    .prepare(
+      'INSERT INTO modules (id, name, version, state, manifest_data, source_path) VALUES (?, ?, ?, ?, ?, ?)',
+    )
+    .run('technitium', 'Technitium', '1.0.0', 'INSTALLED', '{}', '/tmp/technitium');
+
+  // namecheap's ddns_passwords secret: a JSON map of domain -> password.
+  // Encrypt with the SAME master key the resolver will decrypt with (the one
+  // beforeEach wrote into CELILO_DATA_DIR).
+  const enc = encryptSecret(
+    JSON.stringify({ 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' }),
+    await loadTestMasterKey(),
+  );
+  db.$client
+    .prepare(
+      'INSERT INTO secrets (module_id, name, encrypted_value, iv, auth_tag) VALUES (?, ?, ?, ?, ?)',
+    )
+    .run('namecheap', 'ddns_passwords', enc.encryptedValue, enc.iv, enc.authTag);
+});
+
+afterEach(() => {
+  closeDb();
+  process.env.CELILO_DATA_DIR = originalDataDir;
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+/** Read the master key that beforeEach wrote into CELILO_DATA_DIR. */
+async function loadTestMasterKey(): Promise<Buffer> {
+  const { readMasterKey } = await import('../../secrets/master-key');
+  return readMasterKey();
+}
+
+describe('computed capability fields — DB integration', () => {
+  test('registration folds a computed field into stored data as a marker', async () => {
+    await registerModuleCapabilities('namecheap', namecheapManifest(), db.$client);
+
+    const row = db.$client
+      .prepare('SELECT data FROM capabilities WHERE capability_name = ?')
+      .get('dns_registrar') as { data: string };
+    const data = JSON.parse(row.data);
+    expect(data.provider).toBe('namecheap');
+    expect(data.domain_list).toEqual({ [COMPUTED_MARKER_KEY]: 'keys(secret.ddns_passwords)' });
+  });
+
+  test('resolver evaluates the computed field in the provider context', async () => {
+    await registerModuleCapabilities('namecheap', namecheapManifest(), db.$client);
+
+    const ref = parseVariables('$capability:dns_registrar.domain_list')[0];
+    const result = await resolveVariable(ref, contextFromDb('technitium'), db);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      // Non-scalar computed results serialize to JSON in the string path.
+      expect(JSON.parse(result.value)).toEqual(['lunacycle.net', 'celilo.computer']);
+    }
+  });
+
+  test('a static field alongside the computed one still resolves', async () => {
+    await registerModuleCapabilities('namecheap', namecheapManifest(), db.$client);
+
+    const ref = parseVariables('$capability:dns_registrar.provider')[0];
+    const result = await resolveVariable(ref, contextFromDb('technitium'), db);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.value).toBe('namecheap');
+  });
+
+  test('a computed field referencing a missing secret yields a clear error', async () => {
+    await registerModuleCapabilities(
+      'namecheap',
+      namecheapManifest('keys(secret.nope)'),
+      db.$client,
+    );
+
+    const ref = parseVariables('$capability:dns_registrar.domain_list')[0];
+    const result = await resolveVariable(ref, contextFromDb('technitium'), db);
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.error).toMatch(/could not be resolved|Failed to evaluate/);
+  });
+
+  // Gap B (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md step 3): buildResolutionContext
+  // must EAGERLY evaluate computed markers into the capabilities map, so the
+  // `variables.imports` path (which reads context.capabilities directly, not via
+  // resolveVariable) sees the real array.
+  test('buildResolutionContext pre-evaluates the computed field into the capabilities map', async () => {
+    await registerModuleCapabilities('namecheap', namecheapManifest(), db.$client);
+
+    const ctx = await buildResolutionContext('technitium', db);
+    const reg = ctx.capabilities.dns_registrar as Record<string, unknown>;
+
+    // The real array, not the raw marker object.
+    expect(reg.domain_list).toEqual(['lunacycle.net', 'celilo.computer']);
+    expect(reg.provider).toBe('namecheap');
+  });
+
+  test('a provider whose computed field fails to evaluate does not break context build', async () => {
+    await registerModuleCapabilities(
+      'namecheap',
+      namecheapManifest('keys(secret.nope)'),
+      db.$client,
+    );
+
+    // Build context for an unrelated consumer — must not throw despite the
+    // un-evaluable marker (best-effort: leaves the marker in place).
+    const ctx = await buildResolutionContext('technitium', db);
+    const reg = ctx.capabilities.dns_registrar as Record<string, unknown>;
+    expect(reg.provider).toBe('namecheap');
+    expect(reg.domain_list).toEqual({ [COMPUTED_MARKER_KEY]: 'keys(secret.nope)' });
+  });
+});

package/src/variables/computed/computed.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from 'bun:test';
+import { ComputedEvalError, type LookupFn, evaluateComputed } from './evaluate';
+import { ComputedParseError, parseComputed } from './parse';
+
+/**
+ * A lookup over a fixed fixture, mirroring how the resolver will map
+ * roots (self/system/secret/...) onto live data. Returns undefined for
+ * anything absent so the evaluator's missing-ref path is exercised.
+ */
+function makeLookup(data: Record<string, unknown>): LookupFn {
+  return (root, path) => {
+    let current: unknown = data[root];
+    for (const seg of path) {
+      if (current && typeof current === 'object' && seg in (current as Record<string, unknown>)) {
+        current = (current as Record<string, unknown>)[seg];
+      } else {
+        return undefined;
+      }
+    }
+    return current;
+  };
+}
+
+const FIXTURE = {
+  secret: {
+    ddns_passwords: { 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' },
+  },
+  self: {
+    zone_names: { dmz: 'DMZ', app: 'App' },
+    upstreams: [{ ip: '1.1.1.1' }, { ip: '8.8.8.8' }],
+    primary_domains: ['a.net', 'b.net'],
+    extra_domains: ['b.net', 'c.net'],
+    hostname: 'dns-int',
+    zones_with_dupes: ['x', 'y', 'x', 'z', 'y'],
+  },
+  system: {
+    primary_domain: 'lunacycle.net',
+  },
+};
+
+function evalOk(expr: string): unknown {
+  return evaluateComputed(expr, makeLookup(FIXTURE));
+}
+
+describe('computed DSL — keys', () => {
+  test('keys of the ddns_passwords secret map (the domain_list case)', () => {
+    expect(evalOk('keys(secret.ddns_passwords)')).toEqual(['lunacycle.net', 'celilo.computer']);
+  });
+
+  test('keys of a non-secret object', () => {
+    expect(evalOk('keys(self.zone_names)')).toEqual(['dmz', 'app']);
+  });
+});
+
+describe('computed DSL — values', () => {
+  test('values of a NON-secret map is allowed', () => {
+    expect(evalOk('values(self.zone_names)')).toEqual(['DMZ', 'App']);
+  });
+
+  test('values of a secret map is REJECTED (projection rule)', () => {
+    expect(() => evalOk('values(secret.ddns_passwords)')).toThrow(ComputedEvalError);
+    expect(() => evalOk('values(secret.ddns_passwords)')).toThrow(/leak/i);
+  });
+
+  test('keys of a secret map is allowed (key names are non-sensitive)', () => {
+    expect(evalOk('keys(secret.ddns_passwords)')).toEqual(['lunacycle.net', 'celilo.computer']);
+  });
+});
+
+describe('computed DSL — map', () => {
+  test('projects a field from a list of objects', () => {
+    expect(evalOk('map(self.upstreams, ip)')).toEqual(['1.1.1.1', '8.8.8.8']);
+  });
+
+  test('errors when an element is not an object', () => {
+    expect(() => evalOk('map(self.primary_domains, ip)')).toThrow(ComputedEvalError);
+  });
+
+  test('errors when the field arg is not a bare identifier', () => {
+    expect(() => evalOk("map(self.upstreams, 'ip')")).toThrow(/bare field name/);
+  });
+});
+
+describe('computed DSL — concat + unique (nesting/chaining)', () => {
+  test('concat flattens multiple arrays', () => {
+    expect(evalOk('concat(self.primary_domains, self.extra_domains)')).toEqual([
+      'a.net',
+      'b.net',
+      'b.net',
+      'c.net',
+    ]);
+  });
+
+  test('unique dedupes', () => {
+    expect(evalOk('unique(self.zones_with_dupes)')).toEqual(['x', 'y', 'z']);
+  });
+
+  test('nested calls chain: unique(concat(...))', () => {
+    expect(evalOk('unique(concat(self.primary_domains, self.extra_domains))')).toEqual([
+      'a.net',
+      'b.net',
+      'c.net',
+    ]);
+  });
+});
+
+describe('computed DSL — format', () => {
+  test('interpolates named parts', () => {
+    expect(evalOk("format('{host}.{zone}', host=self.hostname, zone=system.primary_domain)")).toBe(
+      'dns-int.lunacycle.net',
+    );
+  });
+
+  test('errors when template references an unsupplied part', () => {
+    expect(() => evalOk("format('{host}.{missing}', host=self.hostname)")).toThrow(
+      /no such named argument/,
+    );
+  });
+
+  test('errors when a non-template arg is positional', () => {
+    expect(() => evalOk("format('{a}', self.hostname)")).toThrow(/must be named/);
+  });
+});
+
+describe('computed DSL — reference & arity errors', () => {
+  test('missing reference throws', () => {
+    expect(() => evalOk('keys(secret.nonexistent)')).toThrow(/could not be resolved/);
+  });
+
+  test('keys on a non-object throws', () => {
+    expect(() => evalOk('keys(self.hostname)')).toThrow(/expects an object/);
+  });
+
+  test('unknown function is rejected', () => {
+    expect(() => evalOk('frobnicate(self.hostname)')).toThrow(/Unknown function/);
+  });
+
+  test('wrong arity is rejected', () => {
+    expect(() => evalOk('keys(self.zone_names, self.upstreams)')).toThrow(/expects 1 argument/);
+  });
+
+  test('named arg to a function that does not take them is rejected', () => {
+    expect(() => evalOk('keys(x=self.zone_names)')).toThrow(/does not take named arguments/);
+  });
+});
+
+describe('computed DSL — parser', () => {
+  test('parses a simple call to a ref-arg AST', () => {
+    const ast = parseComputed('keys(secret.ddns_passwords)');
+    expect(ast).toEqual({
+      kind: 'call',
+      fn: 'keys',
+      args: [{ value: { kind: 'ref', root: 'secret', path: ['ddns_passwords'] } }],
+    });
+  });
+
+  test('parses nested calls', () => {
+    const ast = parseComputed('unique(concat(self.a, self.b))');
+    expect(ast.kind).toBe('call');
+  });
+
+  test('empty expression is a parse error', () => {
+    expect(() => parseComputed('')).toThrow(ComputedParseError);
+  });
+
+  test('unterminated string is a parse error', () => {
+    expect(() => parseComputed("format('{a}")).toThrow(/unterminated string/);
+  });
+
+  test('trailing input is a parse error', () => {
+    expect(() => parseComputed('keys(self.x) extra')).toThrow(/trailing input/);
+  });
+
+  test('unexpected character is a parse error', () => {
+    expect(() => parseComputed('keys(self.x) + 1')).toThrow(ComputedParseError);
+  });
+});

package/src/variables/computed/evaluate.ts

@@ -0,0 +1,271 @@
+/**
+ * Evaluator for the computed-variable DSL.
+ *
+ * Pure: given an AST (from `parse.ts`) and a `lookup` callback that
+ * resolves a variable reference to a value, it produces the computed
+ * value. No DB, no I/O, no `ResolutionContext` coupling — the caller
+ * supplies `lookup`, which keeps this unit-testable and lets the resolver
+ * integration (a later step) decide how refs map onto live data.
+ *
+ * The function allow-list is the v1 set from
+ * v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md (D1.1):
+ *   keys, values, map, concat, unique, format
+ *
+ * Secret-projection rule: `values(secret.*)` is rejected — it would leak
+ * secret values. `keys(secret.*)` is allowed (key names are non-sensitive).
+ */
+
+import { asComputedExpression } from './marker';
+import { type Arg, type Node, type RefNode, parseComputed } from './parse';
+
+export class ComputedEvalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ComputedEvalError';
+  }
+}
+
+/**
+ * Resolves a variable reference to its value.
+ * `root` is e.g. "secret", `path` is the remaining segments.
+ * Returns `undefined` if the reference doesn't exist.
+ */
+export type LookupFn = (root: string, path: string[]) => unknown;
+
+const ALLOWED_FUNCTIONS = new Set(['keys', 'values', 'map', 'concat', 'unique', 'format']);
+
+interface EvalState {
+  lookup: LookupFn;
+}
+
+function refLabel(node: RefNode): string {
+  return `${node.root}.${node.path.join('.')}`;
+}
+
+function evalNode(node: Node, state: EvalState): unknown {
+  switch (node.kind) {
+    case 'str':
+      return node.value;
+    case 'bare':
+      throw new ComputedEvalError(
+        `Unexpected identifier '${node.name}' — expected a function call, a quoted string, or a variable reference like self.x / secret.y`,
+      );
+    case 'ref': {
+      const value = state.lookup(node.root, node.path);
+      if (value === undefined) {
+        throw new ComputedEvalError(`Reference '${refLabel(node)}' could not be resolved`);
+      }
+      return value;
+    }
+    case 'call':
+      return evalCall(node.fn, node.args, state);
+  }
+}
+
+function asObject(value: unknown, fn: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ComputedEvalError(`${fn}() expects an object/map argument`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asArray(value: unknown, fn: string): unknown[] {
+  if (!Array.isArray(value)) {
+    throw new ComputedEvalError(`${fn}() expects an array argument`);
+  }
+  return value;
+}
+
+/** A `secret`/`system_secret`-rooted ref argument, or null if not one. */
+function secretRefArg(arg: Arg): RefNode | null {
+  if (
+    arg.value.kind === 'ref' &&
+    (arg.value.root === 'secret' || arg.value.root === 'system_secret')
+  ) {
+    return arg.value;
+  }
+  return null;
+}
+
+function evalCall(fn: string, args: Arg[], state: EvalState): unknown {
+  if (!ALLOWED_FUNCTIONS.has(fn)) {
+    throw new ComputedEvalError(
+      `Unknown function '${fn}'. Allowed: keys, values, map, concat, unique, format`,
+    );
+  }
+
+  switch (fn) {
+    case 'keys': {
+      requireArity(fn, args, 1);
+      requirePositional(fn, args);
+      const obj = asObject(evalNode(args[0].value, state), fn);
+      return Object.keys(obj);
+    }
+
+    case 'values': {
+      requireArity(fn, args, 1);
+      requirePositional(fn, args);
+      // Secret-projection rule: surfacing the VALUES of a secret map would
+      // leak secrets. Reject statically (before evaluation).
+      const secretRef = secretRefArg(args[0]);
+      if (secretRef) {
+        throw new ComputedEvalError(
+          `values(${refLabel(secretRef)}) is not allowed — exposing the values of a secret would leak it. Use keys() to surface its key names.`,
+        );
+      }
+      const obj = asObject(evalNode(args[0].value, state), fn);
+      return Object.values(obj);
+    }
+
+    case 'unique': {
+      requireArity(fn, args, 1);
+      requirePositional(fn, args);
+      const arr = asArray(evalNode(args[0].value, state), fn);
+      return dedupe(arr);
+    }
+
+    case 'concat': {
+      requirePositional(fn, args);
+      if (args.length === 0) {
+        throw new ComputedEvalError('concat() requires at least one argument');
+      }
+      const out: unknown[] = [];
+      for (const arg of args) {
+        const v = evalNode(arg.value, state);
+        if (Array.isArray(v)) out.push(...v);
+        else out.push(v);
+      }
+      return out;
+    }
+
+    case 'map': {
+      // map(list, field) — field is a bare identifier naming the property.
+      requireArity(fn, args, 2);
+      requirePositional(fn, args);
+      const arr = asArray(evalNode(args[0].value, state), fn);
+      const fieldNode = args[1].value;
+      if (fieldNode.kind !== 'bare') {
+        throw new ComputedEvalError(
+          `map()'s second argument must be a bare field name (e.g. map(self.upstreams, ip))`,
+        );
+      }
+      const field = fieldNode.name;
+      return arr.map((item, idx) => {
+        if (item === null || typeof item !== 'object') {
+          throw new ComputedEvalError(
+            `map() element at index ${idx} is not an object; cannot project field '${field}'`,
+          );
+        }
+        return (item as Record<string, unknown>)[field];
+      });
+    }
+
+    case 'format': {
+      // format('{a}.{b}', a=..., b=...)
+      if (args.length < 1) {
+        throw new ComputedEvalError('format() requires a template string as its first argument');
+      }
+      if (args[0].name !== undefined) {
+        throw new ComputedEvalError("format()'s first argument (the template) must be positional");
+      }
+      const tmplVal = evalNode(args[0].value, state);
+      if (typeof tmplVal !== 'string') {
+        throw new ComputedEvalError("format()'s first argument must be a string template");
+      }
+      const parts: Record<string, string> = {};
+      for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.name) {
+          throw new ComputedEvalError(
+            'format() arguments after the template must be named (e.g. host=self.hostname)',
+          );
+        }
+        parts[arg.name] = stringifyScalar(
+          evalNode(arg.value, state),
+          `format() part '${arg.name}'`,
+        );
+      }
+      return tmplVal.replace(/\{([a-zA-Z0-9_]+)\}/g, (_m, key: string) => {
+        if (!(key in parts)) {
+          throw new ComputedEvalError(
+            `format() template references '{${key}}' but no such named argument was supplied`,
+          );
+        }
+        return parts[key];
+      });
+    }
+
+    default:
+      // Unreachable — guarded by ALLOWED_FUNCTIONS above.
+      throw new ComputedEvalError(`Unhandled function '${fn}'`);
+  }
+}
+
+function requireArity(fn: string, args: Arg[], n: number): void {
+  if (args.length !== n) {
+    throw new ComputedEvalError(`${fn}() expects ${n} argument(s), got ${args.length}`);
+  }
+}
+
+function requirePositional(fn: string, args: Arg[]): void {
+  for (const arg of args) {
+    if (arg.name !== undefined) {
+      throw new ComputedEvalError(`${fn}() does not take named arguments`);
+    }
+  }
+}
+
+function dedupe(arr: unknown[]): unknown[] {
+  const seen = new Set<string>();
+  const out: unknown[] = [];
+  for (const item of arr) {
+    // Key scalars by value; objects/arrays by JSON form. Good enough for
+    // the homogeneous primitive lists computed variables produce.
+    const key = typeof item === 'object' ? JSON.stringify(item) : `${typeof item}:${String(item)}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+function stringifyScalar(value: unknown, what: string): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  throw new ComputedEvalError(`${what} must be a string, number, or boolean`);
+}
+
+/**
+ * Parse + evaluate a computed-variable expression against a lookup.
+ * Throws ComputedParseError / ComputedEvalError on failure.
+ */
+export function evaluateComputed(expression: string, lookup: LookupFn): unknown {
+  const ast = parseComputed(expression);
+  return evalNode(ast, { lookup });
+}
+
+/**
+ * Recursively replace every computed marker in `value` with its evaluated
+ * result, using `lookup` (built over the PROVIDER's context). Non-marker
+ * values pass through unchanged; arrays and plain objects are walked. Pure —
+ * returns a new value, never mutates the input. Throws on the first marker
+ * that fails to evaluate (callers in eager paths catch + degrade).
+ */
+export function resolveComputedFields(value: unknown, lookup: LookupFn): unknown {
+  const expr = asComputedExpression(value);
+  if (expr !== null) {
+    return evaluateComputed(expr, lookup);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolveComputedFields(v, lookup));
+  }
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = resolveComputedFields(v, lookup);
+    }
+    return out;
+  }
+  return value;
+}

package/src/variables/computed/marker.ts

@@ -0,0 +1,53 @@
+/**
+ * Marker for a computed capability field embedded in stored capability data.
+ *
+ * At registration time, each `computed:` entry is folded into the capability's
+ * `data` JSON as `{ [name]: { [MARKER_KEY]: "<dsl expression>" } }`. At read
+ * time the resolver detects the marker and evaluates the expression in the
+ * PROVIDER's context (see resolver.ts capability case). This mirrors how
+ * static `$self:` refs already live verbatim in stored data and resolve lazily.
+ */
+
+/** Property key that flags a value as a computed-field marker. */
+export const COMPUTED_MARKER_KEY = '__celilo_computed__';
+
+export interface ComputedMarker {
+  [COMPUTED_MARKER_KEY]: string;
+}
+
+/** Build a marker object for storage. */
+export function computedMarker(expression: string): ComputedMarker {
+  return { [COMPUTED_MARKER_KEY]: expression };
+}
+
+/** Narrow an arbitrary value to a computed marker, returning its expression. */
+export function asComputedExpression(value: unknown): string | null {
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    COMPUTED_MARKER_KEY in (value as Record<string, unknown>)
+  ) {
+    const expr = (value as Record<string, unknown>)[COMPUTED_MARKER_KEY];
+    return typeof expr === 'string' ? expr : null;
+  }
+  return null;
+}
+
+/**
+ * Cheap recursive scan: does this value (or anything nested) contain a
+ * computed marker? Used to skip the (relatively expensive) provider-lookup
+ * build when a capability has no computed fields — the common case.
+ */
+export function containsComputedMarker(value: unknown): boolean {
+  if (asComputedExpression(value) !== null) return true;
+  if (Array.isArray(value)) {
+    return value.some(containsComputedMarker);
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const v of Object.values(value as Record<string, unknown>)) {
+      if (containsComputedMarker(v)) return true;
+    }
+  }
+  return false;
+}