@cloudcrane/app-spec 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chirag Phor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @cloudcrane/app-spec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The CloudCrane app spec: its schema, the checks a spec must pass, and the
+rule language its logic is written in.
+
+```js
+import { validateSpec, deriveBlueprint } from "@cloudcrane/app-spec";
+
+const { spec, problems } = validateSpec(JSON.parse(text));
+if (!spec) for (const p of problems) console.log(`${p.at}: ${p.problem}`);
+```
+
+- `validateSpec(input)`: the schema, the A2UI surface against its catalog, every
+  rule parses and reproduces its examples, and the leak scan (paths, code,
+  secrets, personal details). Each problem names its JSON Pointer.
+- `deriveBlueprint(spec)`: the blueprint CloudCrane shows for an app (its purpose, screens, data,
+  journeys and promises), from the spec.
+- `Rules` (`@cloudcrane/app-spec/logic`): evaluates a spec's CEL rules, with
+  date functions and a bounded `fold`.
+- `@cloudcrane/app-spec/schema.json`: the spec as JSON Schema (2020-12).
+
+`zod` 3.25 is a peer dependency. Includes A2UI v0.9.1's schemas, unchanged,
+under the Apache License 2.0 (`vendor/a2ui`). MIT licensed.

package/dist/src/a2ui.d.ts

@@ -0,0 +1,12 @@
+export type Problem = {
+    at: string;
+    problem: string;
+};
+export type Catalog = {
+    catalogId: string;
+    [k: string]: unknown;
+};
+export declare const A2UI_VERSION = "v0.9.1";
+export declare const BASIC_CATALOG: Catalog;
+/** Problems with a spec's A2UI messages; none means a renderer can draw them. */
+export declare function surfaceProblems(messages: unknown[], catalog?: Catalog): Problem[];

package/dist/src/a2ui.js

@@ -0,0 +1,89 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import basicCatalog from "../vendor/a2ui/v0_9_1/catalogs/basic/catalog.json" with { type: "json" };
+import commonTypes from "../vendor/a2ui/v0_9_1/common_types.json" with { type: "json" };
+import serverToClient from "../vendor/a2ui/v0_9_1/server_to_client.json" with { type: "json" };
+export const A2UI_VERSION = "v0.9.1";
+export const BASIC_CATALOG = basicCatalog;
+const CATALOG_SLOT = "https://a2ui.org/specification/v0_9/catalog.json";
+const validators = new Map();
+/** A2UI's message validator with `catalog` as the surface's catalog (built once per catalog). */
+function messageValidator(catalog) {
+    const known = validators.get(catalog.catalogId);
+    if (known)
+        return known;
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    ajv.addSchema(commonTypes);
+    ajv.addSchema({ ...catalog, $id: CATALOG_SLOT });
+    const validate = ajv.compile(serverToClient);
+    validators.set(catalog.catalogId, validate);
+    return validate;
+}
+/** The ids a component names as its children: a list of ids, one child, or a template over a path. */
+function childIdsOf(c) {
+    const out = [];
+    const add = (v) => {
+        if (typeof v === "string")
+            out.push(v);
+        else if (Array.isArray(v))
+            v.forEach(add);
+        else if (v && typeof v === "object" && "componentId" in v && typeof v.componentId === "string")
+            out.push(v.componentId);
+    };
+    add(c.children);
+    add(c.child);
+    for (const key of ["trigger", "content", "header", "body"])
+        add(c[key]);
+    if (Array.isArray(c["tabs"]))
+        for (const t of c["tabs"])
+            add(t?.child);
+    return out;
+}
+/** Problems with a spec's A2UI messages; none means a renderer can draw them. */
+export function surfaceProblems(messages, catalog = BASIC_CATALOG) {
+    const problems = [];
+    const validate = messageValidator(catalog);
+    messages.forEach((m, i) => {
+        if (!validate(m)) {
+            for (const e of (validate.errors ?? []).slice(0, 5))
+                problems.push({ at: `surface.messages[${i}]${e.instancePath}`, problem: e.message ?? "invalid" });
+        }
+    });
+    if (problems.length)
+        return problems;
+    const first = messages[0];
+    if (!first?.createSurface)
+        return [{ at: "surface.messages[0]", problem: "must be createSurface" }];
+    const { surfaceId, catalogId } = first.createSurface;
+    if (catalogId !== catalog.catalogId)
+        problems.push({ at: "surface.messages[0].createSurface.catalogId", problem: `must be ${catalog.catalogId}` });
+    const components = new Map();
+    messages.forEach((m, i) => {
+        const body = Object.values(m)[1];
+        const kind = Object.keys(m).find((k) => k !== "version");
+        if (i > 0 && kind === "createSurface")
+            problems.push({ at: `surface.messages[${i}]`, problem: "only one createSurface: a spec is one surface" });
+        if (kind === "deleteSurface")
+            problems.push({ at: `surface.messages[${i}]`, problem: "a spec never deletes its surface" });
+        const sid = m[kind ?? ""]?.surfaceId ?? body?.surfaceId;
+        if (sid !== surfaceId)
+            problems.push({ at: `surface.messages[${i}]`, problem: `surfaceId must be ${surfaceId}` });
+        if (kind === "updateComponents") {
+            for (const c of m.updateComponents.components) {
+                const id = String(c.id);
+                if (components.has(id))
+                    problems.push({ at: `component ${id}`, problem: "duplicate id" });
+                components.set(id, c);
+            }
+        }
+    });
+    if (!components.has("root"))
+        problems.push({ at: "surface", problem: 'no component has the id "root"' });
+    for (const [id, c] of components) {
+        for (const child of childIdsOf(c))
+            if (!components.has(child))
+                problems.push({ at: `component ${id}`, problem: `child "${child}" doesn't exist` });
+    }
+    return problems;
+}

package/dist/src/blueprint.d.ts

@@ -0,0 +1,27 @@
+import type { Spec } from "./schema.js";
+export type BlueprintV1 = {
+    v: 1;
+    purpose: string;
+    screens: {
+        id: string;
+        says: string;
+    }[];
+    data: {
+        version: number;
+        keeps: {
+            key: string;
+            what: string;
+        }[];
+    };
+    journeys: Spec["journeys"];
+    promises: Spec["promises"];
+    network: Spec["network"];
+    icon?: string;
+    category?: string;
+    tags?: string[];
+    design: {
+        palette: string[];
+        notes: string;
+    };
+};
+export declare function deriveBlueprint(spec: Spec): BlueprintV1;

package/dist/src/blueprint.js

@@ -0,0 +1,62 @@
+const literal = (v) => (typeof v === "string" ? v.replace(/\$\{[^}]*\}/g, "…").trim() : null);
+const list = (xs, max = 6) => {
+    const u = [...new Set(xs.filter(Boolean))];
+    return u.length > max ? `${u.slice(0, max).join(", ")} and more` : u.join(", ");
+};
+/** The plain words a person sees on the screen: titles, labels and buttons. */
+function screenWords(spec) {
+    const components = spec.surface.messages.flatMap((m) => m.updateComponents?.components ?? []);
+    const byId = new Map(components.map((c) => [c.id, c]));
+    const texts = components.filter((c) => c.component === "Text").map((c) => literal(c.text));
+    const inputs = components
+        .filter((c) => ["TextField", "CheckBox", "ChoicePicker", "Slider", "DateTimeInput"].includes(c.component))
+        .map((c) => literal(c.label));
+    // A one-character label (×, +) is a glyph, not a word a person reads.
+    const buttons = components.filter((c) => c.component === "Button").map((c) => literal(byId.get(c.child ?? "")?.text));
+    const words = (xs) => xs.filter((t) => !!t && t.length > 1);
+    const widgets = components.filter((c) => !["Text", "Column", "Row", "List", "Card", "Button", "Divider"].includes(c.component)).map((c) => c.component);
+    const parts = [
+        words(texts).length && `Shows ${list(words(texts).filter((t) => !buttons.includes(t)))}`,
+        words(inputs).length && `asks for ${list(words(inputs))}`,
+        words(buttons).length && `with ${list(words(buttons))}`,
+        widgets.length && `using ${list(widgets)}`,
+    ].filter(Boolean);
+    return `${parts.join("; ")}.`;
+}
+/** Every colour in the tokens, as written. */
+function palette(tokens) {
+    const out = [];
+    const walk = (n) => {
+        if (!n || typeof n !== "object")
+            return;
+        const v = n.$value;
+        if (typeof v === "string" && /^#[0-9a-fA-F]{3,8}$/.test(v))
+            out.push(v.toLowerCase());
+        else if (v && typeof v === "object" && typeof v.hex === "string")
+            out.push(v.hex.toLowerCase());
+        for (const [k, c] of Object.entries(n))
+            if (!k.startsWith("$"))
+                walk(c);
+    };
+    walk(tokens);
+    return [...new Set(out)].slice(0, 12);
+}
+export function deriveBlueprint(spec) {
+    const saved = spec.data.initial && typeof spec.data.initial === "object" ? Object.keys(spec.data.initial) : [];
+    return {
+        v: 1,
+        purpose: spec.module.purpose,
+        screens: [{ id: spec.module.id, says: screenWords(spec) }],
+        data: {
+            version: spec.data.version,
+            keeps: [{ key: spec.data.key, what: saved.length ? `On this phone: ${list(saved)}` : "What you enter, on this phone" }],
+        },
+        journeys: spec.journeys,
+        promises: spec.promises,
+        network: spec.network,
+        ...(spec.module.icon ? { icon: spec.module.icon } : {}),
+        ...(spec.module.category ? { category: spec.module.category } : {}),
+        ...(spec.module.tags?.length ? { tags: spec.module.tags } : {}),
+        design: { palette: palette(spec.tokens), notes: `Built from a CloudCrane spec, runtime ${spec.manifest.runtime}.` },
+    };
+}

package/dist/src/canonical.d.ts

@@ -0,0 +1,2 @@
+/** A value as RFC 8785 (JCS) canonical JSON: the same bytes for the same value, everywhere. */
+export declare function canonical(value: unknown): string;

package/dist/src/canonical.js

@@ -0,0 +1,8 @@
+import canonicalizeJson from "canonicalize";
+/** A value as RFC 8785 (JCS) canonical JSON: the same bytes for the same value, everywhere. */
+export function canonical(value) {
+    const out = canonicalizeJson(value);
+    if (out === undefined)
+        throw new TypeError("Not representable as JSON");
+    return out;
+}

package/dist/src/catalog.d.ts

@@ -0,0 +1,7 @@
+import { type Catalog } from "./a2ui.js";
+export declare const CLOUDCRANE_CATALOG_ID = "https://cloudcrane.ai/catalogs/app/v1.json";
+/** The CloudCrane catalog document, built from A2UI's basic catalog. */
+export declare function cloudcraneCatalog(): Catalog;
+export declare const CLOUDCRANE_CATALOG: Catalog;
+/** The catalog a surface names, if it's one we know. */
+export declare function catalogFor(id: string): Catalog | undefined;

package/dist/src/catalog.js

@@ -0,0 +1,83 @@
+import { BASIC_CATALOG } from "./a2ui.js";
+// The CloudCrane catalog: A2UI's basic catalog plus what an app on a phone
+// needs that an agent's chat surface doesn't, written as an A2UI catalog
+// document (the format A2UI's own catalogs use), so A2UI's tools and
+// renderers read it as they read theirs.
+//
+// Functions (renderer-only local actions; they change the surface's data model):
+//   set(path, value), push(path, value), removeAt(path) (the item the action
+//   was fired from, by its index in a list template), batch(steps).
+// Components:
+//   DateStrip: the last N days as chips, today on the right, one selectable,
+//   each with a status dot.
+export const CLOUDCRANE_CATALOG_ID = "https://cloudcrane.ai/catalogs/app/v1.json";
+const COMMON = "https://a2ui.org/specification/v0_9/common_types.json#/$defs";
+const path = { $ref: `${COMMON}/DynamicString`, description: "A JSON Pointer into the data model, like /saved/days/2026-10-27." };
+const value = { $ref: `${COMMON}/DynamicValue`, description: "The value: a literal, or bound to the data model." };
+const fn = (name, description, properties, required) => ({
+    type: "object",
+    description,
+    properties: {
+        call: { const: name },
+        args: { type: "object", properties, required, additionalProperties: false },
+        returnType: { const: "void" },
+    },
+    required: ["call", "args"],
+    unevaluatedProperties: false,
+});
+// A step names its place `target`, not `path`: in A2UI any object with a `path` key is a data binding.
+const STEP = {
+    type: "object",
+    properties: { op: { enum: ["set", "push", "removeAt"] }, target: path, value },
+    required: ["op", "target"],
+    additionalProperties: false,
+};
+const FUNCTIONS = {
+    set: fn("set", "Sets the value at a path in the data model.", { path, value }, ["path", "value"]),
+    push: fn("push", "Adds a value to the end of the list at a path, creating the list if there isn't one.", { path, value }, ["path", "value"]),
+    removeAt: fn("removeAt", "Removes, from the list at a path, the item this action was fired from (by its index in a list template).", { path }, ["path"]),
+    batch: fn("batch", "Runs set, push and removeAt steps in order, as one change.", { steps: { type: "array", items: STEP, minItems: 1, maxItems: 10 } }, [
+        "steps",
+    ]),
+};
+const COMPONENTS = {
+    DateStrip: {
+        type: "object",
+        allOf: [
+            { $ref: `${COMMON}/ComponentCommon` },
+            { $ref: "#/$defs/CatalogComponentCommon" },
+            {
+                type: "object",
+                properties: {
+                    component: { const: "DateStrip" },
+                    days: { type: "integer", minimum: 2, maximum: 60, description: "How many days, ending today." },
+                    today: { $ref: `${COMMON}/DynamicString`, description: "Today, as YYYY-MM-DD." },
+                    value: { $ref: `${COMMON}/DynamicString`, description: "The selected day, as YYYY-MM-DD (two-way)." },
+                    statuses: { $ref: `${COMMON}/DynamicValue`, description: "A map of day (YYYY-MM-DD) to complete, active, partial or incomplete, for its dot." },
+                },
+                required: ["component", "today", "value"],
+            },
+        ],
+        unevaluatedProperties: false,
+    },
+};
+/** The CloudCrane catalog document, built from A2UI's basic catalog. */
+export function cloudcraneCatalog() {
+    const basic = structuredClone(BASIC_CATALOG);
+    basic.components = { ...basic.components, ...COMPONENTS };
+    basic.functions = { ...basic.functions, ...FUNCTIONS };
+    basic.$defs.anyComponent.oneOf.push(...Object.keys(COMPONENTS).map((k) => ({ $ref: `#/components/${k}` })));
+    basic.$defs.anyFunction.oneOf.push(...Object.keys(FUNCTIONS).map((k) => ({ $ref: `#/functions/${k}` })));
+    return {
+        ...basic,
+        $id: CLOUDCRANE_CATALOG_ID,
+        catalogId: CLOUDCRANE_CATALOG_ID,
+        title: "CloudCrane app catalog",
+        description: "A2UI's basic catalog, plus local actions (set, push, removeAt, batch) and DateStrip, for apps that run on a phone.",
+    };
+}
+export const CLOUDCRANE_CATALOG = cloudcraneCatalog();
+/** The catalog a surface names, if it's one we know. */
+export function catalogFor(id) {
+    return id === CLOUDCRANE_CATALOG_ID ? CLOUDCRANE_CATALOG : id === BASIC_CATALOG.catalogId ? BASIC_CATALOG : undefined;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems, type Catalog, type Problem } from "./a2ui.js";
+export { Id, Pointer, PointerPattern, SpecSchema, Tokens, type Spec, type TokenNode } from "./schema.js";
+export { validateSpec } from "./validate.js";
+export { canonical } from "./canonical.js";
+export { specJsonSchema } from "./jsonschema.js";
+export { dates, logicProblems, Rules, fromCel, toCel, MAX_RANGE } from "./logic.js";
+export { leakProblems } from "./leak.js";
+export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
+export { deriveBlueprint, type BlueprintV1 } from "./blueprint.js";

package/dist/src/index.js

@@ -0,0 +1,11 @@
+// The CloudCrane app spec: its schema, the A2UI surface check, canonical JSON
+// and the JSON Schema export. See the repo README.
+export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems } from "./a2ui.js";
+export { Id, Pointer, PointerPattern, SpecSchema, Tokens } from "./schema.js";
+export { validateSpec } from "./validate.js";
+export { canonical } from "./canonical.js";
+export { specJsonSchema } from "./jsonschema.js";
+export { dates, logicProblems, Rules, fromCel, toCel, MAX_RANGE } from "./logic.js";
+export { leakProblems } from "./leak.js";
+export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalog } from "./catalog.js";
+export { deriveBlueprint } from "./blueprint.js";

package/dist/src/jsonschema.d.ts

@@ -0,0 +1,2 @@
+/** The spec's JSON Schema, for tools outside TypeScript (schema/app-spec.v1.json is this, checked in). */
+export declare function specJsonSchema(): Record<string, unknown>;

package/dist/src/jsonschema.js

@@ -0,0 +1,11 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { SpecSchema } from "./schema.js";
+/** The spec's JSON Schema, for tools outside TypeScript (schema/app-spec.v1.json is this, checked in). */
+export function specJsonSchema() {
+    return {
+        $id: "https://cloudcrane.ai/schemas/app-spec.v1.json",
+        title: "CloudCrane app spec v1",
+        description: "An A2UI surface in an envelope: DTCG tokens, saved data, CEL logic, journeys, promises, tests and mod points. No code.",
+        ...zodToJsonSchema(SpecSchema, { target: "jsonSchema2019-09", $refStrategy: "none" }),
+    };
+}

package/dist/src/leak.d.ts

@@ -0,0 +1,3 @@
+import type { Problem } from "./a2ui.js";
+/** What in a spec looks like code, a path, a secret, a personal detail or an internal host. */
+export declare function leakProblems(spec: unknown): Problem[];

package/dist/src/leak.js

@@ -0,0 +1,141 @@
+const re = (r) => (s) => r.test(s);
+const SOURCE = "dart|ts|tsx|js|jsx|mjs|cjs|py|kt|kts|swift|java|go|rb|php|cs|m|mm|c|cc|cpp|h|vue|svelte";
+/** Shannon entropy per character. */
+function entropy(s) {
+    const counts = new Map();
+    for (const c of s)
+        counts.set(c, (counts.get(c) ?? 0) + 1);
+    let h = 0;
+    for (const n of counts.values())
+        h -= (n / s.length) * Math.log2(n / s.length);
+    return h;
+}
+/** A long run of key-like characters that looks random: a token, not a word. */
+function highEntropy(s) {
+    for (const m of s.matchAll(/[A-Za-z0-9+/_=-]{32,}/g)) {
+        const run = m[0];
+        const hex = /^[0-9a-fA-F]+$/.test(run);
+        if (entropy(run) > (hex ? 3.5 : 4.3))
+            return true;
+    }
+    return false;
+}
+/** 10 to 15 digits with phone punctuation, that isn't a date or a time. */
+function phoneNumber(s) {
+    for (const m of s.matchAll(/(?<![\w-])\+?\d[\d\s().-]{8,}\d(?![\w-])/g)) {
+        const run = m[0].trim();
+        if (/^\d{4}-\d{2}-\d{2}/.test(run) || /^\d{1,2}:\d{2}/.test(run))
+            continue;
+        const digits = run.replace(/\D/g, "").length;
+        if (digits >= 10 && digits <= 15)
+            return true;
+    }
+    return false;
+}
+const RULES = [
+    { kind: "path", why: "a source file path", test: re(new RegExp(`(^|[\\s"'(\`])(?:[\\w.-]+/)+[\\w.-]+\\.(?:${SOURCE})\\b`)) },
+    { kind: "path", why: "a file:line reference", test: re(new RegExp(`\\b[\\w./-]+\\.(?:${SOURCE}):\\d+`)) },
+    { kind: "path", why: "an absolute path on someone's machine", test: re(/(^|\s)(\/Users\/|\/home\/|[A-Z]:\\)/) },
+    { kind: "path", why: "a package folder", test: re(/node_modules\/|\.dart_tool\/|\/pubspec\.yaml/) },
+    { kind: "secret", why: "an AWS access key", test: re(/\bAKIA[0-9A-Z]{16}\b/) },
+    {
+        kind: "secret",
+        why: "an API key",
+        test: re(/\b(sk|pk|rk)[-_](live|test|proj)?[-_]?[A-Za-z0-9]{20,}\b|\bAIza[0-9A-Za-z_-]{35}\b|\bgh[pousr]_[A-Za-z0-9]{36}\b|\bxox[abpr]-[A-Za-z0-9-]{10,}/),
+    },
+    { kind: "secret", why: "a JSON Web Token", test: re(/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\./) },
+    { kind: "secret", why: "a private key", test: re(/-----BEGIN [A-Z ]*PRIVATE KEY-----/) },
+    { kind: "secret", why: "a long random-looking string", test: highEntropy },
+    { kind: "personal", why: "an email address", test: re(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/) },
+    { kind: "personal", why: "a phone number", test: phoneNumber },
+    {
+        kind: "host",
+        why: "an internal address",
+        test: re(/\b(localhost|127\.0\.0\.1|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|[\w-]+\.(internal|local|corp|lan))\b/),
+    },
+    { kind: "code", why: "an arrow function", test: re(/=>/) },
+    { kind: "code", why: "a function definition", test: re(/\bfunction\s*\w*\s*\(|\bdef\s+\w+\s*\(|\bfun\s+\w+\s*\(/) },
+    { kind: "code", why: "an import", test: re(/^\s*(import|export)\s+[\w{*'"]|\brequire\(\s*['"]/m) },
+    { kind: "code", why: "a class definition", test: re(/\bclass\s+\w+\s+(extends|implements|with)\b/) },
+    { kind: "code", why: "a widget builder", test: re(/\bWidget\s+build\s*\(|\bsetState\s*\(|\buseState\s*\(/) },
+    { kind: "code", why: "a variable declaration", test: re(/\b(const|let|var|final)\s+[A-Za-z_]\w*\s*(:\s*\w+\s*)?=/) },
+    { kind: "code", why: "statement punctuation", test: (s) => (s.match(/[;{}]/g)?.length ?? 0) >= 4 },
+    { kind: "code", why: "a method call", test: re(/\b[A-Za-z_$][\w$]*(\?)?\.[A-Za-z_$][\w$]*(<[^>]*>)?\(/) },
+    { kind: "code", why: "a constructor call", test: re(/(?<![\w$])_?[A-Z][A-Za-z0-9_]*(<[^>]*>)?\(/) },
+    { kind: "code", why: "a property line", test: re(/^\s*[a-z_$][\w$]*\s*:\s*\S.*[,({[]\s*$/) },
+    { kind: "code", why: "control flow", test: re(/\b(if|for|while|switch|catch)\s*\(|\bawait\s+[\w$.]|\breturn\s+[\w$(!'"[{]|\}\s*else\b/) },
+    { kind: "code", why: "a code operator", test: re(/===?|!==?|&&|\|\||\?\?|\?\.|\+\+|--(?=[\w$])|\b\w+\s*[+\-*/]?=\s*[\w$'"(\[]/) },
+    {
+        kind: "code",
+        why: "a typed declaration",
+        test: re(/\b(final|late|required|static|private|public|protected|readonly)\s+[A-Za-z_$][\w$<>?,\s]*\s+[A-Za-z_$][\w$]*\s*[;=,)]/),
+    },
+    { kind: "code", why: "a statement end", test: re(/[)\]}]\s*;\s*$|^\s*[\w$.]+\s*\([^)]*\)\s*;?\s*$/) },
+    { kind: "code", why: "a generic type", test: re(/\b[A-Za-z_$][\w$]*<[A-Z][\w$<>?,\s]*>/) },
+    { kind: "code", why: "a block opener", test: re(/\)\s*(async\s*)?\{\s*$|\(\{\s*$|\)\s+[a-z_$][\w$]*\s*\(/) },
+    { kind: "code", why: "a member of this", test: re(/\bthis\.[A-Za-z_$]/) },
+    { kind: "code", why: "a trailing code comment", test: re(/[;,){\]]\s*\/\/\s/) },
+    { kind: "code", why: "a quoted key", test: re(/^\s*(['"])[\w-]+\1\s*:\s*\S/) },
+    { kind: "code", why: "a string literal in code", test: re(/^\s*(['"]).*\1\s*[,)]\s*(\1|$)|^\s*(['"])[^'"]*\4\s*,\s*(['"])|\\n/) },
+    { kind: "code", why: "a typed function", test: re(/\b(bool|int|double|String|void|dynamic|num|var|Future|Stream)\??\s+_?[A-Za-z$][\w$]*\s*\(/) },
+    { kind: "code", why: "a conditional expression", test: re(/(^|[\s(])\?\s*[\w$.'"!]+.*\s:\s*[\w$.'"]/) },
+    { kind: "code", why: "a member access", test: re(/\b[A-Z][A-Za-z0-9]*\.[a-z_][\w$]*\b|\b[a-z_$][\w$]*\.[a-z_$][\w$]*[A-Z][\w$]*\b/) },
+    { kind: "code", why: "string interpolation", test: re(/\$\{|\$[a-z_][\w]*/) },
+    { kind: "code", why: "a cast or an index", test: re(/\bas\s+[A-Z][\w$]*\??|\[(['"])[\w-]+\1\]|\w!\.|\w!\(|\}\s*from\s*['"]|\/\*\*|\*\//) },
+    {
+        kind: "code",
+        why: "a type annotation",
+        test: re(/^\s*[A-Za-z_$][\w$]*\??\s*:\s*[^\s].*[;,]\s*$|\|\s*(null|undefined|string|number|boolean)\b|\bPromise<|\basync\s+[\w$]+\s*\(/),
+    },
+    { kind: "code", why: "a call", test: re(/^\s*\.[a-z_$][\w$]*\(|\b[a-z_$][\w$]*\((['"`]|[\w$]{2,}[,)]|\)|\{)/) },
+    { kind: "code", why: "a constant name", test: re(/\b[A-Z][A-Z0-9]*_[A-Z0-9_]+\b/) },
+];
+/** Strings the scan skips, by pointer: the source hash is a hash by design. */
+const EXEMPT = new Set(["/manifest/source/fingerprint"]);
+/** Where CEL lives: rules may look like code there, but nothing else may. */
+const CEL_AT = [/^\/logic\/functions\/[^/]+\/cel$/, /^\/logic\/computed\/.+$/, /^\/data\/migrations\/\d+\/cel$/];
+/** A test step's state path: a dotted path into what the app exposes (CloudCrane's form), which reads like a member access by design. */
+const STATE_PATH_AT = /^\/tests\/\d+\/(steps|setup|check)\/\d+\/path$/;
+const STATE_PATH = /^[A-Za-z0-9_$]+(\.[A-Za-z0-9_$]+)*$/;
+const escape = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+/** Every string in a value, with its JSON Pointer (object keys count as strings too). */
+function* strings(v, at = "") {
+    if (typeof v === "string")
+        yield [at, v];
+    else if (Array.isArray(v))
+        for (let i = 0; i < v.length; i++)
+            yield* strings(v[i], `${at}/${i}`);
+    else if (v && typeof v === "object")
+        for (const [k, x] of Object.entries(v)) {
+            yield [`${at}/${escape(k)}#key`, k];
+            yield* strings(x, `${at}/${escape(k)}`);
+        }
+}
+/** What in a spec looks like code, a path, a secret, a personal detail or an internal host. */
+export function leakProblems(spec) {
+    const problems = [];
+    for (const [at, raw] of strings(spec)) {
+        if (EXEMPT.has(at))
+            continue;
+        // DTCG's own keys ($type, $value, …) are the format's, not the partner's.
+        if (at.endsWith("#key") && /^\$[a-z]+$/.test(raw))
+            continue;
+        // Rule names, parameters and pointers under /logic are CEL identifiers the schema already restricts.
+        if (at.endsWith("#key") && at.startsWith("/logic/"))
+            continue;
+        // A2UI's bindings inside text (${/path}, ${fn(…)}) are the standard's syntax.
+        const s = at.startsWith("/surface/") || at.startsWith("/data/views/") ? raw.replace(/\$\{[^}]*\}/g, " ") : raw;
+        const codeShaped = CEL_AT.some((r) => r.test(at)) || (STATE_PATH_AT.test(at) && STATE_PATH.test(raw));
+        // Web addresses are checked as addresses (hosts, secrets), never as code.
+        const withoutUrls = s.replace(/https?:\/\/[^\s"'<>]+/g, " ");
+        for (const rule of RULES) {
+            if (codeShaped && rule.kind === "code")
+                continue;
+            if (rule.test(rule.kind === "code" ? withoutUrls : s)) {
+                problems.push({ at: at || "/", problem: `looks like ${rule.why} (${rule.kind})` });
+                break;
+            }
+        }
+    }
+    return problems;
+}

package/dist/src/logic.d.ts

@@ -0,0 +1,36 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+type Logic = Spec["logic"];
+type CelValue = unknown;
+export declare const MAX_RANGE = 3660;
+/** JSON in: whole numbers become CEL ints (BigInt). */
+export declare function toCel(v: unknown): CelValue;
+/** CEL out: ints become numbers again, so results are plain JSON. */
+export declare function fromCel(v: CelValue): unknown;
+export declare const dates: {
+    addDays: (s: string, n: bigint) => string;
+    daysBetween: (a: string, b: string) => bigint;
+    /** The Monday that starts s's week. */
+    weekStart: (s: string) => string;
+    dateRange: (a: string, b: string) => string[];
+};
+/** A cycle among the spec's functions, as names, or null. */
+export declare function cycleIn(functions: Logic["functions"]): string[] | null;
+/** The rules of one spec, ready to evaluate. */
+export declare class Rules {
+    private readonly logic;
+    private readonly env;
+    private readonly consts;
+    private depth;
+    constructor(logic: Logic);
+    private call;
+    /** An expression's value, as JSON; null when it can't be worked out. */
+    evaluate(cel: string, vars?: Record<string, unknown>): unknown;
+    /** A spec function applied to JSON arguments; null when it can't be worked out. */
+    apply(name: string, args: unknown[]): unknown;
+    /** Why an expression won't parse, or null when it does. */
+    parseError(cel: string): string | null;
+}
+/** Problems with a spec's rules, each at its JSON Pointer: expressions that don't parse, a call cycle, vectors the rules don't reproduce. */
+export declare function logicProblems(spec: Pick<Spec, "logic" | "data">): Problem[];
+export {};