@hypequery/protocol 0.8.0 → 0.9.0

package/dist/events/errors.d.ts

@@ -0,0 +1,14 @@
+import type { ProtocolQueryDiagnosticsErrorCode, ProtocolQueryEventErrorCode } from './types.js';
+export declare class ProtocolQueryEventError extends TypeError {
+    readonly code: ProtocolQueryEventErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolQueryEventErrorCode, path?: string);
+}
+export declare function eventError(code: ProtocolQueryEventErrorCode, path?: string): never;
+export declare class ProtocolQueryDiagnosticsError extends TypeError {
+    readonly code: ProtocolQueryDiagnosticsErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolQueryDiagnosticsErrorCode, path?: string);
+}
+export declare function diagnosticsError(code: ProtocolQueryDiagnosticsErrorCode, path?: string): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/events/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/events/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAEpB,qBAAa,uBAAwB,SAAQ,SAAS;IACpD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,2BAA2B,EAAE,IAAI,SAAM;CAM1D;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,2BAA2B,EACjC,IAAI,SAAM,GACT,KAAK,CAEP;AAED,qBAAa,6BAA8B,SAAQ,SAAS;IAC1D,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,iCAAiC,EAAE,IAAI,SAAM;CAMhE;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iCAAiC,EACvC,IAAI,SAAM,GACT,KAAK,CAEP"}

package/dist/events/errors.js

@@ -0,0 +1,26 @@
+export class ProtocolQueryEventError extends TypeError {
+    code;
+    path;
+    constructor(code, path = '$') {
+        super(`${code} at ${path}`);
+        this.name = 'ProtocolQueryEventError';
+        this.code = code;
+        this.path = path;
+    }
+}
+export function eventError(code, path = '$') {
+    throw new ProtocolQueryEventError(code, path);
+}
+export class ProtocolQueryDiagnosticsError extends TypeError {
+    code;
+    path;
+    constructor(code, path = '$') {
+        super(`${code} at ${path}`);
+        this.name = 'ProtocolQueryDiagnosticsError';
+        this.code = code;
+        this.path = path;
+    }
+}
+export function diagnosticsError(code, path = '$') {
+    throw new ProtocolQueryDiagnosticsError(code, path);
+}

package/dist/events/index.d.ts

@@ -0,0 +1,5 @@
+export { ProtocolQueryDiagnosticsError, ProtocolQueryEventError, } from './errors.js';
+export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS } from './limits.js';
+export { validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './validate.js';
+export type { ProtocolQueryDiagnostics, ProtocolQueryDiagnosticsErrorCode, ProtocolQueryErrorCategory, ProtocolQueryEvent, ProtocolQueryEventErrorCode, ProtocolQueryEventLimits, ProtocolQueryEventOptions, ProtocolQueryEventOutcome, ProtocolQueryEventTarget, ProtocolQueryOperation, ProtocolQueryTerminalReason, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mCAAmC,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,wBAAwB,EACxB,iCAAiC,EACjC,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/events/index.js

@@ -0,0 +1,3 @@
+export { ProtocolQueryDiagnosticsError, ProtocolQueryEventError, } from './errors.js';
+export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS } from './limits.js';
+export { validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './validate.js';

package/dist/events/limits.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolQueryEventLimits, ProtocolQueryEventOptions } from './types.js';
+export declare const DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS: Readonly<ProtocolQueryEventLimits>;
+export declare function resolveQueryEventLimits(options?: ProtocolQueryEventOptions): Readonly<ProtocolQueryEventLimits>;
+//# sourceMappingURL=limits.d.ts.map

package/dist/events/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/events/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,mCAAmC,EAChD,QAAQ,CAAC,wBAAwB,CAG/B,CAAC;AAEH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,yBAA8B,GACtC,QAAQ,CAAC,wBAAwB,CAAC,CAepC"}

package/dist/events/limits.js

@@ -0,0 +1,19 @@
+export const DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS = Object.freeze({
+    maxStringBytes: 1_024,
+    maxDebugBytes: 4_096,
+});
+export function resolveQueryEventLimits(options = {}) {
+    const result = { ...DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS };
+    for (const key of Object.keys(result)) {
+        const value = options.limits?.[key];
+        if (value === undefined)
+            continue;
+        const maximum = DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS[key];
+        if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+            throw new RangeError(`${key} must be a positive safe integer no greater than ${maximum} `
+                + '(the query event v1 maximum)');
+        }
+        result[key] = value;
+    }
+    return Object.freeze(result);
+}

package/dist/events/types.d.ts

@@ -0,0 +1,52 @@
+export interface ProtocolQueryEventTarget {
+    readonly project: string;
+    readonly environment: string;
+}
+export type ProtocolQueryOperation = 'query' | 'command' | 'insert';
+export type ProtocolQueryEventOutcome = 'success' | 'failure';
+/** RFC 0010 version 1 minimum public error categories. */
+export type ProtocolQueryErrorCategory = 'input-invalid' | 'unauthenticated' | 'forbidden' | 'tenant-required' | 'not-found' | 'too-large' | 'aborted' | 'deadline-exceeded' | 'unavailable' | 'internal';
+/** Metadata-only record of one execution. Never carries values, SQL, or credentials. */
+export interface ProtocolQueryEvent {
+    readonly kind: 'hypequery-query-event';
+    readonly version: 1;
+    readonly eventId: string;
+    readonly occurredAt: string;
+    readonly target: ProtocolQueryEventTarget;
+    readonly queryName: string;
+    readonly operation: ProtocolQueryOperation;
+    readonly outcome: ProtocolQueryEventOutcome;
+    /** Required when outcome is 'failure'; forbidden when outcome is 'success'. */
+    readonly errorCategory?: ProtocolQueryErrorCategory;
+    readonly durationMs: number;
+    readonly rowCount?: number;
+    /** Derived server-side fingerprint; the raw tenant identifier is prohibited. */
+    readonly tenantFingerprint?: string;
+    /** External correlation only; never authoritative. */
+    readonly correlationId?: string;
+}
+export type ProtocolQueryTerminalReason = 'completed' | 'aborted' | 'deadline-exceeded' | 'drained';
+/** Privileged diagnostics projection; requires the RFC 0009 diagnostic capability. */
+export interface ProtocolQueryDiagnostics {
+    readonly kind: 'hypequery-query-diagnostics';
+    readonly version: 1;
+    readonly eventId: string;
+    readonly queryId: string;
+    readonly terminalReason: ProtocolQueryTerminalReason;
+    readonly attempts: number;
+    readonly runtimeIdentity?: string;
+    /** Non-executable RFC 0010 debug form; contains no values. */
+    readonly debugQuery?: string;
+    readonly safeMessage?: string;
+}
+export interface ProtocolQueryEventLimits {
+    readonly maxStringBytes: number;
+    readonly maxDebugBytes: number;
+}
+/** Parser budgets that may tighten, but not raise, query-event v1 limits. */
+export interface ProtocolQueryEventOptions {
+    readonly limits?: Partial<ProtocolQueryEventLimits>;
+}
+export type ProtocolQueryEventErrorCode = 'HQ_EVENT_TYPE' | 'HQ_EVENT_UNKNOWN_FIELD' | 'HQ_EVENT_INVALID_VERSION' | 'HQ_EVENT_INVALID_VALUE' | 'HQ_EVENT_TOO_LARGE' | 'HQ_EVENT_UNSAFE_OBJECT';
+export type ProtocolQueryDiagnosticsErrorCode = 'HQ_DIAGNOSTICS_TYPE' | 'HQ_DIAGNOSTICS_UNKNOWN_FIELD' | 'HQ_DIAGNOSTICS_INVALID_VERSION' | 'HQ_DIAGNOSTICS_INVALID_VALUE' | 'HQ_DIAGNOSTICS_TOO_LARGE' | 'HQ_DIAGNOSTICS_UNSAFE_OBJECT';
+//# sourceMappingURL=types.d.ts.map

package/dist/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpE,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D,0DAA0D;AAC1D,MAAM,MAAM,0BAA0B,GAClC,eAAe,GACf,iBAAiB,GACjB,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,UAAU,CAAC;AAEf,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,0BAA0B,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,2BAA2B,GACnC,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,SAAS,CAAC;AAEd,sFAAsF;AACtF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,2BAA2B,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACrD;AAED,MAAM,MAAM,2BAA2B,GACnC,eAAe,GACf,wBAAwB,GACxB,0BAA0B,GAC1B,wBAAwB,GACxB,oBAAoB,GACpB,wBAAwB,CAAC;AAE7B,MAAM,MAAM,iCAAiC,GACzC,qBAAqB,GACrB,8BAA8B,GAC9B,gCAAgC,GAChC,8BAA8B,GAC9B,0BAA0B,GAC1B,8BAA8B,CAAC"}

package/dist/events/types.js

@@ -0,0 +1 @@
+export {};

package/dist/events/validate.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolQueryDiagnostics, ProtocolQueryEvent, ProtocolQueryEventOptions } from './types.js';
+export declare function validateProtocolQueryEvent(input: unknown, options?: ProtocolQueryEventOptions): ProtocolQueryEvent;
+export declare function validateProtocolQueryDiagnostics(input: unknown, options?: ProtocolQueryEventOptions): ProtocolQueryDiagnostics;
+//# sourceMappingURL=validate.d.ts.map

package/dist/events/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/events/validate.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,wBAAwB,EAExB,kBAAkB,EAElB,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AA4OpB,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAuDpB;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA+B1B"}

package/dist/events/validate.js

@@ -0,0 +1,240 @@
+import { ProtocolIdentifierError, parseProtocolQualifiedIdentifier } from '../identifiers/index.js';
+import { ProtocolDeploymentReleaseError, validateProtocolDeploymentReleaseTarget, } from '../releases/index.js';
+import { diagnosticsError, eventError } from './errors.js';
+import { resolveQueryEventLimits } from './limits.js';
+const EVENT_CONTEXT = {
+    codes: {
+        type: 'HQ_EVENT_TYPE',
+        unknownField: 'HQ_EVENT_UNKNOWN_FIELD',
+        invalidVersion: 'HQ_EVENT_INVALID_VERSION',
+        invalidValue: 'HQ_EVENT_INVALID_VALUE',
+        tooLarge: 'HQ_EVENT_TOO_LARGE',
+        unsafeObject: 'HQ_EVENT_UNSAFE_OBJECT',
+    },
+    fail: eventError,
+};
+const DIAGNOSTICS_CONTEXT = {
+    codes: {
+        type: 'HQ_DIAGNOSTICS_TYPE',
+        unknownField: 'HQ_DIAGNOSTICS_UNKNOWN_FIELD',
+        invalidVersion: 'HQ_DIAGNOSTICS_INVALID_VERSION',
+        invalidValue: 'HQ_DIAGNOSTICS_INVALID_VALUE',
+        tooLarge: 'HQ_DIAGNOSTICS_TOO_LARGE',
+        unsafeObject: 'HQ_DIAGNOSTICS_UNSAFE_OBJECT',
+    },
+    fail: diagnosticsError,
+};
+const HEX64_PATTERN = /^[0-9a-f]{64}$/;
+const OCCURRED_AT_PATTERN = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,3})?Z$/;
+const OPERATIONS = ['query', 'command', 'insert'];
+const OUTCOMES = ['success', 'failure'];
+const ERROR_CATEGORIES = [
+    'input-invalid',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'not-found',
+    'too-large',
+    'aborted',
+    'deadline-exceeded',
+    'unavailable',
+    'internal',
+];
+const TERMINAL_REASONS = ['completed', 'aborted', 'deadline-exceeded', 'drained'];
+const MAX_DURATION_MS = 86_400_000;
+const MAX_ROW_COUNT = 1_000_000_000_000;
+const MAX_ATTEMPTS = 64;
+const textEncoder = new TextEncoder();
+function requireRecord(context, input, path) {
+    const { codes, fail } = context;
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        fail(codes.type, path);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        fail(codes.unsafeObject, path);
+    }
+    if (Object.getOwnPropertySymbols(input).length > 0) {
+        fail(codes.unsafeObject, path);
+    }
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(input))) {
+        if (!descriptor.enumerable || !('value' in descriptor)) {
+            fail(codes.unsafeObject, path);
+        }
+    }
+    return input;
+}
+function exactFields(context, value, required, optional, path) {
+    const { codes, fail } = context;
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            fail(codes.unknownField, `${path}.${key}`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            fail(codes.type, `${path}.${key}`);
+    }
+}
+function freezeRecord(entries) {
+    return Object.freeze(Object.assign(Object.create(null), entries));
+}
+function requireString(context, value, path) {
+    if (typeof value !== 'string')
+        context.fail(context.codes.type, path);
+    return value;
+}
+function hasControlCharacter(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function boundedText(context, value, path, maximum) {
+    const text = requireString(context, value, path);
+    if (text.length > maximum || textEncoder.encode(text).byteLength > maximum) {
+        context.fail(context.codes.tooLarge, path);
+    }
+    if (hasControlCharacter(text)) {
+        context.fail(context.codes.invalidValue, path);
+    }
+    return text;
+}
+function hexIdentity(context, value, path) {
+    const text = requireString(context, value, path);
+    if (!HEX64_PATTERN.test(text))
+        context.fail(context.codes.invalidValue, path);
+    return text;
+}
+function occurredAt(context, value, path) {
+    const text = requireString(context, value, path);
+    if (!OCCURRED_AT_PATTERN.test(text) || Number.isNaN(Date.parse(text))) {
+        context.fail(context.codes.invalidValue, path);
+    }
+    return text;
+}
+function boundedCount(context, value, path, minimum, maximum) {
+    if (typeof value !== 'number')
+        context.fail(context.codes.type, path);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        context.fail(context.codes.invalidValue, path);
+    }
+    return value;
+}
+function stringChoice(context, value, path, choices) {
+    const text = requireString(context, value, path);
+    if (!choices.includes(text))
+        context.fail(context.codes.invalidValue, path);
+    return text;
+}
+function queryTarget(context, value, path) {
+    try {
+        return validateProtocolDeploymentReleaseTarget(value);
+    }
+    catch (error) {
+        if (error instanceof ProtocolDeploymentReleaseError) {
+            context.fail(context.codes.invalidValue, path);
+        }
+        throw error;
+    }
+}
+function queryName(context, value, path) {
+    const text = requireString(context, value, path);
+    try {
+        parseProtocolQualifiedIdentifier(text);
+    }
+    catch (error) {
+        if (error instanceof ProtocolIdentifierError) {
+            context.fail(context.codes.invalidValue, path);
+        }
+        throw error;
+    }
+    return text;
+}
+function kindAndVersion(context, value, kind) {
+    const { codes, fail } = context;
+    if (value.kind !== kind) {
+        if (typeof value.kind !== 'string')
+            fail(codes.type, '$.kind');
+        fail(codes.invalidValue, '$.kind');
+    }
+    if (value.version !== 1) {
+        if (typeof value.version !== 'number')
+            fail(codes.type, '$.version');
+        fail(codes.invalidVersion, '$.version');
+    }
+}
+export function validateProtocolQueryEvent(input, options = {}) {
+    const limits = resolveQueryEventLimits(options);
+    const context = EVENT_CONTEXT;
+    const value = requireRecord(context, input, '$');
+    exactFields(context, value, [
+        'kind',
+        'version',
+        'eventId',
+        'occurredAt',
+        'target',
+        'queryName',
+        'operation',
+        'outcome',
+        'durationMs',
+    ], ['errorCategory', 'rowCount', 'tenantFingerprint', 'correlationId'], '$');
+    kindAndVersion(context, value, 'hypequery-query-event');
+    const outcome = stringChoice(context, value.outcome, '$.outcome', OUTCOMES);
+    const hasCategory = Object.hasOwn(value, 'errorCategory');
+    if (outcome === 'failure' && !hasCategory) {
+        eventError('HQ_EVENT_INVALID_VALUE', '$.errorCategory');
+    }
+    if (outcome === 'success' && hasCategory) {
+        eventError('HQ_EVENT_INVALID_VALUE', '$.errorCategory');
+    }
+    return freezeRecord({
+        kind: 'hypequery-query-event',
+        version: 1,
+        eventId: hexIdentity(context, value.eventId, '$.eventId'),
+        occurredAt: occurredAt(context, value.occurredAt, '$.occurredAt'),
+        target: queryTarget(context, value.target, '$.target'),
+        queryName: queryName(context, value.queryName, '$.queryName'),
+        operation: stringChoice(context, value.operation, '$.operation', OPERATIONS),
+        outcome,
+        ...(hasCategory ? {
+            errorCategory: stringChoice(context, value.errorCategory, '$.errorCategory', ERROR_CATEGORIES),
+        } : {}),
+        durationMs: boundedCount(context, value.durationMs, '$.durationMs', 0, MAX_DURATION_MS),
+        ...(Object.hasOwn(value, 'rowCount') ? {
+            rowCount: boundedCount(context, value.rowCount, '$.rowCount', 0, MAX_ROW_COUNT),
+        } : {}),
+        ...(Object.hasOwn(value, 'tenantFingerprint') ? {
+            tenantFingerprint: hexIdentity(context, value.tenantFingerprint, '$.tenantFingerprint'),
+        } : {}),
+        ...(Object.hasOwn(value, 'correlationId') ? {
+            correlationId: boundedText(context, value.correlationId, '$.correlationId', limits.maxStringBytes),
+        } : {}),
+    });
+}
+export function validateProtocolQueryDiagnostics(input, options = {}) {
+    const limits = resolveQueryEventLimits(options);
+    const context = DIAGNOSTICS_CONTEXT;
+    const value = requireRecord(context, input, '$');
+    exactFields(context, value, ['kind', 'version', 'eventId', 'queryId', 'terminalReason', 'attempts'], ['runtimeIdentity', 'debugQuery', 'safeMessage'], '$');
+    kindAndVersion(context, value, 'hypequery-query-diagnostics');
+    return freezeRecord({
+        kind: 'hypequery-query-diagnostics',
+        version: 1,
+        eventId: hexIdentity(context, value.eventId, '$.eventId'),
+        queryId: hexIdentity(context, value.queryId, '$.queryId'),
+        terminalReason: stringChoice(context, value.terminalReason, '$.terminalReason', TERMINAL_REASONS),
+        attempts: boundedCount(context, value.attempts, '$.attempts', 1, MAX_ATTEMPTS),
+        ...(Object.hasOwn(value, 'runtimeIdentity') ? {
+            runtimeIdentity: hexIdentity(context, value.runtimeIdentity, '$.runtimeIdentity'),
+        } : {}),
+        ...(Object.hasOwn(value, 'debugQuery') ? {
+            debugQuery: boundedText(context, value.debugQuery, '$.debugQuery', limits.maxDebugBytes),
+        } : {}),
+        ...(Object.hasOwn(value, 'safeMessage') ? {
+            safeMessage: boundedText(context, value.safeMessage, '$.safeMessage', limits.maxStringBytes),
+        } : {}),
+    });
+}

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { ProtocolSchema, ProtocolSchemaErrorCode, ProtocolSchemaLimits, Pro
 export type { ProtocolAggregation, ProtocolBinaryOperator, ProtocolComparisonOperator, ProtocolDatasetQuery, ProtocolExpression, ProtocolExpressionErrorCode, ProtocolExpressionLimits, ProtocolExpressionOptions, ProtocolFunctionName, ProtocolMetricQuery, ProtocolOrderBy, ProtocolSemanticQuery, ProtocolTimeGrain, } from './expressions/index.js';
 export type { ProtocolIdentifier, ProtocolIdentifierErrorCode, ProtocolQualifiedIdentifier, } from './identifiers/index.js';
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';
+export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS, ProtocolQueryDiagnosticsError, ProtocolQueryEventError, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './events/index.js';
+export type { ProtocolQueryDiagnostics, ProtocolQueryDiagnosticsErrorCode, ProtocolQueryErrorCategory, ProtocolQueryEvent, ProtocolQueryEventErrorCode, ProtocolQueryEventLimits, ProtocolQueryEventOptions, ProtocolQueryEventOutcome, ProtocolQueryEventTarget, ProtocolQueryOperation, ProtocolQueryTerminalReason, } from './events/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, PROTOCOL_DEPLOYMENT_BUNDLE_IDENTITY_DOMAIN, ProtocolDeploymentBundleError, encodeProtocolDeploymentBundleManifest, encodeProtocolDeploymentBundleManifestToString, hashProtocolDeploymentBundleManifest, prepareProtocolDeploymentBundleManifest, validateProtocolDeploymentBundleManifest, } from './bundles/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_RELEASE_LIMITS, PROTOCOL_DEPLOYMENT_RELEASE_IDENTITY_DOMAIN, ProtocolDeploymentReleaseError, encodeProtocolDeploymentReleaseEnvelope, encodeProtocolDeploymentReleaseEnvelopeToString, hashProtocolDeploymentReleaseEnvelope, prepareProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseTarget, } from './releases/index.js';
 export type { PreparedProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseErrorCode, ProtocolDeploymentReleaseLimits, ProtocolDeploymentReleaseOptions, ProtocolDeploymentReleaseTarget, } from './releases/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -3,6 +3,7 @@ export { PROTOCOL_IDENTIFIER_LIMITS, ProtocolIdentifierError, isProtocolIdentifi
 export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validateProtocolExpression, validateProtocolSemanticQuery, } from './expressions/index.js';
 export { DEFAULT_PROTOCOL_SCHEMA_LIMITS, DEFAULT_PROTOCOL_SCHEMA_VALUE_LIMITS, ProtocolSchemaError, ProtocolSchemaValueError, applyProtocolSchemaValue, createProtocolSchemaValueParser, resolveProtocolSchemaValueLimits, validateProtocolSchema, } from './schemas/index.js';
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';
+export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS, ProtocolQueryDiagnosticsError, ProtocolQueryEventError, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './events/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, PROTOCOL_DEPLOYMENT_BUNDLE_IDENTITY_DOMAIN, ProtocolDeploymentBundleError, encodeProtocolDeploymentBundleManifest, encodeProtocolDeploymentBundleManifestToString, hashProtocolDeploymentBundleManifest, prepareProtocolDeploymentBundleManifest, validateProtocolDeploymentBundleManifest, } from './bundles/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_RELEASE_LIMITS, PROTOCOL_DEPLOYMENT_RELEASE_IDENTITY_DOMAIN, ProtocolDeploymentReleaseError, encodeProtocolDeploymentReleaseEnvelope, encodeProtocolDeploymentReleaseEnvelopeToString, hashProtocolDeploymentReleaseEnvelope, prepareProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseTarget, } from './releases/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_LIMITS, PROTOCOL_DEPLOYMENT_IDENTITY_DOMAIN, ProtocolDeploymentError, encodeProtocolDeploymentContract, encodeProtocolDeploymentContractToString, hashProtocolDeploymentContract, prepareProtocolDeploymentContract, validateProtocolDatasetContract, validateProtocolDeploymentContract, } from './deployments/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Public contracts and TypeScript reference implementation for portable Hypequery artifacts",
   "license": "Apache-2.0",
   "type": "module",