@spottoai/types-package 1.0.2-dev1138.12 → 1.0.2-dev1138.14

package/dist/esm/common/validationHelpers.js

@@ -0,0 +1,115 @@
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const isString = (value) => typeof value === 'string' && value.trim().length > 0;
+export const isOptionalString = (value) => value === undefined || isString(value);
+export const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+export const isOptionalFiniteNumber = (value) => value === undefined || isFiniteNumber(value);
+export const isOptionalBoolean = (value) => value === undefined || typeof value === 'boolean';
+export const isCount = (value) => isFiniteNumber(value) && Number.isInteger(value) && value >= 0;
+export const isDateTime = (value) => isString(value) && Number.isFinite(Date.parse(value));
+export const isStringArray = (value) => Array.isArray(value) && value.every(isString);
+export const isCountRecord = (value) => isRecord(value) && Object.values(value).every(isCount);
+export const countTotal = (value) => Object.values(value).reduce((total, count) => total + count, 0);
+export const hasOptionalStrings = (value, keys) => keys.every(key => isOptionalString(value[key]));
+export const hasOptionalNumbers = (value, keys) => keys.every(key => isOptionalFiniteNumber(value[key]));
+export const isBoundedRows = (value, limit, isRow) => {
+    if (!isRecord(value) || !isCount(value.totalCount) || !isCount(value.omittedCount) || !Array.isArray(value.rows))
+        return false;
+    return value.rows.length <= limit && value.rows.every(isRow) && value.totalCount === value.rows.length + value.omittedCount;
+};
+/*
+ * Throwing assertion primitives for exact-shape boundary validators. Each
+ * failure names the offending field path so rejections are diagnosable.
+ */
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+export function asRecord(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be a JSON object.`);
+    return value;
+}
+export function asArray(value, field, nonEmpty = false) {
+    if (!Array.isArray(value) || (nonEmpty && value.length === 0))
+        throw new Error(`${field} must be ${nonEmpty ? 'a non-empty' : 'an'} array.`);
+    return value;
+}
+export function requiredString(value, field) {
+    if (typeof value !== 'string' || value.trim() !== value || value.length === 0)
+        throw new Error(`${field} must be a non-empty trimmed string.`);
+    return value;
+}
+export function requiredEnum(value, values, field) {
+    if (typeof value !== 'string' || !values.includes(value))
+        throw new Error(`${field} is not declared.`);
+    return value;
+}
+export function requiredBoolean(value, field) {
+    if (typeof value !== 'boolean')
+        throw new Error(`${field} must be a boolean.`);
+    return value;
+}
+export function nonNegativeInteger(value, field) {
+    if (!Number.isSafeInteger(value) || Number(value) < 0)
+        throw new Error(`${field} must be a non-negative safe integer.`);
+    return Number(value);
+}
+export function finiteNumber(value, field) {
+    if (!isFiniteNumber(value))
+        throw new Error(`${field} must be a finite number.`);
+    return value;
+}
+export function isoTimestamp(value, field) {
+    const timestamp = requiredString(value, field);
+    if (!ISO_TIMESTAMP_PATTERN.test(timestamp) || Number.isNaN(Date.parse(timestamp)))
+        throw new Error(`${field} must be an ISO UTC timestamp.`);
+    return timestamp;
+}
+export function assertExactKeys(value, allowed, field) {
+    const allowedKeys = new Set(allowed);
+    const unknown = Object.keys(value).filter(key => !allowedKeys.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${field} contains undeclared fields: ${unknown.sort().join(', ')}.`);
+}
+export function assertValue(actual, expected, field) {
+    if (actual !== expected)
+        throw new Error(`${field} must match its exact binding.`);
+}
+export function assertUnique(values, field) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`${field} must not contain duplicates.`);
+}
+export function requiredPublicIdentifier(value, field) {
+    const identifier = requiredString(value, field);
+    if (identifier.includes('/') || identifier.includes('\\') || identifier.includes('://') || identifier.includes('..'))
+        throw new Error(`${field} must not contain a physical path or URI.`);
+    return identifier;
+}
+/** Validates an exact `ArtifactGeneration` identity. */
+export function validateGeneration(value, field) {
+    const generation = asRecord(value, field);
+    assertExactKeys(generation, ['runId', 'generatedAt'], field);
+    return {
+        runId: requiredPublicIdentifier(generation.runId, `${field}.runId`),
+        generatedAt: isoTimestamp(generation.generatedAt, `${field}.generatedAt`),
+    };
+}
+/** Rejects non-JSON values and non-plain objects; `isForbiddenKey` rejects keys at every depth. */
+export function assertPlainJson(value, field, isForbiddenKey = () => false) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${field} must contain only finite JSON numbers.`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertPlainJson(item, `${field}[${index}]`, isForbiddenKey));
+        return;
+    }
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error(`${field} must contain only plain JSON values.`);
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (isForbiddenKey(key))
+            throw new Error(`${field}.${key} is not allowed in a public artifact.`);
+        assertPlainJson(child, `${field}.${key}`, isForbiddenKey);
+    }
+}

package/dist/esm/entries/relationships.js

@@ -1,3 +1,3 @@
-export * from '../aws/portalRelationshipPublicArtifactValidation.js';
-import * as namespace from '../aws/portalRelationshipPublicArtifactValidation.js';
+export * from '../aws/relationships.js';
+import * as namespace from '../aws/relationships.js';
 export default namespace;

package/dist/esm/index.js

@@ -15,12 +15,15 @@ export * from './azure/artifactRunReference.js';
 export * from './azure/billingPlots.js';
 export * from './azure/benefits.js';
 export * from './azure/commitmentsPlanning.js';
+export * from './azure/commitmentsPlanningValidation.js';
 export * from './azure/licensing.js';
 export * from './azure/configs.js';
 export * from './azure/metrics.js';
 export * from './azure/payloads.js';
 export * from './azure/portalArtifacts.js';
 export * from './azure/dataProtection.js';
+export * from './azure/resilienceFacts.js';
+export * from './azure/resilienceFactsValidation.js';
 export * from './azure/prices.js';
 export * from './azure/relationships.js';
 export * from './azure/recommendations.js';
@@ -34,6 +37,8 @@ export * from './azure/resources.js';
 export * from './azure/reports.js';
 export * from './azure/reportEvidence.js';
 export * from './azure/reportEvidenceValidation.js';
+export * from './common/utilizationStories.js';
+export * from './common/utilizationStoriesValidation.js';
 export * from './azure/reportDailySpend.js';
 export * from './azure/reportDailySpendValidation.js';
 export * from './azure/reportSpend.js';

package/dist/esm/index.vite.js

@@ -5,6 +5,7 @@ export * from './azure/budgets.js';
 export * from './azure/billingPlots.js';
 export * from './azure/benefits.js';
 export * from './azure/commitmentsPlanning.js';
+export * from './azure/commitmentsPlanningValidation.js';
 export * from './azure/licensing.js';
 export * from './azure/configs.js';
 export * from './azure/metrics.js';

package/dist/esm/reporting/jobs/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@spottoai/types-package/reporting-jobs`: background report job contracts shared by the API, cloud-engine and
+ * reportworker (types-package/specs/reporting/reporting-scheduler-types.md, Part A).
+ */
+export * from './reportJobSpec.js';
+export * from './reportJobIdentity.js';
+export * from './reportJobMessages.js';
+export * from './reportJobStatus.js';
+export * from './reportJobRow.js';
+export { sha256Hex, SHA256_HEX_PATTERN } from '../shared/reportingDigest.js';
+export { isIanaTimeZone, isIsoUtcTimestamp, isReportEntityId, isReportGuid, isReportJobCompanyId, REPORT_ENTITY_ID_PATTERN, REPORT_JOB_COMPANY_ID_MAX_LENGTH, } from '../shared/reportingIds.js';
+export { normalizeReportTableEntity, REPORT_TABLE_SYSTEM_FIELDS, toReportTableSdkEntity } from '../shared/reportTableEntities.js';
+export { isReportFileName, sanitizeReportingPathSegment } from '../shared/reportingPaths.js';

package/dist/esm/reporting/jobs/reportJobIdentity.js

@@ -0,0 +1,76 @@
+/**
+ * Background report job identity (core/specs/reporting/reporting-scheduler.md, "Report job table").
+ *
+ * `jobId = {reverseTime19}-{reportType}-{scopeHash}` is the `reportjobs` RowKey and the generated report's ID.
+ * The API and cloud-engine must derive it identically, so both use these functions.
+ */
+import { sha256Hex } from '../shared/reportingDigest.js';
+import { isIsoUtcTimestamp, isReportEntityId, isReportGuid, isReportJobCompanyId } from '../shared/reportingIds.js';
+import { isReportJobReportType, normalizeReportSubscriptionIds } from './reportJobSpec.js';
+/** The `recommendationsevents` reverse-time convention: 19 nines minus Unix milliseconds, zero-padded to 19 digits. */
+export const REPORT_JOB_MAX_REVERSE_TIME = BigInt('9999999999999999999');
+/** Latest instant accepted (9999-12-31T23:59:59.999Z). */
+export const REPORT_JOB_MAX_INSTANT_MS = 253402300799999;
+export const REPORT_JOB_ID_PATTERN = /^(\d{19})-(sdm|architecture-assessment)-([0-9a-f]{16})$/;
+export const REPORT_JOB_SCOPE_HASH_PATTERN = /^[0-9a-f]{16}$/;
+/** Strings must be exact UTC ISO timestamps (`toISOString` form), so the result never depends on the host time zone. */
+const toInstantMs = (instant) => {
+    if (typeof instant === 'string' && !isIsoUtcTimestamp(instant))
+        throw new RangeError('Report job instant strings must be UTC ISO timestamps (YYYY-MM-DDTHH:mm:ss.sssZ).');
+    const ms = instant instanceof Date ? instant.getTime() : typeof instant === 'number' ? instant : Date.parse(instant);
+    if (!Number.isInteger(ms) || ms < 0 || ms > REPORT_JOB_MAX_INSTANT_MS)
+        throw new RangeError('Report job instant must be a valid time between 1970 and 9999.');
+    return ms;
+};
+export const buildReverseTime19 = (instant) => (REPORT_JOB_MAX_REVERSE_TIME - BigInt(toInstantMs(instant))).toString().padStart(19, '0');
+/** The instant a reverse time encodes, or `null` when it is not a valid 19-digit reverse time. */
+export const parseReverseTime19 = (value) => {
+    if (typeof value !== 'string' || !/^\d{19}$/.test(value))
+        return null;
+    const ms = REPORT_JOB_MAX_REVERSE_TIME - BigInt(value);
+    if (ms < BigInt(0) || ms > BigInt(REPORT_JOB_MAX_INSTANT_MS))
+        return null;
+    return new Date(Number(ms));
+};
+/** First 16 hex characters of SHA-256 over the sorted, lower-cased subscription IDs joined with `,` (then `|{scheduleId}`). */
+export const buildReportJobScopeHash = async ({ subscriptionIds, scheduleId }) => {
+    if (subscriptionIds.length === 0 || !subscriptionIds.every(id => typeof id === 'string' && isReportGuid(id.trim()))) {
+        throw new Error('Report job scope hash needs at least one valid subscription ID.');
+    }
+    if (scheduleId !== undefined && !isReportEntityId(scheduleId))
+        throw new Error('Report job scope hash: invalid schedule ID.');
+    const preimage = normalizeReportSubscriptionIds(subscriptionIds).join(',') + (scheduleId === undefined ? '' : `|${scheduleId}`);
+    return (await sha256Hex(preimage)).slice(0, 16);
+};
+export const buildReportJobId = ({ instant, reportType, scopeHash }) => {
+    if (!isReportJobReportType(reportType))
+        throw new Error('Report job ID: invalid report type.');
+    if (!REPORT_JOB_SCOPE_HASH_PATTERN.test(scopeHash))
+        throw new Error('Report job ID: invalid scope hash.');
+    return `${buildReverseTime19(instant)}-${reportType}-${scopeHash}`;
+};
+export const parseReportJobId = (jobId) => {
+    if (typeof jobId !== 'string')
+        return null;
+    const match = REPORT_JOB_ID_PATTERN.exec(jobId);
+    if (!match)
+        return null;
+    const instant = parseReverseTime19(match[1]);
+    if (!instant)
+        return null;
+    return { reverseTime19: match[1], instant, reportType: match[2], scopeHash: match[3] };
+};
+export const isReportJobId = (value) => parseReportJobId(value) !== null;
+/** Derives `scopeHash` and `jobId` together. */
+export const deriveReportJobIdentity = async (input) => {
+    const scopeHash = await buildReportJobScopeHash(input);
+    return { jobId: buildReportJobId({ instant: input.instant, reportType: input.reportType, scopeHash }), scopeHash };
+};
+/** Service Bus `MessageId` for `ReportJobRequestedV1`: `report-job:{companyId}:{jobId}`. */
+export const buildReportJobMessageId = (companyId, jobId) => {
+    if (!isReportJobCompanyId(companyId))
+        throw new Error('Report job message ID: invalid company ID.');
+    if (!isReportJobId(jobId))
+        throw new Error('Report job message ID: invalid job ID.');
+    return `report-job:${companyId}:${jobId}`;
+};

package/dist/esm/reporting/jobs/reportJobMessages.js

@@ -0,0 +1,47 @@
+/**
+ * The `reports` queue message (core/specs/reporting/reporting-scheduler.md, "Queue message").
+ *
+ * The message is a pointer only: the worker reads everything else from the `reportjobs` row. Each region has its
+ * own queue, table and worker, so the message carries no region.
+ */
+import { hasExactlyKeys, isBoundedPlainText, isPlainRecord, isReportJobCompanyId } from '../shared/reportingIds.js';
+import { buildReportJobMessageId, isReportJobId } from './reportJobIdentity.js';
+export const REPORT_JOB_REQUESTED_MESSAGE_TYPE = 'report-job.requested';
+/** Upper bound for the serialised message body. */
+export const REPORT_JOB_REQUESTED_MAX_BYTES = 4 * 1024;
+const MESSAGE_KEYS = ['schemaVersion', 'messageType', 'companyId', 'jobId', 'correlationId'];
+/** Strict guard: exact keys, valid identifiers, bounded size. Never throws. */
+export const isReportJobRequestedV1 = (value) => {
+    try {
+        if (!isPlainRecord(value) || !hasExactlyKeys(value, MESSAGE_KEYS))
+            return false;
+        return (value.schemaVersion === 1 &&
+            value.messageType === REPORT_JOB_REQUESTED_MESSAGE_TYPE &&
+            isReportJobCompanyId(value.companyId) &&
+            isReportJobId(value.jobId) &&
+            isBoundedPlainText(value.correlationId, 128) &&
+            JSON.stringify(value).length <= REPORT_JOB_REQUESTED_MAX_BYTES);
+    }
+    catch {
+        return false;
+    }
+};
+export const createReportJobRequestedV1 = ({ companyId, jobId, correlationId }) => {
+    const message = {
+        schemaVersion: 1,
+        messageType: REPORT_JOB_REQUESTED_MESSAGE_TYPE,
+        companyId,
+        jobId,
+        correlationId: correlationId ?? jobId,
+    };
+    if (!isReportJobRequestedV1(message))
+        throw new Error('Invalid report job requested message.');
+    return message;
+};
+/** Service Bus properties for a `ReportJobRequestedV1` send: the shared MessageId drives duplicate detection. */
+export const buildReportJobRequestedBrokerProperties = (message) => ({
+    messageId: buildReportJobMessageId(message.companyId, message.jobId),
+    correlationId: message.jobId,
+    contentType: 'application/json',
+    subject: REPORT_JOB_REQUESTED_MESSAGE_TYPE,
+});

package/dist/esm/reporting/jobs/reportJobRow.js

@@ -0,0 +1,264 @@
+/**
+ * The `reportjobs` row (core/specs/reporting/reporting-scheduler.md, "Report job table").
+ *
+ * PartitionKey = companyId, RowKey = jobId. Three writers own disjoint field groups and merge with ETag
+ * compare-and-swap: the producer (insert only), reportworker and, from phase 6, cloud-engine's notifier.
+ * The row carries no region (each region has its own table, queue and worker) and no time zone (reportworker uses
+ * the company's `preferredTimezone`, else UTC). The row never holds e-mail addresses, document content, source data, Blob paths or credentials.
+ */
+import { sha256Hex, SHA256_HEX_PATTERN } from '../shared/reportingDigest.js';
+import { isReportFileName } from '../shared/reportingPaths.js';
+import { hasExactlyKeys, isBoundedPlainText, isIsoUtcTimestamp, isPlainRecord, isReportEntityId, isReportJobCompanyId, utf8ByteLength, } from '../shared/reportingIds.js';
+import { normalizeReportTableEntity } from '../shared/reportTableEntities.js';
+import { buildReportJobScopeHash, deriveReportJobIdentity, parseReportJobId } from './reportJobIdentity.js';
+import { parseReportJobRequestJson, REPORT_JOB_SPEC_MAX_BYTES, serializeReportJobSpecV1, } from './reportJobSpec.js';
+import { isReportJobFailureCode, isReportJobFailureStage, isReportJobNotificationStatus, isReportJobStatus, REPORT_JOB_FAILURE_STAGE_BY_CODE, } from './reportJobStatus.js';
+export const REPORT_JOB_ROW_SCHEMA_VERSION = 1;
+export const REPORT_JOB_TRIGGERS = ['api', 'schedule'];
+/** UTF-8 byte limit of `sourceCoverageSummary` (a JSON object). */
+export const REPORT_JOB_COVERAGE_SUMMARY_MAX_BYTES = 8 * 1024;
+export const REPORT_JOB_PRODUCER_FIELDS = [
+    'PartitionKey',
+    'RowKey',
+    'schemaVersion',
+    'jobId',
+    'companyId',
+    'reportType',
+    'trigger',
+    'scheduleId',
+    'definitionRevision',
+    'scheduledForUtc',
+    'requestedAtUtc',
+    'requestedByUserId',
+    'coalescedOccurrenceCount',
+    'requestJson',
+    'requestSha256',
+    'fileName',
+    'notificationPolicyId',
+];
+export const REPORT_JOB_WORKER_FIELDS = [
+    'status',
+    'attemptCount',
+    'leaseOwner',
+    'leaseExpiresAtUtc',
+    'startedAtUtc',
+    'lastAttemptAtUtc',
+    'sourceObservedAtUtc',
+    'sourceSnapshotSha256',
+    'sourceCoverageSummary',
+    'generatedAtUtc',
+    'artifactContentSha256',
+    'artifactBytes',
+    'completedAtUtc',
+    'failureStage',
+    'failureCode',
+    'lastTransientErrorCode',
+];
+export const REPORT_JOB_NOTIFICATION_FIELDS = ['notificationStatus'];
+const REQUIRED_FIELDS = [
+    'PartitionKey',
+    'RowKey',
+    'schemaVersion',
+    'jobId',
+    'companyId',
+    'reportType',
+    'trigger',
+    'requestedAtUtc',
+    'requestJson',
+    'requestSha256',
+    'fileName',
+    'status',
+    'attemptCount',
+    'notificationStatus',
+];
+const OPTIONAL_FIELDS = [...REPORT_JOB_PRODUCER_FIELDS, ...REPORT_JOB_WORKER_FIELDS, ...REPORT_JOB_NOTIFICATION_FIELDS].filter(field => !REQUIRED_FIELDS.includes(field));
+/** Statuses reached only after the source snapshot is durable. */
+const SNAPSHOT_STATUSES = ['source-ready', 'generated', 'completed', 'completed-with-notification-errors'];
+/** Statuses reached only after the artifact is durable. */
+const ARTIFACT_STATUSES = ['generated', 'completed', 'completed-with-notification-errors'];
+const isCount = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 2147483647;
+const isSha = (value) => typeof value === 'string' && SHA256_HEX_PATTERN.test(value);
+const isText = (limit) => (value) => isBoundedPlainText(value, limit);
+const isOptional = (value, check) => value === undefined || check(value);
+const isCoverageSummary = (value) => {
+    if (typeof value !== 'string' || utf8ByteLength(value) > REPORT_JOB_COVERAGE_SUMMARY_MAX_BYTES)
+        return false;
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === 'object' && parsed !== null;
+    }
+    catch {
+        return false;
+    }
+};
+/** `row` is already normalised (REST key casing, no system properties, no null values). */
+const validateShape = (row, errors) => {
+    const check = (field, ok) => {
+        if (!ok)
+            errors.push(`${field}: invalid`);
+    };
+    if (!hasExactlyKeys(row, REQUIRED_FIELDS, OPTIONAL_FIELDS)) {
+        const unknown = Object.keys(row).filter(key => !REQUIRED_FIELDS.includes(key) && !OPTIONAL_FIELDS.includes(key));
+        const missing = REQUIRED_FIELDS.filter(key => row[key] === undefined);
+        if (unknown.length > 0)
+            errors.push(`row: unknown fields ${unknown.join(', ')}`);
+        if (missing.length > 0)
+            errors.push(`row: missing fields ${missing.join(', ')}`);
+    }
+    check('companyId', isReportJobCompanyId(row.companyId) && row.PartitionKey === row.companyId);
+    const parsedId = parseReportJobId(row.jobId);
+    check('jobId', parsedId !== null && row.RowKey === row.jobId);
+    check('reportType', parsedId !== null && row.reportType === parsedId.reportType);
+    check('trigger', row.trigger === 'api' || row.trigger === 'schedule');
+    check('requestedAtUtc', isIsoUtcTimestamp(row.requestedAtUtc));
+    check('requestJson', typeof row.requestJson === 'string' && utf8ByteLength(row.requestJson) <= REPORT_JOB_SPEC_MAX_BYTES);
+    check('requestSha256', isSha(row.requestSha256));
+    check('fileName', isReportFileName(row.fileName));
+    // Requesters are identified by user ID, never by e-mail address.
+    check('requestedByUserId', isOptional(row.requestedByUserId, value => isText(128)(value) && !value.includes('@')));
+    check('notificationPolicyId', isOptional(row.notificationPolicyId, isReportEntityId));
+    check('coalescedOccurrenceCount', isOptional(row.coalescedOccurrenceCount, value => isCount(value) && value >= 1));
+    if (row.trigger === 'schedule') {
+        check('scheduleId', isReportEntityId(row.scheduleId));
+        check('definitionRevision', isCount(row.definitionRevision) && row.definitionRevision >= 1);
+        check('scheduledForUtc', isIsoUtcTimestamp(row.scheduledForUtc));
+    }
+    else {
+        check('scheduleId', row.scheduleId === undefined);
+        check('definitionRevision', row.definitionRevision === undefined);
+        check('scheduledForUtc', row.scheduledForUtc === undefined);
+        check('coalescedOccurrenceCount', row.coalescedOccurrenceCount === undefined);
+    }
+    const instant = row.trigger === 'schedule' ? row.scheduledForUtc : row.requestedAtUtc;
+    check('jobId', parsedId !== null && typeof instant === 'string' && parsedId.instant.toISOString() === instant);
+    check('status', isReportJobStatus(row.status));
+    check('attemptCount', isCount(row.attemptCount));
+    check('notificationStatus', isReportJobNotificationStatus(row.notificationStatus));
+    for (const field of ['leaseExpiresAtUtc', 'startedAtUtc', 'lastAttemptAtUtc', 'sourceObservedAtUtc', 'generatedAtUtc', 'completedAtUtc']) {
+        check(field, isOptional(row[field], isIsoUtcTimestamp));
+    }
+    check('leaseOwner', isOptional(row.leaseOwner, isText(256)));
+    check('sourceSnapshotSha256', isOptional(row.sourceSnapshotSha256, isSha));
+    check('artifactContentSha256', isOptional(row.artifactContentSha256, isSha));
+    check('artifactBytes', isOptional(row.artifactBytes, value => isCount(value) && value >= 1));
+    check('sourceCoverageSummary', isOptional(row.sourceCoverageSummary, isCoverageSummary));
+    check('failureStage', isOptional(row.failureStage, isReportJobFailureStage));
+    check('failureCode', isOptional(row.failureCode, isReportJobFailureCode));
+    check('lastTransientErrorCode', isOptional(row.lastTransientErrorCode, isText(128)));
+    // Cross-field rules: the status milestone and the fields that prove it agree.
+    if (!isReportJobStatus(row.status))
+        return;
+    const status = row.status;
+    if (status === 'failed') {
+        check('failureCode', isReportJobFailureCode(row.failureCode));
+        check('failureStage', isReportJobFailureStage(row.failureStage));
+        if (isReportJobFailureCode(row.failureCode) && isReportJobFailureStage(row.failureStage)) {
+            const expected = REPORT_JOB_FAILURE_STAGE_BY_CODE[row.failureCode];
+            check('failureStage', expected === null || expected === row.failureStage);
+        }
+    }
+    else {
+        check('failureCode', row.failureCode === undefined);
+        check('failureStage', row.failureStage === undefined);
+    }
+    if (SNAPSHOT_STATUSES.includes(status)) {
+        check('sourceSnapshotSha256', isSha(row.sourceSnapshotSha256));
+        check('sourceObservedAtUtc', isIsoUtcTimestamp(row.sourceObservedAtUtc));
+    }
+    if (ARTIFACT_STATUSES.includes(status)) {
+        check('artifactContentSha256', isSha(row.artifactContentSha256));
+        check('artifactBytes', isCount(row.artifactBytes) && row.artifactBytes >= 1);
+        check('generatedAtUtc', isIsoUtcTimestamp(row.generatedAtUtc));
+    }
+    if (status === 'completed' || status === 'completed-with-notification-errors')
+        check('completedAtUtc', isIsoUtcTimestamp(row.completedAtUtc));
+    if (status === 'accepted')
+        check('attemptCount', row.attemptCount === 0);
+};
+/**
+ * Validates a stored row and its request. Accepts REST (`PartitionKey`) and `@azure/data-tables` (`partitionKey`)
+ * key casing and ignores Table system properties. Checks keys against the body, the job ID against the trigger's
+ * instant, status against the fields that prove it, the report type and scope hash against the spec, the request's
+ * canonical form and `requestSha256`. Returns the row in REST casing. Never throws.
+ */
+export const parseReportJobRowV1 = async (entity) => {
+    try {
+        if (!isPlainRecord(entity))
+            return { ok: false, code: 'request-invalid', errors: ['row: must be an object'] };
+        const normalized = normalizeReportTableEntity(entity);
+        if (normalized.schemaVersion !== REPORT_JOB_ROW_SCHEMA_VERSION) {
+            return { ok: false, code: 'unsupported-schema-version', errors: ['schemaVersion: unsupported'] };
+        }
+        const errors = [];
+        validateShape(normalized, errors);
+        if (errors.length > 0)
+            return { ok: false, code: 'request-invalid', errors: Array.from(new Set(errors)) };
+        const row = normalized;
+        if ((await sha256Hex(row.requestJson)) !== row.requestSha256) {
+            return { ok: false, code: 'request-hash-mismatch', errors: ['requestSha256: does not match requestJson'] };
+        }
+        const spec = parseReportJobRequestJson(row.requestJson);
+        if (!spec.ok)
+            return { ok: false, code: 'request-invalid', errors: spec.errors };
+        if (spec.value.reportType !== row.reportType)
+            return { ok: false, code: 'request-invalid', errors: ['reportType: does not match the request'] };
+        const scopeHash = await buildReportJobScopeHash({
+            subscriptionIds: spec.value.scope.subscriptionIds,
+            scheduleId: row.trigger === 'schedule' ? row.scheduleId : undefined,
+        });
+        if (parseReportJobId(row.jobId)?.scopeHash !== scopeHash) {
+            return { ok: false, code: 'request-invalid', errors: ['jobId: scope hash does not match the request'] };
+        }
+        return { ok: true, row, spec: spec.value };
+    }
+    catch {
+        return { ok: false, code: 'request-invalid', errors: ['row: unreadable'] };
+    }
+};
+/**
+ * Builds the row a producer inserts (status `accepted`, attempt 0, notification `none`), with the job ID derived
+ * from the trigger's instant and the request. The result is validated with `parseReportJobRowV1`; invalid input throws.
+ */
+export const buildReportJobRowV1 = async (input) => {
+    const requestJson = serializeReportJobSpecV1(input.spec);
+    const spec = parseReportJobRequestJson(requestJson);
+    if (!spec.ok)
+        throw new Error(`Invalid report job spec: ${spec.errors.join('; ')}`);
+    const schedule = input.trigger === 'schedule' ? input : undefined;
+    const { jobId } = await deriveReportJobIdentity({
+        instant: schedule ? schedule.scheduledForUtc : input.requestedAtUtc,
+        reportType: spec.value.reportType,
+        subscriptionIds: spec.value.scope.subscriptionIds,
+        scheduleId: schedule?.scheduleId,
+    });
+    const row = {
+        PartitionKey: input.companyId,
+        RowKey: jobId,
+        schemaVersion: 1,
+        jobId,
+        companyId: input.companyId,
+        reportType: spec.value.reportType,
+        trigger: input.trigger,
+        ...(schedule
+            ? {
+                scheduleId: schedule.scheduleId,
+                definitionRevision: schedule.definitionRevision,
+                scheduledForUtc: schedule.scheduledForUtc,
+                ...(schedule.coalescedOccurrenceCount === undefined ? {} : { coalescedOccurrenceCount: schedule.coalescedOccurrenceCount }),
+            }
+            : {}),
+        requestedAtUtc: input.requestedAtUtc,
+        ...(input.requestedByUserId === undefined ? {} : { requestedByUserId: input.requestedByUserId }),
+        requestJson,
+        requestSha256: await sha256Hex(requestJson),
+        fileName: input.fileName,
+        ...(input.notificationPolicyId === undefined ? {} : { notificationPolicyId: input.notificationPolicyId }),
+        status: 'accepted',
+        attemptCount: 0,
+        notificationStatus: 'none',
+    };
+    const parsed = await parseReportJobRowV1(row);
+    if (!parsed.ok)
+        throw new Error(`Invalid report job row: ${parsed.errors.join('; ')}`);
+    return row;
+};