@researchdatabox/redbox-core 5.0.4 → 5.1.0-beta.12568

package/dist/RecordConcurrencyObservability.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordConcurrencyMetricLabels = recordConcurrencyMetricLabels;
+exports.emitRecordConcurrencyEvent = emitRecordConcurrencyEvent;
+const api_1 = require("@opentelemetry/api");
+const sails_ng_common_1 = require("@researchdatabox/sails-ng-common");
+const conflictCodes = new Set(sails_ng_common_1.RECORD_CONCURRENCY_PROBLEM_CODES);
+const eventKinds = new Set(['save-outcome', 'internal-retry', 'lifecycle-recovery']);
+const routeFamilies = new Set(['browser', 'api', 'internal']);
+const writeKinds = new Set(['create', 'update', 'transition', 'delete', 'restore', 'purge']);
+const phases = new Set(['pre-save', 'persistence', 'attachments', 'post-save', 'response', 'transport']);
+const outcomes = new Set([
+    'saved',
+    'saved-with-warnings',
+    'not-saved',
+    'unknown',
+    'attempted',
+    'exhausted',
+    'completed',
+    'cancelled',
+    'retained',
+]);
+const preconditions = new Set(['not-applicable', 'missing', 'matching', 'stale']);
+const modes = new Set(sails_ng_common_1.RECORD_CONCURRENT_MODIFICATION_MODES);
+const resolutions = new Set(sails_ng_common_1.RECORD_CONCURRENCY_RESOLUTIONS);
+const problemKinds = new Set(['validation', 'processing', 'authorization', 'conflict', 'system', 'network']);
+const safeLogReferencePattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function boundedMetricLabel(value, allowed, fallback) {
+    return typeof value === 'string' && allowed.has(value) ? value : fallback;
+}
+function boundedLogReference(value, fallback) {
+    return typeof value === 'string' && safeLogReferencePattern.test(value.trim()) ? value.trim() : fallback;
+}
+function boundedRevision(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : undefined;
+}
+const meter = api_1.metrics.getMeter('redbox.record-concurrency');
+const preconditionCounter = meter.createCounter('record_concurrency_precondition_total', {
+    description: 'Record mutation preconditions by bounded policy and result.',
+    unit: '{precondition}',
+});
+const conflictCounter = meter.createCounter('record_concurrency_conflict_total', {
+    description: 'Certified record concurrency conflicts by safe code and write kind.',
+    unit: '{conflict}',
+});
+const resolutionCounter = meter.createCounter('record_concurrency_resolution_total', {
+    description: 'Record mutation results by normalized concurrency resolution.',
+    unit: '{resolution}',
+});
+const internalRetryCounter = meter.createCounter('record_concurrency_internal_retry_total', {
+    description: 'Bounded recomputable internal mutation retries.',
+    unit: '{retry}',
+});
+const lifecycleRecoveryCounter = meter.createCounter('record_concurrency_lifecycle_recovery_total', {
+    description: 'Lifecycle recovery results by operation and bounded outcome.',
+    unit: '{recovery}',
+});
+/** Low-cardinality metric labels. Identifiers and revisions are deliberately impossible to add here. */
+function recordConcurrencyMetricLabels(event) {
+    return {
+        event_kind: boundedMetricLabel(event.kind, eventKinds, 'other'),
+        route_family: boundedMetricLabel(event.routeFamily, routeFamilies, 'other'),
+        write_kind: boundedMetricLabel(event.writeKind, writeKinds, 'other'),
+        phase: boundedMetricLabel(event.phase, phases, 'other'),
+        outcome: boundedMetricLabel(event.outcome, outcomes, 'other'),
+        precondition: boundedMetricLabel(event.precondition, preconditions, 'other'),
+        mode: event.mode === undefined ? 'unavailable' : boundedMetricLabel(event.mode, modes, 'other'),
+        problem_code: event.problemCode ? (conflictCodes.has(event.problemCode) ? event.problemCode : 'other') : 'none',
+        resolution: event.resolution === undefined ? 'direct' : boundedMetricLabel(event.resolution, resolutions, 'other'),
+    };
+}
+/**
+ * Emit one value-free structured event and its bounded counters.
+ *
+ * Revision coordinates are bounded integers, and record type is log-only
+ * because deployments may have an unbounded extension set. Identifiers are
+ * deliberately absent, these values are never copied to metric labels, and
+ * this contract has no fields capable of carrying record values, headers,
+ * paths, or exceptions.
+ */
+function emitRecordConcurrencyEvent(event, logger = sails.log) {
+    const expectedRevision = boundedRevision(event.expectedRevision);
+    const currentRevision = boundedRevision(event.currentRevision);
+    const safeEvent = Object.freeze({
+        kind: boundedMetricLabel(event.kind, eventKinds, 'other'),
+        routeFamily: boundedMetricLabel(event.routeFamily, routeFamilies, 'other'),
+        writeKind: boundedMetricLabel(event.writeKind, writeKinds, 'other'),
+        ...(event.recordType === undefined ? {} : { recordType: boundedLogReference(event.recordType, 'unavailable') }),
+        phase: boundedMetricLabel(event.phase, phases, 'other'),
+        outcome: boundedMetricLabel(event.outcome, outcomes, 'other'),
+        ...(event.mode === undefined ? {} : { mode: boundedMetricLabel(event.mode, modes, 'other') }),
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
+        ...(currentRevision === undefined ? {} : { currentRevision }),
+        precondition: boundedMetricLabel(event.precondition, preconditions, 'other'),
+        ...(event.problemKind === undefined
+            ? {}
+            : { problemKind: boundedMetricLabel(event.problemKind, problemKinds, 'other') }),
+        ...(event.problemCode === undefined
+            ? {}
+            : { problemCode: conflictCodes.has(event.problemCode) ? event.problemCode : 'other' }),
+        ...(event.resolution === undefined
+            ? {}
+            : { resolution: boundedMetricLabel(event.resolution, resolutions, 'other') }),
+        ...(event.errorType === undefined ? {} : { errorType: boundedLogReference(event.errorType, 'other') }),
+    });
+    const logDetails = Object.freeze({ event: 'record_concurrency_event', ...safeEvent });
+    const isWarning = Boolean(safeEvent.errorType || safeEvent.problemKind || safeEvent.problemCode) ||
+        safeEvent.outcome === 'not-saved' ||
+        safeEvent.outcome === 'unknown' ||
+        safeEvent.outcome === 'saved-with-warnings' ||
+        safeEvent.outcome === 'exhausted' ||
+        safeEvent.outcome === 'retained';
+    if (isWarning) {
+        logger.warn('record_concurrency_event', logDetails);
+    }
+    else {
+        logger.info('record_concurrency_event', logDetails);
+    }
+    const labels = recordConcurrencyMetricLabels(event);
+    if (safeEvent.kind === 'save-outcome') {
+        if (safeEvent.writeKind !== 'create')
+            preconditionCounter.add(1, labels);
+        if (safeEvent.problemCode && conflictCodes.has(safeEvent.problemCode))
+            conflictCounter.add(1, labels);
+        if (safeEvent.resolution)
+            resolutionCounter.add(1, labels);
+    }
+    else if (safeEvent.kind === 'internal-retry') {
+        internalRetryCounter.add(1, labels);
+    }
+    else if (safeEvent.kind === 'lifecycle-recovery') {
+        lifecycleRecoveryCounter.add(1, labels);
+    }
+    return safeEvent;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmVjb3JkQ29uY3VycmVuY3lPYnNlcnZhYmlsaXR5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL1JlY29yZENvbmN1cnJlbmN5T2JzZXJ2YWJpbGl0eS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQTRHQSxzRUFZQztBQVdELGdFQW9EQztBQXZMRCw0Q0FBOEQ7QUFDOUQsc0VBUzBDO0FBeUMxQyxNQUFNLGFBQWEsR0FBRyxJQUFJLEdBQUcsQ0FBUyxrREFBZ0MsQ0FBQyxDQUFDO0FBQ3hFLE1BQU0sVUFBVSxHQUFHLElBQUksR0FBRyxDQUFTLENBQUMsY0FBYyxFQUFFLGdCQUFnQixFQUFFLG9CQUFvQixDQUFDLENBQUMsQ0FBQztBQUM3RixNQUFNLGFBQWEsR0FBRyxJQUFJLEdBQUcsQ0FBUyxDQUFDLFNBQVMsRUFBRSxLQUFLLEVBQUUsVUFBVSxDQUFDLENBQUMsQ0FBQztBQUN0RSxNQUFNLFVBQVUsR0FBRyxJQUFJLEdBQUcsQ0FBUyxDQUFDLFFBQVEsRUFBRSxRQUFRLEVBQUUsWUFBWSxFQUFFLFFBQVEsRUFBRSxTQUFTLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQztBQUNyRyxNQUFNLE1BQU0sR0FBRyxJQUFJLEdBQUcsQ0FBUyxDQUFDLFVBQVUsRUFBRSxhQUFhLEVBQUUsYUFBYSxFQUFFLFdBQVcsRUFBRSxVQUFVLEVBQUUsV0FBVyxDQUFDLENBQUMsQ0FBQztBQUNqSCxNQUFNLFFBQVEsR0FBRyxJQUFJLEdBQUcsQ0FBUztJQUMvQixPQUFPO0lBQ1AscUJBQXFCO0lBQ3JCLFdBQVc7SUFDWCxTQUFTO0lBQ1QsV0FBVztJQUNYLFdBQVc7SUFDWCxXQUFXO0lBQ1gsV0FBVztJQUNYLFVBQVU7Q0FDWCxDQUFDLENBQUM7QUFDSCxNQUFNLGFBQWEsR0FBRyxJQUFJLEdBQUcsQ0FBUyxDQUFDLGdCQUFnQixFQUFFLFNBQVMsRUFBRSxVQUFVLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQztBQUMxRixNQUFNLEtBQUssR0FB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

package/dist/RecordEntityTag.d.ts

@@ -0,0 +1,31 @@
+import { type RecordEntityTag } from '@researchdatabox/sails-ng-common';
+export type { RecordEntityTag } from '@researchdatabox/sails-ng-common';
+export type RecordEntityTagParseFailureReason = 'missing' | 'malformed' | 'too-long' | 'multiple' | 'weak' | 'wildcard' | 'record-mismatch';
+export interface ParsedRecordEntityTag {
+    readonly entityTag: RecordEntityTag;
+    readonly expectedRevision: number;
+}
+export type RecordEntityTagParseResult = {
+    readonly valid: true;
+    readonly value: ParsedRecordEntityTag;
+} | {
+    readonly valid: false;
+    readonly reason: RecordEntityTagParseFailureReason;
+};
+/**
+ * Format the sole record entity-tag representation. Callers must treat the
+ * returned quoted value as opaque and must never derive it from the numeric
+ * revision on the client.
+ */
+export declare function formatRecordEntityTag(recordOid: string, revision: number): RecordEntityTag;
+/**
+ * Parse one exact `If-Match` tag for a known record. Arrays, comma-joined
+ * lists, weak validators, wildcards, malformed values, and tags bound to
+ * another OID are all rejected, and no raw header text is returned or logged.
+ *
+ * An old but well-formed tag for the same record parses successfully: deciding
+ * that it is stale belongs to the policy and compare-and-set boundary, not to
+ * request parsing.
+ */
+export declare function parseRecordEntityTag(value: unknown, recordOid: string): RecordEntityTagParseResult;
+//# sourceMappingURL=RecordEntityTag.d.ts.map

package/dist/RecordEntityTag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordEntityTag.d.ts","sourceRoot":"","sources":["../src/RecordEntityTag.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE,MAAM,MAAM,iCAAiC,GACzC,SAAS,GACT,WAAW,GACX,UAAU,GACV,UAAU,GACV,MAAM,GACN,UAAU,GACV,iBAAiB,CAAC;AAEtB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAA;CAAE,CAAC;AA8BlF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAU1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,0BAA0B,CA+ClG"}

package/dist/RecordEntityTag.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRecordEntityTag = formatRecordEntityTag;
+exports.parseRecordEntityTag = parseRecordEntityTag;
+const node_crypto_1 = require("node:crypto");
+const sails_ng_common_1 = require("@researchdatabox/sails-ng-common");
+/**
+ * The record OID is server-supplied route context, not client input, so an
+ * unusable value is a programming error rather than a request-contract error.
+ */
+function assertRecordOid(recordOid) {
+    if (typeof recordOid !== 'string' ||
+        recordOid.length === 0 ||
+        recordOid.length > sails_ng_common_1.RECORD_ENTITY_TAG_RECORD_ID_MAX_LENGTH) {
+        throw new TypeError('Record OID must be a non-empty bounded string.');
+    }
+}
+/**
+ * Bind identity and revision into a fixed-width payload. The digest is an
+ * unkeyed hash: it makes a tag from another record fail to match and keeps the
+ * tag bounded regardless of OID length. It is not a signature and carries no
+ * authorization.
+ */
+function identityDigest(recordOid, revision) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(`${sails_ng_common_1.RECORD_ENTITY_TAG_VERSION}\0${recordOid.length}\0`, 'utf8')
+        .update(recordOid, 'utf8')
+        .update(`\0${revision}`, 'utf8')
+        .digest('base64url');
+}
+/**
+ * Format the sole record entity-tag representation. Callers must treat the
+ * returned quoted value as opaque and must never derive it from the numeric
+ * revision on the client.
+ */
+function formatRecordEntityTag(recordOid, revision) {
+    assertRecordOid(recordOid);
+    if (!(0, sails_ng_common_1.isRecordRevision)(revision)) {
+        throw new TypeError('Record revision must be a non-negative safe integer.');
+    }
+    const entityTag = `"${sails_ng_common_1.RECORD_ENTITY_TAG_VERSION}.${revision}.${identityDigest(recordOid, revision)}"`;
+    if (!(0, sails_ng_common_1.isRecordEntityTag)(entityTag)) {
+        throw new Error('Generated record entity tag did not satisfy the shared contract.');
+    }
+    return entityTag;
+}
+/**
+ * Parse one exact `If-Match` tag for a known record. Arrays, comma-joined
+ * lists, weak validators, wildcards, malformed values, and tags bound to
+ * another OID are all rejected, and no raw header text is returned or logged.
+ *
+ * An old but well-formed tag for the same record parses successfully: deciding
+ * that it is stale belongs to the policy and compare-and-set boundary, not to
+ * request parsing.
+ */
+function parseRecordEntityTag(value, recordOid) {
+    assertRecordOid(recordOid);
+    if (value === undefined || value === null) {
+        return { valid: false, reason: 'missing' };
+    }
+    if (Array.isArray(value)) {
+        return { valid: false, reason: 'multiple' };
+    }
+    if (typeof value !== 'string') {
+        return { valid: false, reason: 'malformed' };
+    }
+    // Bound the untrusted header before any further work.
+    if (value.length > sails_ng_common_1.RECORD_ENTITY_TAG_MAX_LENGTH) {
+        return { valid: false, reason: 'too-long' };
+    }
+    const normalized = value.trim();
+    // Once a header field is present, an empty value is malformed. Only the
+    // absence of the field is a missing precondition.
+    if (normalized.length === 0) {
+        return { valid: false, reason: 'malformed' };
+    }
+    if (normalized === '*') {
+        return { valid: false, reason: 'wildcard' };
+    }
+    if (/^W\//i.test(normalized)) {
+        return { valid: false, reason: 'weak' };
+    }
+    if (normalized.includes(',')) {
+        return { valid: false, reason: 'multiple' };
+    }
+    const match = sails_ng_common_1.RECORD_ENTITY_TAG_PATTERN.exec(normalized);
+    if (!match) {
+        return { valid: false, reason: 'malformed' };
+    }
+    const expectedRevision = Number(match[1]);
+    if (!(0, sails_ng_common_1.isRecordRevision)(expectedRevision)) {
+        return { valid: false, reason: 'malformed' };
+    }
+    // Recomputing the whole tag proves the digest binds this OID and revision.
+    const expectedTag = formatRecordEntityTag(recordOid, expectedRevision);
+    if (normalized !== expectedTag) {
+        return { valid: false, reason: 'record-mismatch' };
+    }
+    return { valid: true, value: { entityTag: expectedTag, expectedRevision } };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmVjb3JkRW50aXR5VGFnLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL1JlY29yZEVudGl0eVRhZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQWdFQSxzREFVQztBQVdELG9EQStDQztBQXBJRCw2Q0FBeUM7QUFDekMsc0VBUTBDO0FBc0IxQzs7O0dBR0c7QUFDSCxTQUFTLGVBQWUsQ0FBQyxTQUFpQjtJQUN4QyxJQUNFLE9BQU8sU0FBUyxLQUFLLFFBQVE7UUFDN0IsU0FBUyxDQUFDLE1BQU0sS0FBSyxDQUFDO1FBQ3RCLFNBQVMsQ0FBQyxNQUFNLEdBQUcsd0RBQXNDLEVBQ3pELENBQUM7UUFDRCxNQUFNLElBQUksU0FBUyxDQUFDLGdEQUFnRCxDQUFDLENBQUM7SUFDeEUsQ0FBQztBQUNILENBQUM7QUFFRDs7Ozs7R0FLRztBQUNILFNBQVMsY0FBYyxDQUFDLFNBQWlCLEVBQUUsUUFBZ0I7SUFDekQsT0FBTyxJQUFBLHdCQUFVLEVBQUMsUUFBUSxDQUFDO1NBQ3hCLE1BQU0sQ0FBQyxHQUFHLDJDQUF5QixLQUFLLFNBQVMsQ0FBQyxNQUFNLElBQUksRUFBRSxNQUFNLENBQUM7U0FDckUsTUFBTSxDQUFDLFNBQVMsRUFBRSxNQUFNLENBQUM7U0FDekIsTUFBTSxDQUFDLEtBQUssUUFBUSxFQUFFLEVBQUUsTUFBTSxDQUFDO1NBQy9CLE1BQU0sQ0FBQyxXQUFXLENBQUMsQ0FBQztBQUN6QixDQUFDO0FBRUQ7Ozs7R0FJRztBQUNILFNBQWdCLHFCQUFxQixDQUFDLFNBQWlCLEVBQUUsUUFBZ0I7SUFDdkUsZUFBZSxDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQzNCLElBQUksQ0FBQyxJQUFBLGtDQUFnQixFQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUM7UUFDaEMsTUFBTSxJQUFJLFNBQVMsQ0FBQyxzREFBc0QsQ0FBQyxDQUFDO0lBQzlFLENBQUM7SUFDRCxNQUFNLFNBQVMsR0FBRyxJQUFJLDJDQUF5QixJQUFJLFFBQVEsSUFBSSxj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

package/dist/RecordFormFingerprint.d.ts

@@ -0,0 +1,7 @@
+import { type RecordFormFingerprint } from '@researchdatabox/sails-ng-common';
+/**
+ * Build a stable, bounded fingerprint for an authoritative form contract.
+ * Accessors are never invoked and the serialized contract is never retained.
+ */
+export declare function formatRecordFormFingerprint(value: unknown): RecordFormFingerprint | undefined;
+//# sourceMappingURL=RecordFormFingerprint.d.ts.map

package/dist/RecordFormFingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordFormFingerprint.d.ts","sourceRoot":"","sources":["../src/RecordFormFingerprint.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAKvG;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAuF7F"}

package/dist/RecordFormFingerprint.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRecordFormFingerprint = formatRecordFormFingerprint;
+const node_crypto_1 = require("node:crypto");
+const sails_ng_common_1 = require("@researchdatabox/sails-ng-common");
+const RECORD_FORM_FINGERPRINT_MAX_BYTES = 1_048_576;
+const RECORD_FORM_FINGERPRINT_MAX_NODES = 50_000;
+/**
+ * Build a stable, bounded fingerprint for an authoritative form contract.
+ * Accessors are never invoked and the serialized contract is never retained.
+ */
+function formatRecordFormFingerprint(value) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    const seen = new WeakSet();
+    let bytes = 0;
+    let nodes = 0;
+    let bounded = true;
+    const append = (part) => {
+        if (!bounded)
+            return;
+        const size = Buffer.byteLength(part);
+        if (bytes + size > RECORD_FORM_FINGERPRINT_MAX_BYTES) {
+            bounded = false;
+            return;
+        }
+        bytes += size;
+        hash.update(part);
+    };
+    const walk = (item) => {
+        nodes += 1;
+        if (nodes > RECORD_FORM_FINGERPRINT_MAX_NODES) {
+            bounded = false;
+            return;
+        }
+        if (item === null || typeof item === 'boolean' || typeof item === 'string') {
+            append(JSON.stringify(item));
+            return;
+        }
+        if (typeof item === 'number') {
+            append(Number.isFinite(item) ? JSON.stringify(item) : JSON.stringify(String(item)));
+            return;
+        }
+        if (typeof item === 'undefined') {
+            append('"[undefined]"');
+            return;
+        }
+        if (typeof item === 'function') {
+            append(JSON.stringify(`[function:${Function.prototype.toString.call(item)}]`));
+            return;
+        }
+        if (typeof item !== 'object') {
+            append(JSON.stringify(String(item)));
+            return;
+        }
+        if (seen.has(item)) {
+            append('"[circular]"');
+            return;
+        }
+        seen.add(item);
+        try {
+            const descriptors = Object.getOwnPropertyDescriptors(item);
+            if (Array.isArray(item)) {
+                append('[');
+                for (let index = 0; index < item.length && bounded; index += 1) {
+                    if (index > 0)
+                        append(',');
+                    const descriptor = descriptors[String(index)];
+                    if (descriptor && 'value' in descriptor)
+                        walk(descriptor.value);
+                    else
+                        append('"[accessor-or-hole]"');
+                }
+                append(']');
+                return;
+            }
+            append('{');
+            let first = true;
+            for (const key of Object.keys(descriptors).sort()) {
+                const descriptor = descriptors[key];
+                if (!descriptor.enumerable)
+                    continue;
+                if (!first)
+                    append(',');
+                first = false;
+                append(JSON.stringify(key));
+                append(':');
+                if ('value' in descriptor)
+                    walk(descriptor.value);
+                else
+                    append('"[accessor]"');
+                if (!bounded)
+                    break;
+            }
+            append('}');
+        }
+        finally {
+            seen.delete(item);
+        }
+    };
+    walk(value);
+    if (!bounded)
+        return undefined;
+    const fingerprint = `sha256:${hash.digest('hex')}`;
+    return (0, sails_ng_common_1.isRecordFormFingerprint)(fingerprint) ? fingerprint : undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmVjb3JkRm9ybUZpbmdlcnByaW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL1JlY29yZEZvcm1GaW5nZXJwcmludC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQVVBLGtFQXVGQztBQWpHRCw2Q0FBeUM7QUFDekMsc0VBQXVHO0FBRXZHLE1BQU0saUNBQWlDLEdBQUcsU0FBUyxDQUFDO0FBQ3BELE1BQU0saUNBQWlDLEdBQUcsTUFBTSxDQUFDO0FBRWpEOzs7R0FHRztBQUNILFNBQWdCLDJCQUEyQixDQUFDLEtBQWM7SUFDeEQsTUFBTSxJQUFJLEdBQUcsSUFBQSx3QkFBVSxFQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQ2xDLE1BQU0sSUFBSSxHQUFHLElBQUksT0FBTyxFQUFVLENBQUM7SUFDbkMsSUFBSSxLQUFLLEdBQUcsQ0FBQyxDQUFDO0lBQ2QsSUFBSSxLQUFLLEdBQUcsQ0FBQyxDQUFDO0lBQ2QsSUFBSSxPQUFPLEdBQUcsSUFBSSxDQUFDO0lBRW5CLE1BQU0sTUFBTSxHQUFHLENBQUMsSUFBWSxFQUFRLEVBQUU7UUFDcEMsSUFBSSxDQUFDLE9BQU87WUFBRSxPQUFPO1FBQ3JCLE1BQU0sSUFBSSxHQUFHLE1BQU0sQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLENBQUM7UUFDckMsSUFBSSxLQUFLLEdBQUcsSUFBSSxHQUFHLGlDQUFpQyxFQUFFLENBQUM7WUFDckQsT0FBTyxHQUFHLEtBQUssQ0FBQztZQUNoQixPQUFPO1FBQ1QsQ0FBQztRQUNELEtBQUssSUFBSSxJQUFJLENBQUM7UUFDZCxJQUFJLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ3BCLENBQUMsQ0FBQztJQUVGLE1BQU0sSUFBSSxHQUFHLENBQUMsSUFBYSxFQUFRLEVBQUU7UUFDbkMsS0FBSyxJQUFJLENBQUMsQ0FBQztRQUNYLElBQUksS0FBSyxHQUFHLGlDQUFpQyxFQUFFLENBQUM7WUFDOUMsT0FBTyxHQUFHLEtBQUssQ0FBQztZQUNo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

package/dist/RecordHttpConcurrency.d.ts

@@ -0,0 +1,60 @@
+import { type RecordConcurrencyMetadata, type RecordSaveResult } from '@researchdatabox/sails-ng-common';
+import type { RecordConcurrencyContext } from './RecordSaveResponse';
+export declare const RECORD_HTTP_HEADERS: Readonly<{
+    ifMatch: "If-Match";
+    entityTag: "ETag";
+    formFingerprint: "X-ReDBox-Form-Fingerprint";
+    resolution: "X-ReDBox-Concurrency-Resolution";
+    resolutionOfRequestId: "X-ReDBox-Resolution-Of-Request-Id";
+    saveRequestId: "X-ReDBox-Save-Request-Id";
+}>;
+export type PublicRecordConcurrencyRequestErrorCode = 'record-if-match-invalid' | 'record-form-fingerprint-invalid' | 'record-concurrency-resolution-invalid' | 'record-concurrency-request-linkage-invalid';
+export type PublicRecordConcurrencyRequestResult = {
+    readonly valid: true;
+    readonly context: RecordConcurrencyContext;
+} | {
+    readonly valid: false;
+    readonly code: PublicRecordConcurrencyRequestErrorCode;
+    readonly header: string;
+};
+export interface PublicRecordConcurrencyRequestOptions {
+    /** Only generated browser-form submissions bind to a form definition. */
+    readonly formBacked?: boolean;
+}
+/**
+ * Normalize public optimistic-concurrency headers once at the HTTP boundary.
+ * Staleness and policy remain RecordsService/storage decisions; malformed
+ * request contracts are rejected before candidate work begins.
+ */
+export declare function parsePublicRecordConcurrencyRequest(headers: Readonly<Record<string, unknown>> | undefined, recordOid: string | undefined, options?: PublicRecordConcurrencyRequestOptions): PublicRecordConcurrencyRequestResult;
+export declare function recordConcurrencyRequestFailureResponse(apiVersion: string, failure: {
+    readonly code: string;
+    readonly header: string;
+}): Record<string, unknown>;
+export interface RecordRepresentationConcurrency {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly metadata: RecordConcurrencyMetadata;
+}
+/**
+ * Revision of one stored active or tombstone representation. A record written
+ * before the revision migration reads as the initial revision; anything else
+ * non-conforming is a storage fault rather than a value to guess at.
+ */
+export declare function recordRepresentationRevision(record: unknown): number;
+/**
+ * Build read-side revision metadata and the `ETag` header from server-owned
+ * record fields only. Collection rows carry the numeric revision alone: a row
+ * is not an individual representation, so it gets no entity tag.
+ */
+export declare function recordRepresentationConcurrency(record: unknown): RecordRepresentationConcurrency;
+/** Emit only the authoritative entity tag carried by a typed save result. */
+export declare function recordSaveResultHeaders(result: Pick<RecordSaveResult, 'concurrency'> | null | undefined): Readonly<Record<string, string>>;
+/**
+ * Spreadable response fragment. The `headers` key is omitted entirely when a
+ * result carries no authoritative tag, so responses that never had one keep
+ * their existing shape.
+ */
+export declare function recordSaveResultHeaderOption(result: Pick<RecordSaveResult, 'concurrency'> | null | undefined): {
+    headers?: Readonly<Record<string, string>>;
+};
+//# sourceMappingURL=RecordHttpConcurrency.d.ts.map

package/dist/RecordHttpConcurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordHttpConcurrency.d.ts","sourceRoot":"","sources":["../src/RecordHttpConcurrency.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,yBAAyB,EAE9B,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAC;AAEH,MAAM,MAAM,uCAAuC,GAC/C,yBAAyB,GACzB,iCAAiC,GACjC,uCAAuC,GACvC,4CAA4C,CAAC;AAEjD,MAAM,MAAM,oCAAoC,GAC5C;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACpE;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,uCAAuC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,qCAAqC;IACpD,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAqCD;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACtD,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,GAAE,qCAA0C,GAClD,oCAAoC,CA2EtC;AAED,wBAAgB,uCAAuC,CACrD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAUpE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,OAAO,GAAG,+BAA+B,CAWhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/D,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGlC;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG;IAC9G,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5C,CAGA"}