@sanity/ailf 4.5.0 → 5.0.0

package/dist/_vendor/ailf-core/artifact-registry.js

@@ -24,6 +24,26 @@
  * @see docs/design-docs/unified-run-artifacts.md (§ M1, § M5)
  */
 import { z } from "zod";
+/**
+ * Opt-in marker for the bulk-versioned-with-report-axis carve-out
+ * (Plan 01-03 / ITER2-BLOCKER-01). Any descriptor that needs to combine
+ * `layout: "bulk"` with a `report` axis (e.g. the post-hoc diagnosis
+ * artifact) must set
+ * `pathSafetyMarker: BULK_VERSIONED_WITH_REPORT_AXIS` to opt in to the
+ * carve-out in `assertValidArtifactDescriptor`.
+ *
+ * `Symbol.for(...)` is registry-keyed: it survives minification (the
+ * key is a string literal that minifiers cannot rename) and yields
+ * cross-module-instance equality by spec. This makes it bundler-stable
+ * — a deliberate replacement for any source-text reflection on the
+ * descriptor's `objectPath` closure body.
+ *
+ * The marker alone does NOT trigger the carve-out — the four structural
+ * conditions (bulk + versionedBy + run+report axes) must also hold.
+ * Conversely, the structural conditions alone do NOT trigger the
+ * carve-out without the marker. This is an explicit opt-in.
+ */
+export const BULK_VERSIONED_WITH_REPORT_AXIS = Symbol.for("ailf.artifactRegistry.bulkVersionedWithReportAxis");
 // ---------------------------------------------------------------------------
 // Path + key helpers
 // ---------------------------------------------------------------------------
@@ -59,6 +79,221 @@ function perEntryPathBuilder(slug, mime) {
         return `runs/${runId}/${slug}/${sanitized}.${ext}`;
     };
 }
+/**
+ * Bulk-shaped path builder with a `{version}` segment appended to the
+ * filename stem (D0050). Used by descriptors that opt into the versioning
+ * axis via `versionedBy`. Multiple versions coexist under the same run
+ * prefix as siblings:
+ *
+ *   `runs/{runId}/{slug}-v1.{ext}`
+ *   `runs/{runId}/{slug}-v2.{ext}`
+ *
+ * The version segment is sanitized via `sanitizeEntryKey` so versions
+ * containing `/` or wire separators don't accidentally nest into
+ * subdirectories. Empty / whitespace-only versions are rejected — a
+ * versioned descriptor with no version is a programmer error, not silently
+ * collapsed to an unversioned path.
+ */
+export function versionedPathBuilder(slug, mime) {
+    const ext = mimeExtension(mime);
+    return (runId, _entryKey, version) => {
+        if (version === undefined || version.trim() === "") {
+            throw new Error(`Artifact "${slug}" uses versioned layout; a non-empty version is required`);
+        }
+        if (hasControlChars(version)) {
+            throw new Error(`Artifact "${slug}" version must not contain control characters`);
+        }
+        const sanitized = sanitizeEntryKey(version);
+        return `runs/${runId}/${slug}-${sanitized}.${ext}`;
+    };
+}
+/**
+ * Synchronous SHA-256 over a UTF-8-encoded string returning a lowercase
+ * hex digest. Implemented inline because `@sanity/ailf-core` is the
+ * domain kernel — it intentionally avoids a `@types/node` dependency
+ * (matching the existing `byteLengthUtf8` rationale below) and the
+ * Web Crypto `crypto.subtle.digest` API is async-only, which would
+ * force `ArtifactObjectPath` to become async.
+ *
+ * Used only for the diagnosis descriptor's `cardSetShortHash` (the
+ * filename suffix) — collision resistance, not authentication, is the
+ * relevant property. FIPS 180-4 reference implementation.
+ */
+function sha256Hex(input) {
+    const K = [
+        0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+        0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+        0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+        0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+        0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+        0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+        0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+        0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+        0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+        0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+        0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+    ];
+    // UTF-8 encode (without TextEncoder reliance — kernel runs in both Node
+    // and the browser; both have TextEncoder by spec, but staying explicit
+    // mirrors the byteLengthUtf8 helper below).
+    const bytes = [];
+    for (let i = 0; i < input.length; i++) {
+        let c = input.charCodeAt(i);
+        if (c < 0x80) {
+            bytes.push(c);
+        }
+        else if (c < 0x800) {
+            bytes.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+        }
+        else if (c >= 0xd800 && c < 0xdc00 && i + 1 < input.length) {
+            // surrogate pair
+            const c2 = input.charCodeAt(i + 1);
+            const cp = 0x10000 + (((c & 0x3ff) << 10) | (c2 & 0x3ff));
+            bytes.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+            i++;
+        }
+        else {
+            bytes.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+        }
+    }
+    // Pre-processing: padding
+    const bitLen = bytes.length * 8;
+    bytes.push(0x80);
+    while (bytes.length % 64 !== 56)
+        bytes.push(0);
+    // 64-bit big-endian length (high 32 bits zero — input < 2^32 bits is the
+    // realistic ceiling here).
+    bytes.push(0, 0, 0, 0);
+    bytes.push((bitLen >>> 24) & 0xff, (bitLen >>> 16) & 0xff, (bitLen >>> 8) & 0xff, bitLen & 0xff);
+    let h0 = 0x6a09e667;
+    let h1 = 0xbb67ae85;
+    let h2 = 0x3c6ef372;
+    let h3 = 0xa54ff53a;
+    let h4 = 0x510e527f;
+    let h5 = 0x9b05688c;
+    let h6 = 0x1f83d9ab;
+    let h7 = 0x5be0cd19;
+    const W = new Array(64);
+    for (let chunk = 0; chunk < bytes.length; chunk += 64) {
+        for (let i = 0; i < 16; i++) {
+            const j = chunk + i * 4;
+            W[i] =
+                ((bytes[j] << 24) |
+                    (bytes[j + 1] << 16) |
+                    (bytes[j + 2] << 8) |
+                    bytes[j + 3]) >>>
+                    0;
+        }
+        for (let i = 16; i < 64; i++) {
+            const a = W[i - 15];
+            const b = W[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            W[i] = (W[i - 16] + s0 + W[i - 7] + s1) >>> 0;
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        let f = h5;
+        let g = h6;
+        let h = h7;
+        for (let i = 0; i < 64; i++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^
+                ((e >>> 11) | (e << 21)) ^
+                ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + S1 + ch + K[i] + W[i]) >>> 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^
+                ((a >>> 13) | (a << 19)) ^
+                ((a >>> 22) | (a << 10));
+            const mj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + mj) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+        h5 = (h5 + f) >>> 0;
+        h6 = (h6 + g) >>> 0;
+        h7 = (h7 + h) >>> 0;
+    }
+    const toHex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+    return (toHex(h0) +
+        toHex(h1) +
+        toHex(h2) +
+        toHex(h3) +
+        toHex(h4) +
+        toHex(h5) +
+        toHex(h6) +
+        toHex(h7));
+}
+/**
+ * Two-axis post-hoc path builder for the diagnosis descriptor (Plan 01-03,
+ * D-09). Filename: `diagnosis-{diagnosisVersion}-{cardSetShortHash}.json`
+ * where `cardSetShortHash = sha256(cardVersion).slice(0, 12)`.
+ *
+ * The compound version argument is `${diagnosisVersion}|${cardVersion}`
+ * to fit the existing 3-arg `objectPath` signature without growing the
+ * shared `ArtifactObjectPath` shape. Callers should use
+ * `encodeDiagnosisPathVersion()` rather than building the compound
+ * string by hand.
+ *
+ * The diagnosis descriptor opts into the bulk-versioned-with-report-axis
+ * carve-out via `pathSafetyMarker: BULK_VERSIONED_WITH_REPORT_AXIS`
+ * (ITER2-BLOCKER-01). The builder itself does not need to know about
+ * the marker — it just builds the path; the carve-out is a registration-
+ * time concern in `assertValidArtifactDescriptor`.
+ */
+export function diagnosisPathBuilder() {
+    return (runId, reportId, version) => {
+        if (!reportId)
+            throw new Error("diagnosisPathBuilder requires reportId axis");
+        if (!version)
+            throw new Error("diagnosisPathBuilder requires compound version");
+        if (hasControlChars(reportId))
+            throw new Error("diagnosisPathBuilder reportId must not contain control characters");
+        const sep = version.indexOf("|");
+        if (sep <= 0)
+            throw new Error("diagnosisPathBuilder version must be ${diagnosisVersion}|${cardVersion}");
+        const dv = version.slice(0, sep);
+        const cv = version.slice(sep + 1);
+        if (hasControlChars(dv))
+            throw new Error("diagnosisPathBuilder diagnosisVersion must not contain control characters");
+        // Sanitize reportId and diagnosisVersion segments — `/` would otherwise
+        // create unintended GCS subdirectories and break the
+        // `runs/{runId}/{reportId}/diagnosis-…` path-prefix containment
+        // guarantee. Mirrors `versionedPathBuilder` (above).
+        const sanitizedReportId = sanitizeEntryKey(reportId);
+        const sanitizedDv = sanitizeEntryKey(dv);
+        const cardSetShortHash = sha256Hex(cv).slice(0, 12);
+        return `runs/${runId}/${sanitizedReportId}/diagnosis-${sanitizedDv}-${cardSetShortHash}.json`;
+    };
+}
+/**
+ * Pack the diagnosis descriptor's two version segments into the existing
+ * single-string `version` slot of `ArtifactObjectPath`. Separator is `|`;
+ * `diagnosisVersion` MUST NOT contain `|` (the function rejects that case).
+ */
+export function encodeDiagnosisPathVersion(diagnosisVersion, cardVersion) {
+    if (diagnosisVersion === "")
+        throw new Error("encodeDiagnosisPathVersion: diagnosisVersion must be a non-empty string");
+    if (cardVersion === "")
+        throw new Error("encodeDiagnosisPathVersion: cardVersion must be a non-empty string");
+    if (diagnosisVersion.includes("|"))
+        throw new Error("diagnosisVersion must not contain '|'");
+    return `${diagnosisVersion}|${cardVersion}`;
+}
 /**
  * Convert an entry key (wire format, e.g. `{taskId}::{modelId}`) to a
  * filename-safe component.
@@ -415,9 +650,12 @@ function titleCaseCategory(id) {
         .join(" ");
 }
 function buildDescriptor(input) {
-    const objectPath = input.layout === "bulk"
-        ? bulkPathBuilder(input.slug, input.mime)
-        : perEntryPathBuilder(input.slug, input.mime);
+    const objectPath = input.objectPath ??
+        (input.versionedBy
+            ? versionedPathBuilder(input.slug, input.mime)
+            : input.layout === "bulk"
+                ? bulkPathBuilder(input.slug, input.mime)
+                : perEntryPathBuilder(input.slug, input.mime));
     const formatEntryKey = input.layout === "per-entry" ? formatKeyFromAxes(input.axes) : undefined;
     const parseEntryKey = input.layout === "per-entry"
         ? (input.parseEntryKey ?? parseKeyByAxes(input.type, input.axes))
@@ -432,6 +670,9 @@ function buildDescriptor(input) {
         capBytes: input.capBytes,
         truncation: input.truncation,
         optional: input.optional,
+        writePolicy: input.writePolicy,
+        versionedBy: input.versionedBy,
+        pathSafetyMarker: input.pathSafetyMarker,
         objectPath,
         formatEntryKey,
         parseEntryKey,
@@ -932,6 +1173,49 @@ export const ARTIFACT_REGISTRY = {
         capBytes: 10_000_000,
         truncation: "trial-oversize",
     }),
+    // -- Plan 01-03 — Actionability ladder Phase 1 ---------------------------
+    diagnosis: buildDescriptor({
+        type: "diagnosis",
+        slug: "diagnosis",
+        layout: "bulk",
+        axes: ["run", "report"],
+        entrySchema: unknownEntry,
+        mime: "application/json",
+        capBytes: 5 * 1024 * 1024,
+        writePolicy: "post-hoc",
+        versionedBy: "diagnosisVersion",
+        objectPath: diagnosisPathBuilder(),
+        // Defense-in-depth: this descriptor's axes (`run`, `report`) are both
+        // bounded, so the `assertValidArtifactDescriptor` unbounded-axis rule
+        // does not fire and the carve-out is never consulted at module load
+        // for THIS descriptor. The marker is set so any future additions to
+        // this descriptor (or a new diagnosis-shaped descriptor that gains an
+        // unbounded axis like `task`) opt into the carve-out by default rather
+        // than tripping the bounded-axis rule. The marker also documents
+        // intent: this descriptor is the canonical reference for the
+        // bulk-versioned-with-report-axis pattern (ITER2-BLOCKER-01).
+        pathSafetyMarker: BULK_VERSIONED_WITH_REPORT_AXIS, // ITER2-BLOCKER-01 — explicit opt-in
+    }),
+    perEntryAttribution: buildDescriptor({
+        type: "perEntryAttribution",
+        slug: "attribution",
+        layout: "per-entry",
+        axes: ["run"],
+        entrySchema: unknownEntry,
+        mime: "application/json",
+        capBytes: 1 * 1024 * 1024,
+        writePolicy: "pipeline",
+    }),
+    attributionMeta: buildDescriptor({
+        type: "attributionMeta",
+        slug: "attribution-meta",
+        layout: "bulk",
+        axes: ["run"],
+        entrySchema: unknownEntry,
+        mime: "application/json",
+        capBytes: 1 * 1024 * 1024,
+        writePolicy: "pipeline",
+    }),
 };
 /** All artifact types in declaration order. */
 export const ARTIFACT_TYPES = Object.keys(ARTIFACT_REGISTRY);
@@ -943,25 +1227,61 @@ export function isArtifactType(value) {
     return value in ARTIFACT_REGISTRY;
 }
 // ---------------------------------------------------------------------------
-// Module-load invariant (D0033 / W0049)
+// Module-load invariant (D0033 / W0049 / D0050)
 // ---------------------------------------------------------------------------
 /**
  * Unbounded axes — dimensions whose cardinality grows with a run. A bulk
  * artifact fanning across these cannot bound its payload; the registry
  * forbids that shape at import time.
+ *
+ * **Layout rule (D0050).** Bulk descriptors must declare *only* bounded
+ * axes — fanning a single JSON across an unbounded axis (`task`, `model`,
+ * `trial`) violates the size cap at scale. Per-entry descriptors *may*
+ * declare unbounded axes; the per-entry layout naturally produces one
+ * object per axis tuple, so unboundedness becomes the file count, not
+ * the file size. The existing `testOutputs` per-entry descriptor has
+ * carried unbounded `task`+`model` axes since W0048 and is the precedent
+ * D0050 formalizes for attribution.
  */
 const UNBOUNDED_AXES = [
     "task",
     "model",
     "trial",
 ];
+/**
+ * The bulk-versioned-with-report-axis carve-out (Plan 01-03 /
+ * ITER2-BLOCKER-01) is an explicit opt-in: a descriptor must set
+ * `pathSafetyMarker === BULK_VERSIONED_WITH_REPORT_AXIS` AND meet the
+ * four structural conditions:
+ *
+ *   1. desc.pathSafetyMarker === BULK_VERSIONED_WITH_REPORT_AXIS  (gate)
+ *   2. desc.layout === "bulk"                                     (sanity)
+ *   3. Boolean(desc.versionedBy)                                  (sanity)
+ *   4. desc.association.axes.includes("run")                      (sanity)
+ *   5. desc.association.axes.includes("report")                   (sanity)
+ *
+ * Marker without structure → fails (the descriptor misapplied the marker).
+ * Structure without marker → fails (the descriptor must opt in).
+ *
+ * The marker is the SOLE detection mechanism. There is no source-text
+ * reflection on the descriptor's path-builder closure body — `Symbol.for(...)`
+ * is bundler-stable by spec and survives minification.
+ */
+function isBulkVersionedWithReportAxisCarveOut(desc) {
+    return (desc.pathSafetyMarker === BULK_VERSIONED_WITH_REPORT_AXIS &&
+        desc.layout === "bulk" &&
+        Boolean(desc.versionedBy) &&
+        desc.association.axes.includes("run") &&
+        desc.association.axes.includes("report"));
+}
 /**
  * Structural check run against a single descriptor. Exported so L1 contract
  * tests can construct an invalid descriptor inline and assert the throw.
  */
 export function assertValidArtifactDescriptor(desc) {
+    const carveOutApplies = isBulkVersionedWithReportAxisCarveOut(desc);
     const hasUnboundedAxis = desc.association.axes.some((a) => UNBOUNDED_AXES.includes(a));
-    if (hasUnboundedAxis && desc.layout !== "per-entry") {
+    if (hasUnboundedAxis && desc.layout !== "per-entry" && !carveOutApplies) {
         throw new Error(`Artifact ${desc.type}: association contains unbounded axis (${desc.association.axes
             .filter((a) => UNBOUNDED_AXES.includes(a))
             .join(", ")}) but layout is "${desc.layout}". Unbounded axes require layout "per-entry".`);
@@ -972,6 +1292,14 @@ export function assertValidArtifactDescriptor(desc) {
     if (desc.layout === "per-entry" && !desc.formatEntryKey) {
         throw new Error(`Artifact ${desc.type}: per-entry descriptors must declare formatEntryKey`);
     }
+    // D0050 — versioned descriptors are bulk-shaped only in v0; per-entry +
+    // versioned is a future extension and rejected at module load so a
+    // half-wired descriptor doesn't ship by accident. Bulk-versioned-with-
+    // report-axis (the diagnosis case) is permitted only via the explicit
+    // pathSafetyMarker opt-in checked above.
+    if (desc.versionedBy && desc.layout !== "bulk") {
+        throw new Error(`Artifact ${desc.type}: versionedBy is only supported on bulk descriptors (got layout "${desc.layout}")`);
+    }
 }
 // Fire the invariant at import time — a bad descriptor kills the process
 // before any producer can silently serialize an oversized JSON array.
@@ -979,6 +1307,92 @@ for (const desc of Object.values(ARTIFACT_REGISTRY)) {
     assertValidArtifactDescriptor(desc);
 }
 // ---------------------------------------------------------------------------
+// Write-policy guard (D0050)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a writer's identity (`writeSource`) doesn't match a
+ * descriptor's `writePolicy`. Pipeline writers can't emit `"post-hoc"`
+ * descriptors (the post-hoc artifact would land mid-run, before the run
+ * finalizes); post-hoc writers can't emit `"pipeline"` descriptors
+ * (those should have been written by the pipeline itself).
+ *
+ * The error type is intentionally distinct from `Error` so CI can match
+ * on the class and surface mismatches clearly in failure logs.
+ */
+export class WritePolicyMismatchError extends Error {
+    code = "WRITE_POLICY_MISMATCH";
+    artifactType;
+    descriptorPolicy;
+    writerSource;
+    constructor(opts) {
+        super(`Artifact "${opts.artifactType}" has writePolicy="${opts.descriptorPolicy}" but writer is "${opts.writerSource}". ` +
+            `Pipeline writers cannot emit post-hoc descriptors and post-hoc writers cannot emit pipeline descriptors.`);
+        this.name = "WritePolicyMismatchError";
+        this.artifactType = opts.artifactType;
+        this.descriptorPolicy = opts.descriptorPolicy;
+        this.writerSource = opts.writerSource;
+    }
+}
+/**
+ * Resolve a descriptor's effective write policy. Defaults to `"pipeline"`
+ * when unset — preserves backward compatibility with every pre-D0050
+ * descriptor that doesn't declare the field.
+ */
+export function resolveWritePolicy(desc) {
+    return desc.writePolicy ?? "pipeline";
+}
+/**
+ * Writer-side guard. Call at the top of `emit()` / `appendNdjson()` in
+ * every artifact writer that physically writes bytes (the in-memory test
+ * doubles don't need it). Throws `WritePolicyMismatchError` on
+ * mismatch; returns silently on a match. Pure function — no I/O, safe
+ * to invoke from any layer.
+ */
+export function assertWritePolicyMatches(writerSource, descriptor) {
+    const descriptorPolicy = resolveWritePolicy(descriptor);
+    if (descriptorPolicy !== writerSource) {
+        throw new WritePolicyMismatchError({
+            artifactType: descriptor.type,
+            descriptorPolicy,
+            writerSource,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Slim-shape preview for post-hoc artifacts (D0050)
+// ---------------------------------------------------------------------------
+/**
+ * Slim-shape preview for `"post-hoc"` descriptors. Replaces the
+ * fixed-path semantics that pipeline-written artifacts use (a single
+ * known path per descriptor) with `present: boolean` plus an optional
+ * `latestVersion: string` — necessary because:
+ *
+ *   - A post-hoc artifact may have zero versions (never written) or
+ *     multiple versions (regenerated). A fixed `path` cannot encode
+ *     either.
+ *   - Slim-shape consumers (Studio rollups) want to know "is there a
+ *     diagnosis for this run?" without enumerating versioned siblings.
+ *
+ * Post-hoc writers populate `latestVersion` after a successful write
+ * (last-write-wins per-version semantics, per D0050 open-question
+ * resolution). The full versioned payload is fetched via the
+ * descriptor's `objectPath(runId, undefined, latestVersion)`.
+ */
+export const postHocSlimPreviewSchema = z.object({
+    present: z.boolean(),
+    latestVersion: z.string().optional(),
+});
+/**
+ * Build a post-hoc slim-shape preview. `latestVersion` is omitted when
+ * absent rather than emitted as `undefined`, matching the optional-field
+ * convention used elsewhere in the registry.
+ */
+export function buildPostHocSlimPreview(opts) {
+    return opts.latestVersion === undefined
+        ? { present: opts.present }
+        : { present: opts.present, latestVersion: opts.latestVersion };
+}
+// ---------------------------------------------------------------------------
 // Manifest preview helper (W0051 / D0033 M7)
 // ---------------------------------------------------------------------------
 /**