dataiku-sdk 0.12.4 → 0.12.6

package/dist/src/skill.js

@@ -10,22 +10,30 @@ If the installed \`dss\` binary is unavailable but the repository checkout is th
 
 ## Contract
 
-- Success writes exactly one JSON result to stdout.
-- Failure writes exactly one JSONL error event to stderr with \`type:"error"\`, \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`.
+- Command results write exactly one JSON value to stdout, including \`doctor\`, \`batch\`, and \`cleanup\` failure reports; use the exit code and result fields.
+- Dispatch/runtime failures write one JSONL error event to stderr with \`type:"error"\`, \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`, while stdout stays empty.
 - Non-fatal warnings and \`--verbose\` HTTP traces are JSONL stderr events (\`type:"warning"\` / \`type:"trace"\`), never prose.
 - No prompts, help screens, tables, banners, or prose output are part of the contract.
-- Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 completed command with failed long-running DSS work.
+- Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 a failed long-running result or synchronous assertion.
+- Pass \`--json\` for compact single-line JSON on stdout; use it for agent discovery and other JSON results to minimize tokens. Without it, success JSON is pretty-printed.
 - \`--raw\` is the only stdout escape hatch: recipe payload commands emit raw bytes to stdout unless \`--output PATH\` is also set; with \`--output\`, stdout is the JSON string equal to \`PATH\` and the file receives exact raw bytes.
 - \`--fields a,b,c\` projects those fields from object or array-of-objects results; dotted paths (\`a.b.c\`) drill into nested objects, and missing fields become \`null\`; string and scalar results pass through unchanged.
 
 ## Discover commands
 
 \`\`\`text
-dss agent contract
-dss commands run
+dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --json
+dss commands run --fields dataset.create --json
+dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples --json
+dss commands run --fields dataset --json
+dss agent contract --fields commands.actions --json
 \`\`\`
 
-Use \`dss agent contract\` once to check \`agentContractVersion\`, stderr event schemas, non-JSON escape hatches, and compatibility rules. The command registry from \`dss commands run\` is the canonical schema for resources, actions, flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, structured examples, payload schemas, unsafe outputs, cleanup hints, and exit codes. Use it before choosing command syntax.
+Bootstrap with the scoped \`agent contract\` call above: \`protocol,agentContractVersion,cli,stdio,planning,compatibility\` cover protocol/schema compatibility, stderr event semantics, preferred discovery commands, non-JSON escape hatches, planning rules, and compatibility guarantees in ~250 tokens. Request \`schemas\` (the JSON schemas) or \`commands\` (the contract's discovery section) only when you actually need them.
+
+Before choosing command syntax, look the action up in the command registry: \`--fields RESOURCE.ACTION\` returns one complete entry, and appended \`.FIELD\` paths return only the metadata you need. Prefer the four-field projection \`usage,description,flags,examples\` by default — it is the smallest self-sufficient starting point for constructing an invocation. The registry entry is the canonical schema for flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, structured examples, payload schemas, unsafe outputs, cleanup hints, and exit codes.
+
+\`--fields\` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (\`--fields dataset.create\` returns \`{"dataset.create": {...}}\`). Enumerate every resource and action with \`dss agent contract --fields commands.actions --json\` (~1k tokens); the hundreds-of-thousands-token unscoped registry is compatibility-only. An unknown resource or action exits with code 1 and a JSON error envelope on stderr containing the valid options.
 Credential lookup order is flags first, then \`DATAIKU_*\` environment variables, then saved credentials.
 Set \`DATAIKU_DISABLE_ENV=1\` when a test must ignore both \`.env\` files and \`DATAIKU_*\` environment variables.
 When \`.env\` loading is enabled, the CLI reads \`.env\` from the command's current working directory first and then the CLI build/root directory; the invocation directory wins on conflicting keys. Put test-specific \`.env\` files in the directory where you invoke \`dss\`.
@@ -37,7 +45,7 @@ For disposable agent tests, set \`DSS_CONFIG_DIR\` to a temporary directory so s
 - Use \`--dry-run\` only when that action's registry entry has \`dryRun:true\`. \`--plan\` explains the operation; \`--dry-run\` exercises the action-specific simulation path. Never add an unsupported flag.
 - When a create/upload action advertises \`--record-cleanup\`, pass \`--record-cleanup cleanup.jsonl\`. \`dss cleanup --file cleanup.jsonl\` previews the recorded cleanup steps in reverse order and does not mutate DSS; add \`--apply\` only after checking the preview.
 - For JSON payload actions, follow \`inputContract\`, \`requiredFlags\`, and \`requiredOneOf\`. Prefer \`--data-file PATH\` or \`--stdin\` when advertised instead of inline \`--data\`; this preserves exact JSON across shells and keeps large or sensitive payloads out of process arguments.
-- Authenticated actions advertise \`--request-timeout MS\` and \`--retries N\`. Long-running actions separately advertise controls such as \`--timeout MS\`, \`--poll-interval MS\`, and log limits; use only the flags in that action's registry entry.
+- Authenticated actions advertise \`--request-timeout MS\` and \`--retries N\`; \`--retries\` applies to idempotent GET requests. Long-running actions separately advertise controls such as \`--timeout MS\`, \`--poll-interval MS\`, and log limits; use only the flags in that action's registry entry.
 - Before live mutation tests, use \`dss fixtures --json\` to discover compatible test resources instead of guessing project objects.
 
 ## Authentication
@@ -84,25 +92,74 @@ TLS flags: \`--insecure\` disables certificate verification; \`--ca-cert PATH\`
 \`\`\`text
 dss version
 dss project list
-dss doctor --fast
 dss dataset list --project-key MYPROJ
-dss dataset list --project-key MYPROJ --fields name,type
-dss dataset preview orders --max-rows 10 --project-key MYPROJ
-dss recipe get-payload compute_orders --project-key MYPROJ
-dss recipe get-payload compute_orders --raw --project-key MYPROJ
 dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
 dss recipe diff compute_orders --file code.py --project-key MYPROJ
 dss recipe set-payload compute_orders --file code.py --project-key MYPROJ
 dss job build-and-wait orders --include-logs --project-key MYPROJ
-dss scenario run daily_build --project-key MYPROJ
 dss sql query --connection analytics --sql "select 1" --project-key MYPROJ
-dss sql query --dataset MYPROJ.orders --sql-file query.sql
-dss notebook clear-jupyter-outputs exploration --dry-run --project-key MYPROJ
-dss api-service list-packages churn-service --project-key MYPROJ
 dss batch --data-file steps.json
 \`\`\`
 For fake-DSS smoke tests, return project lists as JSON arrays such as \`[{"projectKey":"MYPROJ","name":"My Project"}]\` from \`/public/api/projects/\`; recipe payload commands read \`/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true\` and expect a JSON object shaped like \`{"recipe":{"name":"<NAME>","type":"python"},"payload":"..."}\`.
 
+## Application release safety
+
+Treat app release as explicit validate, compare, version, successor, verify, and permission gates.
+The public app-manifest \`version\` field is raw metadata: writing it is NOT a publish transaction.
+New instances inherit the template's raw \`version\`; existing instances are never upgraded in
+place — create an additive successor (the old instance is preserved), verify it, then retire the
+old one as a separate guarded step. Never infer private publish/recreate/rename,
+recipient-sharing, or UI-click operations that the public DSS API does not expose.
+
+\`\`\`text
+dss app validate-manifest --project-key APP_TEMPLATE
+dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
+dss app manifest-version --project-key APP_TEMPLATE
+dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+# targetProjectKey in instance.json must be confirmed absent
+dss app create-instance APP_ID --data-file instance.json --wait --record-cleanup cleanup.jsonl
+dss app create-successor-instance APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
+dss app verify-instance APP_ID --project-key RELEASE_INSTANCE_V2 --expect-version 1.4.0
+dss cleanup --file cleanup.jsonl
+dss app permissions-snapshot --project-key RELEASE_INSTANCE --output permissions.json
+dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
+dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
+\`\`\`
+
+An invalid manifest exits non-zero with the validation result in the structured error details.
+Review the cleanup preview before \`dss cleanup --file cleanup.jsonl --apply\`. Every new entry is
+bound to the canonical DSS URL. App cleanup records a \`creationTag\` hash observed after the DSS
+future identifies its target key; unconfirmed creation stops unresolved. The future target and
+later \`creationTag\` are independent, non-atomic observations because the public API exposes
+neither an immutable project ID joined to the future nor a conditional DELETE. Cleanup rechecks
+type and \`creationTag\` immediately before deletion, rejecting detected key reuse but unable to
+eliminate replacement in the remaining check-to-DELETE gap. Apply validates the full ledger before
+any request and rejects legacy, mixed-server, mismatched-server, or unbound app cleanup entries.
+The successor's cleanup ledger entry targets only the new project key;
+the predecessor is never targeted. Some DSS deployments return 403 for an unknown target project:
+instance creation requires confirmed target absence before POST, so an inaccessible target absent
+from the visible project list is still rejected as unconfirmed rather than risking cleanup against
+a pre-existing project. A definitive create rejection never produces a cleanup entry.
+
+\`app set-manifest-version\` reports
+\`concurrencyControl:"client-side-non-atomic-stale-read-check"\`. \`--expect-hash SHA256\` refuses the
+write when the manifest already changed, but the PUT itself stays unconditional: this command can
+overwrite a writer that commits inside the read-then-write window, and the post-write read cannot
+detect that lost update when this command's payload wins. Never treat the hash as a serializing lock.
+An ambiguous manifest PUT or verification read exits non-zero with \`persisted:null\`,
+\`after:null\`, and \`outcome:"indeterminate"\`; it never claims success or rejection.
+
+The API key authenticates public REST only. \`app verify-instance\` reports \`apiReady:true\`,
+\`status:"API_VERIFIED_UI_PENDING"\`, and \`uiPublicationVerified:false\`. Its \`visual-ui\` gate
+requires a pre-authenticated SSO browser session or dedicated UI test identity and evidence from
+exercising the affected tiles, forms, and actions; the CLI never marks that external gate complete.
+Permission snapshots have an integrity hash bound to the canonical DSS URL, project key, and
+observed concrete project incarnation from \`creationTag\`; diff and restore reject detected server,
+key, or incarnation mismatches. DSS exposes no conditional permission PUT, so these client-side checks
+narrow and detect key-reuse races but cannot serialize the final check with the write. Snapshots
+contain access-control identities; keep them mode \`0600\` and commit them only when repository
+policy permits.
+
 ## Confirming mutations
 
 Mutations print a small JSON ack to stdout and exit 0 on success (e.g. \`{"updated":"NAME","resource":"recipe"}\`); on failure they print the error envelope to stderr and exit non-zero. The exit code is the source of truth.
@@ -122,10 +179,11 @@ Mutations print a small JSON ack to stdout and exit 0 on success (e.g. \`{"updat
 - \`dss api-service list-packages SERVICE\` first verifies the parent service through its settings. A \`not_found\` error means the service is missing (verify the service ID and project key); an empty array means the service exists but has no deployable packages. Do not reinterpret \`not_found\` as an empty package list or retry the lower-level packages route.
 - \`dss notebook clear-jupyter-outputs NAME --dry-run\` returns the full \`current\` and \`next\` notebook states. Applying it clears \`outputs\` and resets \`execution_count\` to \`0\` only on code cells, preserving markdown and raw cells unchanged.
 - \`dss sql query ... --dataset PROJECT.NAME\` first queries through the dataset. If DSS rejects that dataset connection as neither SQL nor HDFS, the CLI reads dataset metadata and retries with \`params.connection\` (using its schema or catalog as the database when available). A readable dataset with no usable connection exits with \`validation_failed\` and advises \`--connection\`; dataset metadata \`404\` and \`403\` errors propagate as \`not_found\` and \`permission_denied\`.
+- \`dss sql query ... --start-retries N\` opts the query-start POST into transient retries with exponential backoff. A lost response can cause DSS to execute the SQL more than once, so use it only for SQL whose repetition is safe; ordinary \`--retries N\` remains GET-only.
 
 ## Error envelope
 
-Parse each stderr line as JSON; on non-zero exit the final line is an error event:
+For dispatch/runtime failures, parse stderr as JSONL; the final line is an error event:
 
 \`\`\`json
 {
@@ -140,6 +198,7 @@ Parse each stderr line as JSON; on non-zero exit the final line is an error even
 }
 \`\`\`
 
+\`doctor\`, \`batch\`, and \`cleanup\` report command-level failures on stdout and leave stderr empty. Use the exit code before choosing a stream.
 Use \`code\`, \`category\`, \`exitCode\`, \`retryable\`, \`status\`, and \`details\` for recovery logic. Do not scrape message text when a structured field is available.
 Treat \`details.body\` as sanitized metadata only: it contains at most \`requestId\`/\`request_id\`/\`errorId\`/\`elapsedMs\` plus locally trusted target/timing fields, not the arbitrary DSS response body. \`details.statusText\` is canonical text derived from the numeric status, not a remote reason phrase. Base recovery on top-level \`code\`, \`category\`, \`status\`, \`retryable\`, \`requestId\`, \`hint\`, and \`details.dssCategory\`; never parse or expose assumed server-body fields.
 `;
@@ -148,8 +207,8 @@ name: dataiku-dss
 description: >-
   Agent-only JSON CLI for Dataiku DSS. Use to inspect or mutate DSS projects,
   datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables,
-  code envs, and connections. Discover the full machine-readable surface with
-  dss commands run.
+  code envs, and connections. Discover scoped command metadata with
+  dss commands run --fields RESOURCE.ACTION --json.
 ---
 
 `;

package/dist/src/utils/cleanup-ledger.d.ts

@@ -7,9 +7,42 @@ export interface CleanupLedgerEntry {
     name?: string;
     path?: string;
     projectKey?: string;
+    /** Canonical DSS base URL the entry was recorded against. Absent only on legacy ledgers. */
+    dssUrl?: string;
     cleanup: {
         argv: string[];
     };
 }
-export declare function appendCleanupLedgerEntry(filePath: string, entry: CleanupLedgerEntry): Promise<void>;
+/**
+ * Prove that a cleanup ledger path can be written before any remote mutation.
+ * A parent directory is created when missing (matching append behavior); an
+ * existing ledger file is opened for append; a not-yet-existing ledger file is
+ * probed by creating and removing a sibling file, so nothing is left behind.
+ * Throws a plain Error with a non-secret message on any failure.
+ */
+export declare function preflightCleanupLedgerPath(filePath: string): Promise<void>;
+/**
+ * Atomically bind a cleanup ledger path to one DSS server before a mutation.
+ * The adjacent owner-only reservation closes the empty-ledger race: processes
+ * targeting different servers cannot both pass preflight and mutate before
+ * either cleanup entry is appended. The reservation intentionally persists
+ * even when a mutation fails, because another same-server process may already
+ * rely on it.
+ */
+export declare function reserveCleanupLedgerDssUrl(filePath: string, dssUrl: string): Promise<void>;
+export interface CleanupLedgerBindingViolation {
+    index: number;
+    resource: string;
+    action: string;
+    reason: "missing" | "mismatch";
+    /** Canonical URL the entry was bound to, for mismatch reasons. */
+    found?: string;
+}
+/**
+ * First entry not exactly bound to `expectedDssUrl` (both canonicalized), in
+ * ledger order. Legacy entries without a `dssUrl` count as missing. Intentionally
+ * never exposes argv/ids: the violation is identifiable by index alone.
+ */
+export declare function findCleanupLedgerBindingViolation(entries: CleanupLedgerEntry[], expectedDssUrl: string): CleanupLedgerBindingViolation | undefined;
+export declare function appendCleanupLedgerEntry(filePath: string, entry: CleanupLedgerEntry, dssUrl: string): Promise<void>;
 export declare function readCleanupLedger(filePath: string): Promise<CleanupLedgerEntry[]>;

package/dist/src/utils/cleanup-ledger.js

@@ -1,5 +1,6 @@
-import { appendFile, mkdir, readFile, } from "node:fs/promises";
-import { dirname, resolve, } from "node:path";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { canonicalDssUrl, } from "./dss-url.js";
 function isCleanupLedgerEntry(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -12,16 +13,126 @@ function isCleanupLedgerEntry(value) {
         return false;
     if (!candidate.cleanup || typeof candidate.cleanup !== "object")
         return false;
+    if (candidate.dssUrl !== undefined && typeof candidate.dssUrl !== "string")
+        return false;
     const cleanup = candidate.cleanup;
     return Array.isArray(cleanup.argv) && cleanup.argv.every((arg) => typeof arg === "string");
 }
-export async function appendCleanupLedgerEntry(filePath, entry) {
-    const resolved = resolve(filePath);
-    await mkdir(dirname(resolved), { recursive: true, });
-    await appendFile(resolved, `${JSON.stringify(entry)}\n`, "utf-8");
+/**
+ * Prove that a cleanup ledger path can be written before any remote mutation.
+ * A parent directory is created when missing (matching append behavior); an
+ * existing ledger file is opened for append; a not-yet-existing ledger file is
+ * probed by creating and removing a sibling file, so nothing is left behind.
+ * Throws a plain Error with a non-secret message on any failure.
+ */
+export async function preflightCleanupLedgerPath(filePath) {
+    const resolved = path.resolve(filePath);
+    const parent = path.dirname(resolved);
+    await fs.mkdir(parent, { recursive: true, });
+    let stats;
+    try {
+        stats = await fs.stat(resolved);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error(`Could not preflight cleanup ledger ${resolved}: ${error instanceof Error ? error.message : String(error)}`, { cause: error, });
+        }
+    }
+    if (stats?.isDirectory()) {
+        throw new Error(`Cleanup ledger path is a directory, not a file: ${resolved}`);
+    }
+    if (stats !== undefined) {
+        try {
+            const handle = await fs.open(resolved, "a");
+            await handle.close();
+        }
+        catch (error) {
+            const code = error.code;
+            throw new Error(code === "EACCES" || code === "EPERM"
+                ? `Cleanup ledger file is not writable: ${resolved}`
+                : `Could not preflight cleanup ledger ${resolved}: ${error instanceof Error ? error.message : String(error)}`, { cause: error, });
+        }
+        return;
+    }
+    const probePrefix = `${resolved}.preflight-`;
+    try {
+        const probe = await fs.mkdtemp(probePrefix);
+        await fs.rm(probe, { recursive: true, force: true, });
+    }
+    catch (error) {
+        throw new Error(`Cleanup ledger directory is not writable: ${parent}${error instanceof Error ? ` (${error.message})` : ""}`, { cause: error, });
+    }
+}
+/**
+ * Atomically bind a cleanup ledger path to one DSS server before a mutation.
+ * The adjacent owner-only reservation closes the empty-ledger race: processes
+ * targeting different servers cannot both pass preflight and mutate before
+ * either cleanup entry is appended. The reservation intentionally persists
+ * even when a mutation fails, because another same-server process may already
+ * rely on it.
+ */
+export async function reserveCleanupLedgerDssUrl(filePath, dssUrl) {
+    const resolved = path.resolve(filePath);
+    const bindingPath = `${resolved}.dss-url`;
+    const expected = canonicalDssUrl(dssUrl);
+    await fs.mkdir(path.dirname(resolved), { recursive: true, });
+    try {
+        await fs.writeFile(bindingPath, `${expected}\n`, {
+            encoding: "utf-8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        return;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const raw = await fs.readFile(bindingPath, "utf-8");
+    let found;
+    try {
+        found = canonicalDssUrl(raw.trim());
+    }
+    catch (error) {
+        throw new Error("Cleanup ledger DSS binding is invalid.", { cause: error, });
+    }
+    if (found !== expected) {
+        throw new Error("Cleanup ledger is reserved for a different DSS server.");
+    }
+}
+/**
+ * First entry not exactly bound to `expectedDssUrl` (both canonicalized), in
+ * ledger order. Legacy entries without a `dssUrl` count as missing. Intentionally
+ * never exposes argv/ids: the violation is identifiable by index alone.
+ */
+export function findCleanupLedgerBindingViolation(entries, expectedDssUrl) {
+    const expected = canonicalDssUrl(expectedDssUrl);
+    for (const [index, entry,] of entries.entries()) {
+        const bound = typeof entry.dssUrl === "string" ? canonicalDssUrl(entry.dssUrl) : undefined;
+        if (!bound) {
+            return { index, resource: entry.resource, action: entry.action, reason: "missing", };
+        }
+        if (bound !== expected) {
+            return {
+                index,
+                resource: entry.resource,
+                action: entry.action,
+                reason: "mismatch",
+                found: bound,
+            };
+        }
+    }
+    return undefined;
+}
+export async function appendCleanupLedgerEntry(filePath, entry, dssUrl) {
+    const resolved = path.resolve(filePath);
+    await fs.mkdir(path.dirname(resolved), { recursive: true, });
+    await reserveCleanupLedgerDssUrl(resolved, dssUrl);
+    const bound = { ...entry, dssUrl: canonicalDssUrl(dssUrl), };
+    await fs.appendFile(resolved, `${JSON.stringify(bound)}\n`, "utf-8");
 }
 export async function readCleanupLedger(filePath) {
-    const content = await readFile(resolve(filePath), "utf-8");
+    const content = await fs.readFile(path.resolve(filePath), "utf-8");
     return content
         .split(/\r?\n/)
         .map((line) => line.trim())

package/dist/src/utils/dss-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonical identity for a DSS base URL stored in local safety artifacts.
+ * Formatting differences do not break binding, and embedded URL credentials
+ * are never serialized or echoed.
+ */
+export declare function canonicalDssUrl(raw: string): string;

package/dist/src/utils/dss-url.js

@@ -0,0 +1,17 @@
+/**
+ * Canonical identity for a DSS base URL stored in local safety artifacts.
+ * Formatting differences do not break binding, and embedded URL credentials
+ * are never serialized or echoed.
+ */
+export function canonicalDssUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    try {
+        const parsed = new URL(trimmed);
+        parsed.username = "";
+        parsed.password = "";
+        return parsed.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return trimmed.replace(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@]*@/, "$1");
+    }
+}

package/dist/src/utils/project-incarnation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fingerprint one concrete DSS project incarnation using only the immutable
+ * creationTag. Mutable project metadata, including projectAppType and
+ * versionTag, is intentionally excluded.
+ */
+export declare function projectIncarnationHash(projectKey: string, projectDetails: unknown): string | undefined;

package/dist/src/utils/project-incarnation.js

@@ -0,0 +1,27 @@
+import { stableHash, } from "./stable-hash.js";
+function plainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Fingerprint one concrete DSS project incarnation using only the immutable
+ * creationTag. Mutable project metadata, including projectAppType and
+ * versionTag, is intentionally excluded.
+ */
+export function projectIncarnationHash(projectKey, projectDetails) {
+    const details = plainRecord(projectDetails);
+    if (!details)
+        return undefined;
+    const returnedKey = details["projectKey"];
+    if (typeof returnedKey !== "string" || returnedKey.trim() !== projectKey)
+        return undefined;
+    const creationTag = plainRecord(details["creationTag"]);
+    if (!creationTag)
+        return undefined;
+    const lastModifiedOn = creationTag["lastModifiedOn"];
+    if (!(typeof lastModifiedOn === "number" && Number.isFinite(lastModifiedOn))
+        && !(typeof lastModifiedOn === "string" && lastModifiedOn.trim().length > 0))
+        return undefined;
+    return stableHash({ projectKey, creationTag, });
+}

package/dist/src/utils/stable-hash.d.ts

@@ -0,0 +1,11 @@
+export declare function sha256Hex(value: string): string;
+/** Locale-independent UTF-16 code-unit order for deterministic machine output. */
+export declare function compareStrings(a: string, b: string): number;
+/**
+ * Deterministic JSON rendering: object keys are emitted in sorted order so two
+ * structurally identical values always produce the same string (and therefore
+ * the same hash) regardless of key insertion order. Array order is preserved
+ * because it is semantic.
+ */
+export declare function stableJson(value: unknown): string;
+export declare function stableHash(value: unknown): string;

package/dist/src/utils/stable-hash.js

@@ -0,0 +1,27 @@
+import { createHash, } from "node:crypto";
+export function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/** Locale-independent UTF-16 code-unit order for deterministic machine output. */
+export function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Deterministic JSON rendering: object keys are emitted in sorted order so two
+ * structurally identical values always produce the same string (and therefore
+ * the same hash) regardless of key insertion order. Array order is preserved
+ * because it is semantic.
+ */
+export function stableJson(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    const entries = Object.entries(value).sort(([a,], [b,]) => compareStrings(a, b));
+    return `{${entries.map(([key, item,]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+export function stableHash(value) {
+    return sha256Hex(stableJson(value));
+}

package/node_modules/@sinclair/typebox/build/cjs/compiler/compiler.js

@@ -91,35 +91,6 @@ var Character;
     Character.IsNumeric = IsNumeric;
 })(Character || (Character = {}));
 // ------------------------------------------------------------------
-// MemberExpression
-// ------------------------------------------------------------------
-var MemberExpression;
-(function (MemberExpression) {
-    function IsFirstCharacterNumeric(value) {
-        if (value.length === 0)
-            return false;
-        return Character.IsNumeric(value.charCodeAt(0));
-    }
-    function IsAccessor(value) {
-        if (IsFirstCharacterNumeric(value))
-            return false;
-        for (let i = 0; i < value.length; i++) {
-            const code = value.charCodeAt(i);
-            const check = Character.IsAlpha(code) || Character.IsNumeric(code) || Character.DollarSign(code) || Character.IsUnderscore(code);
-            if (!check)
-                return false;
-        }
-        return true;
-    }
-    function EscapeHyphen(key) {
-        return key.replace(/'/g, "\\'");
-    }
-    function Encode(object, key) {
-        return IsAccessor(key) ? `${object}.${key}` : `${object}['${EscapeHyphen(key)}']`;
-    }
-    MemberExpression.Encode = Encode;
-})(MemberExpression || (MemberExpression = {}));
-// ------------------------------------------------------------------
 // Identifier
 // ------------------------------------------------------------------
 var Identifier;
@@ -140,15 +111,21 @@ var Identifier;
     Identifier.Encode = Encode;
 })(Identifier || (Identifier = {}));
 // ------------------------------------------------------------------
-// LiteralString
+// StringConstant
 // ------------------------------------------------------------------
-var LiteralString;
-(function (LiteralString) {
-    function Escape(content) {
-        return content.replace(/'/g, "\\'");
-    }
-    LiteralString.Escape = Escape;
-})(LiteralString || (LiteralString = {}));
+function StringConstant(value) {
+    if (!(0, index_12.IsString)(value))
+        throw Error('ConstantString: Not a String');
+    const canonical = JSON.stringify(value).slice(1, -1);
+    const escaped = canonical.replace(/'/g, "\\'");
+    return `'${escaped}'`;
+}
+// ------------------------------------------------------------------
+// MemberExpression
+// ------------------------------------------------------------------
+function MemberExpression(value, key) {
+    return `${value}[${StringConstant(key)}]`;
+}
 // ------------------------------------------------------------------
 // Errors
 // ------------------------------------------------------------------
@@ -172,7 +149,7 @@ exports.TypeCompilerTypeGuardError = TypeCompilerTypeGuardError;
 var Policy;
 (function (Policy) {
     function IsExactOptionalProperty(value, key, expression) {
-        return index_3.TypeSystemPolicy.ExactOptionalPropertyTypes ? `('${key}' in ${value} ? ${expression} : true)` : `(${MemberExpression.Encode(value, key)} !== undefined ? ${expression} : true)`;
+        return index_3.TypeSystemPolicy.ExactOptionalPropertyTypes ? `(${StringConstant(key)} in ${value} ? ${expression} : true)` : `(${MemberExpression(value, key)} !== undefined ? ${expression} : true)`;
     }
     Policy.IsExactOptionalProperty = IsExactOptionalProperty;
     function IsObjectLike(value) {
@@ -317,8 +294,11 @@ var TypeCompiler;
         if (typeof schema.const === 'number' || typeof schema.const === 'boolean') {
             yield `(${value} === ${schema.const})`;
         }
+        else if (typeof schema.const === 'string') {
+            yield `(${value} === ${StringConstant(schema.const)})`;
+        }
         else {
-            yield `(${value} === '${LiteralString.Escape(schema.const)}')`;
+            throw Error('Invalid Literal Value');
         }
     }
     function* FromNever(schema, references, value) {
@@ -352,12 +332,12 @@ var TypeCompiler;
             yield `Object.getOwnPropertyNames(${value}).length <= ${schema.maxProperties}`;
         const knownKeys = Object.getOwnPropertyNames(schema.properties);
         for (const knownKey of knownKeys) {
-            const memberExpression = MemberExpression.Encode(value, knownKey);
+            const memberExpression = MemberExpression(value, knownKey);
             const property = schema.properties[knownKey];
             if (schema.required && schema.required.includes(knownKey)) {
                 yield* Visit(property, references, memberExpression);
                 if ((0, extends_undefined_1.ExtendsUndefinedCheck)(property) || IsAnyOrUnknown(property))
-                    yield `('${knownKey}' in ${value})`;
+                    yield `(${StringConstant(knownKey)} in ${value})`;
             }
             else {
                 const expression = CreateExpression(property, references, memberExpression);
@@ -369,13 +349,13 @@ var TypeCompiler;
                 yield `Object.getOwnPropertyNames(${value}).length === ${knownKeys.length}`;
             }
             else {
-                const keys = `[${knownKeys.map((key) => `'${key}'`).join(', ')}]`;
+                const keys = `[${knownKeys.map((key) => `${StringConstant(key)}`).join(', ')}]`;
                 yield `Object.getOwnPropertyNames(${value}).every(key => ${keys}.includes(key))`;
             }
         }
         if (typeof schema.additionalProperties === 'object') {
             const expression = CreateExpression(schema.additionalProperties, references, `${value}[key]`);
-            const keys = `[${knownKeys.map((key) => `'${key}'`).join(', ')}]`;
+            const keys = `[${knownKeys.map((key) => `${StringConstant(key)}`).join(', ')}]`;
             yield `(Object.getOwnPropertyNames(${value}).every(key => ${keys}.includes(key) || ${expression}))`;
         }
     }
@@ -423,7 +403,7 @@ var TypeCompiler;
             yield `${variable}.test(${value})`;
         }
         if (schema.format !== undefined) {
-            yield `format('${schema.format}', ${value})`;
+            yield `format(${StringConstant(schema.format)}, ${value})`;
         }
     }
     function* FromSymbol(schema, references, value) {
@@ -471,7 +451,7 @@ var TypeCompiler;
     function* FromKind(schema, references, value) {
         const instance = state.instances.size;
         state.instances.set(instance, schema);
-        yield `kind('${schema[index_7.Kind]}', ${instance}, ${value})`;
+        yield `kind(${StringConstant(schema[index_7.Kind])}, ${instance}, ${value})`;
     }
     function* Visit(schema, references, value, useHoisting = true) {
         const references_ = (0, index_12.IsString)(schema.$id) ? [...references, schema] : references;
@@ -645,7 +625,7 @@ var TypeCompiler;
     /** Compiles a TypeBox type for optimal runtime type checking. Types must be valid TypeBox types of TSchema */
     function Compile(schema, references = []) {
         const generatedCode = Code(schema, references, { language: 'javascript' });
-        const compiledFunction = globalThis.Function('kind', 'format', 'hash', generatedCode);
+        const compiledFunction = (0, index_3.Evaluate)('kind', 'format', 'hash', generatedCode);
         const instances = new Map(state.instances);
         function typeRegistryFunction(kind, instance, value) {
             if (!index_8.TypeRegistry.Has(kind) || !instances.has(instance))

package/node_modules/@sinclair/typebox/build/cjs/parser/runtime/guard.d.ts

@@ -20,4 +20,4 @@ export declare function IsTuple(value: unknown): value is ITuple;
 /** Returns true if the value is a Union Parser */
 export declare function IsUnion(value: unknown): value is IUnion;
 /** Returns true if the value is a Parser */
-export declare function IsParser(value: unknown): value is IContext<unknown> | IUnion<unknown> | IArray<unknown> | IConst<unknown> | IIdent<unknown> | INumber<unknown> | IOptional<unknown> | IRef<unknown> | IString<unknown> | ITuple<unknown>;
+export declare function IsParser(value: unknown): value is IArray<unknown> | IConst<unknown> | IContext<unknown> | IIdent<unknown> | INumber<unknown> | IOptional<unknown> | IRef<unknown> | IString<unknown> | ITuple<unknown> | IUnion<unknown>;

package/node_modules/@sinclair/typebox/build/cjs/parser/runtime/token.d.ts

@@ -3,6 +3,6 @@ export declare function Const(value: string, code: string): [] | [string, string
 /** Scans for the next Ident token */
 export declare function Ident(code: string): [] | [string, string];
 /** Scans for the next number token */
-export declare function Number(code: string): [string, string] | [];
+export declare function Number(code: string): [] | [string, string];
 /** Scans the next Literal String value */
-export declare function String(options: string[], code: string): [string, string] | [];
+export declare function String(options: string[], code: string): [] | [string, string];

package/node_modules/@sinclair/typebox/build/cjs/syntax/mapping.d.ts

@@ -121,7 +121,7 @@ export declare function AsyncIteratorMapping(input: [unknown, unknown, unknown,
 export type TIteratorMapping<Input extends [unknown, unknown, unknown, unknown], Context extends T.TProperties> = Input extends ['Iterator', '<', infer Type extends T.TSchema, '>'] ? T.TIterator<Type> : never;
 export declare function IteratorMapping(input: [unknown, unknown, unknown, unknown], context: unknown): T.TIterator<T.TSchema>;
 export type TArgumentMapping<Input extends [unknown, unknown, unknown, unknown], Context extends T.TProperties> = Input extends ['Argument', '<', infer Type extends T.TSchema, '>'] ? Type extends T.TLiteral<infer Index extends number> ? T.TArgument<Index> : T.TNever : never;
-export declare function ArgumentMapping(input: [unknown, unknown, unknown, unknown], context: unknown): T.TNever | T.TArgument<number>;
+export declare function ArgumentMapping(input: [unknown, unknown, unknown, unknown], context: unknown): T.TArgument<number> | T.TNever;
 export type TAwaitedMapping<Input extends [unknown, unknown, unknown, unknown], Context extends T.TProperties> = Input extends ['Awaited', '<', infer Type extends T.TSchema, '>'] ? T.TAwaited<Type> : never;
 export declare function AwaitedMapping(input: [unknown, unknown, unknown, unknown], context: unknown): T.TSchema;
 export type TArrayMapping<Input extends [unknown, unknown, unknown, unknown], Context extends T.TProperties> = Input extends ['Array', '<', infer Type extends T.TSchema, '>'] ? T.TArray<Type> : never;

package/node_modules/@sinclair/typebox/build/cjs/system/evaluate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Evaluates code in the current environment. This function matches centralized
+ * evaluation as implemented in TypeBox 1.x.
+ */
+export declare function Evaluate(...args: string[]): globalThis.Function;