@empire-builder-kit/runtime 1.0.0-beta.9 → 1.0.0-rc.2

package/src/reliability/model.d.ts

@@ -0,0 +1,191 @@
+import type { AlarmDefinition, AlarmSeverity } from '../observability.js';
+import type { ApprovalRequest } from '../authorization/approval.js';
+export declare const RELIABILITY_SCHEMA_VERSION: 1;
+export type SliType = 'availability' | 'latency' | 'freshness' | 'durability' | 'correctness' | 'deadline';
+export type SloWindowKind = 'rolling' | 'calendar';
+export type SloTier = 'critical' | 'important' | 'standard';
+export type ReliabilityMeasurementProvider = 'direct-cloudwatch-metric-math' | 'application-signals';
+export interface ReliabilityCostEstimate {
+    currency: 'USD';
+    monthly: number;
+    provenance: 'estimate';
+}
+export interface ReliabilityProviderDecision {
+    applicationSignalsCoverage: readonly string[];
+    basis: string;
+    cost: ReliabilityCostEstimate;
+    directMetricMathCoverage: readonly string[];
+    reviewedAt: string;
+    selected: ReliabilityMeasurementProvider;
+}
+export interface SloIndicator {
+    goodEventDefinition: string;
+    metricRef: string;
+    threshold?: number;
+    type: SliType;
+    unit?: string;
+    validEventDefinition: string;
+}
+export interface SloLowTrafficPolicy {
+    mode: 'data-insufficient' | 'synthetic';
+    syntheticRef?: string;
+}
+export interface SloBurnThresholds {
+    fast: number;
+    slow: number;
+    warning: number;
+}
+export interface SloMinimumValidEvents {
+    diagnosticSample: number;
+    fastBurnWindow: number;
+    objectiveWindow: number;
+    slowBurnWindow: number;
+}
+export interface SloReferences {
+    alarmIds: readonly string[];
+    dashboardRef: string;
+    runbookRef: string;
+    syntheticRef?: string;
+}
+export interface SloObjective {
+    allowedExclusionPolicyRef: string;
+    burn: SloBurnThresholds;
+    effectiveAt: string;
+    feature: string;
+    id: string;
+    indicator: SloIndicator;
+    journey: string;
+    lowTraffic: SloLowTrafficPolicy;
+    minimumValidEvents: SloMinimumValidEvents;
+    owner: string;
+    references: SloReferences;
+    target: number;
+    tier: SloTier;
+    window: {
+        days: number;
+        kind: SloWindowKind;
+    };
+}
+export interface SliceReliabilityContract {
+    escalationRouteKey: string;
+    objectives: readonly SloObjective[];
+    owner: string;
+    providerDecision: ReliabilityProviderDecision;
+    schemaVersion: typeof RELIABILITY_SCHEMA_VERSION;
+    slice: string;
+}
+export type AlarmMissingDataBehavior = 'breaching' | 'notBreaching' | 'ignore' | 'missing';
+export interface AlarmRegistrationMetadata {
+    businessSymptom: string;
+    condition: string;
+    dependencyAlarmIds: readonly string[];
+    escalationRouteKey: string;
+    expectedFalseNegativeRisk: string;
+    expectedFalsePositiveRisk: string;
+    id: string;
+    missingData: AlarmMissingDataBehavior;
+    owner: string;
+    runbookRef: string;
+    severity: AlarmSeverity;
+    testRef: string;
+}
+export interface RegisteredAlarmDefinition extends AlarmDefinition {
+    registration: AlarmRegistrationMetadata;
+}
+export type SloEvaluationState = 'data-insufficient' | 'synthetic-healthy' | 'synthetic-failed' | 'healthy' | 'warning' | 'slow-burn' | 'fast-burn' | 'exhausted';
+export interface SloEvaluation {
+    badEvents: number;
+    burnRate: number | null;
+    errorBudgetEvents: number;
+    errorBudgetRemainingEvents: number;
+    goodEvents: number;
+    objectiveId: string;
+    state: SloEvaluationState;
+    target: number;
+    validEvents: number;
+}
+export type IncidentSeverity = 'SEV-1' | 'SEV-2' | 'SEV-3' | 'SEV-4';
+export type IncidentState = 'declared' | 'stabilizing' | 'diagnosing' | 'recovering' | 'monitoring' | 'resolved';
+export interface IncidentRoles {
+    communicationsOwner: string;
+    incidentCommander: string;
+    scribe: string;
+    technicalLead: string;
+}
+export interface IncidentTimelineEntry {
+    actor: string;
+    at: string;
+    evidenceRefs: readonly string[];
+    message: string;
+    type: 'observation' | 'decision' | 'action' | 'verification';
+}
+export interface IncidentRecord {
+    affectedJourneyIds: readonly string[];
+    candidateId?: string;
+    configurationDigest?: string;
+    declaredAt: string;
+    followUpRefs: readonly string[];
+    id: string;
+    impact: string;
+    roles: IncidentRoles;
+    severity: IncidentSeverity;
+    slice: string;
+    state: IncidentState;
+    timeline: readonly IncidentTimelineEntry[];
+}
+export type DiagnosticSource = 'alarm-state' | 'resource-metadata' | 'sanitized-signal' | 'bounded-log-query';
+export interface DiagnosticTarget {
+    account: string;
+    region: string;
+    slice: string;
+    stage: string;
+}
+export interface SensitiveDiagnosticApproval {
+    allowedLogGroups: readonly string[];
+    authorization: ApprovalRequest<'reliability-diagnostic'>;
+    incidentRef: string;
+    queryClass: string;
+    reason: string;
+    target: DiagnosticTarget;
+    windowEnd: string;
+    windowStart: string;
+}
+export interface DiagnosticRequest {
+    approval?: SensitiveDiagnosticApproval;
+    source: DiagnosticSource;
+    target: DiagnosticTarget;
+}
+export interface DiagnosticPlan {
+    approvalRequired: boolean;
+    expiresAt?: string;
+    queryClass?: string;
+    source: DiagnosticSource;
+    target: DiagnosticTarget;
+}
+export type RemediationAction = 'protected-revert' | 'roll-forward' | 'redrive' | 'replay' | 'restore' | 'degraded-mode';
+export interface RemediationApproval {
+    authorization: ApprovalRequest<'reliability-remediation'>;
+    incidentRef: string;
+}
+export type RemediationExecution = {
+    adapter: 'protected-async-recovery';
+    asyncRecoveryReportDigest: string;
+} | {
+    adapter: 'report-only';
+};
+export interface RemediationRequest {
+    action: RemediationAction;
+    approval?: RemediationApproval;
+    cleanup: readonly string[];
+    execution: RemediationExecution;
+    mode: 'report' | 'apply';
+    preconditions: readonly string[];
+    stopConditions: readonly string[];
+    target: DiagnosticTarget;
+    verification: readonly string[];
+}
+export interface RemediationPlan extends RemediationRequest {
+    approvalRequired: true;
+    authorized: boolean;
+    remediationPlanDigest: string;
+}

package/src/reliability/model.fixtures.d.ts

@@ -0,0 +1,2 @@
+import type { SliceReliabilityContract } from './model.js';
+export declare function reliabilityFixture(): SliceReliabilityContract;

package/src/reliability/model.fixtures.js

@@ -0,0 +1,57 @@
+export function reliabilityFixture() {
+    return {
+        escalationRouteKey: 'commerce-on-call',
+        objectives: [
+            {
+                allowedExclusionPolicyRef: 'docs:reliability/exclusions.md',
+                burn: { fast: 14.4, slow: 6, warning: 0.5 },
+                effectiveAt: '2026-07-29T00:00:00.000Z',
+                feature: 'web',
+                id: 'checkout-availability',
+                indicator: {
+                    goodEventDefinition: 'Valid checkout requests complete without a server failure.',
+                    metricRef: 'operations:metrics/checkout-availability',
+                    type: 'availability',
+                    validEventDefinition: 'Authenticated checkout requests accepted by policy.',
+                },
+                journey: 'complete-checkout',
+                lowTraffic: {
+                    mode: 'synthetic',
+                    syntheticRef: 'synthetic:checkout',
+                },
+                minimumValidEvents: {
+                    diagnosticSample: 100,
+                    fastBurnWindow: 1,
+                    objectiveWindow: 100,
+                    slowBurnWindow: 5,
+                },
+                owner: 'commerce',
+                references: {
+                    alarmIds: ['checkout-fast-burn', 'checkout-slow-burn'],
+                    dashboardRef: 'dashboard:checkout',
+                    runbookRef: 'runbook:checkout-recovery',
+                    syntheticRef: 'synthetic:checkout',
+                },
+                target: 0.99,
+                tier: 'critical',
+                window: { days: 28, kind: 'rolling' },
+            },
+        ],
+        owner: 'commerce',
+        providerDecision: {
+            applicationSignalsCoverage: ['lambda', 'next'],
+            basis: 'Direct metric math covers every generated workload at lower forecast cost.',
+            cost: {
+                currency: 'USD',
+                monthly: 4.25,
+                provenance: 'estimate',
+            },
+            directMetricMathCoverage: ['lambda', 'next', 'service', 'job', 'queue'],
+            reviewedAt: '2026-07-29T00:00:00.000Z',
+            selected: 'direct-cloudwatch-metric-math',
+        },
+        schemaVersion: 1,
+        slice: 'billing',
+    };
+}
+//# sourceMappingURL=model.fixtures.js.map

package/src/reliability/model.fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.fixtures.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/reliability/model.fixtures.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,kBAAkB,EAAE,kBAAkB;QACtC,UAAU,EAAE;YACV;gBACE,yBAAyB,EAAE,gCAAgC;gBAC3D,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE;gBAC3C,WAAW,EAAE,0BAA0B;gBACvC,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,uBAAuB;gBAC3B,SAAS,EAAE;oBACT,mBAAmB,EACjB,4DAA4D;oBAC9D,SAAS,EAAE,0CAA0C;oBACrD,IAAI,EAAE,cAAc;oBACpB,oBAAoB,EAClB,qDAAqD;iBACxD;gBACD,OAAO,EAAE,mBAAmB;gBAC5B,UAAU,EAAE;oBACV,IAAI,EAAE,WAAW;oBACjB,YAAY,EAAE,oBAAoB;iBACnC;gBACD,kBAAkB,EAAE;oBAClB,gBAAgB,EAAE,GAAG;oBACrB,cAAc,EAAE,CAAC;oBACjB,eAAe,EAAE,GAAG;oBACpB,cAAc,EAAE,CAAC;iBAClB;gBACD,KAAK,EAAE,UAAU;gBACjB,UAAU,EAAE;oBACV,QAAQ,EAAE,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;oBACtD,YAAY,EAAE,oBAAoB;oBAClC,UAAU,EAAE,2BAA2B;oBACvC,YAAY,EAAE,oBAAoB;iBACnC;gBACD,MAAM,EAAE,IAAI;gBACZ,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;aACtC;SACF;QACD,KAAK,EAAE,UAAU;QACjB,gBAAgB,EAAE;YAChB,0BAA0B,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC9C,KAAK,EACH,4EAA4E;YAC9E,IAAI,EAAE;gBACJ,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,UAAU;aACvB;YACD,wBAAwB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC;YACvE,UAAU,EAAE,0BAA0B;YACtC,QAAQ,EAAE,+BAA+B;SAC1C;QACD,aAAa,EAAE,CAAC;QAChB,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC"}

package/src/reliability/model.js

@@ -0,0 +1,2 @@
+export const RELIABILITY_SCHEMA_VERSION = 1;
+//# sourceMappingURL=model.js.map

package/src/reliability/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/reliability/model.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAU,CAAC"}

package/src/reliability/slo.d.ts

@@ -0,0 +1,9 @@
+import type { SloEvaluation, SloObjective } from './model.js';
+export interface EvaluateSloInput {
+    goodEvents: number;
+    minimumValidEvents?: number;
+    objective: SloObjective;
+    syntheticSuccess?: boolean;
+    validEvents: number;
+}
+export declare function evaluateSlo(input: EvaluateSloInput): SloEvaluation;

package/src/reliability/slo.js

@@ -0,0 +1,74 @@
+function count(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`[runtime/reliability] \`${field}\` must be a non-negative safe integer.`);
+    }
+    return value;
+}
+export function evaluateSlo(input) {
+    var _a;
+    const validEvents = count(input.validEvents, 'validEvents');
+    const goodEvents = count(input.goodEvents, 'goodEvents');
+    if (goodEvents > validEvents) {
+        throw new Error('[runtime/reliability] goodEvents cannot exceed validEvents.');
+    }
+    const badEvents = validEvents - goodEvents;
+    const errorBudgetEvents = validEvents * (1 - input.objective.target);
+    const errorBudgetRemainingEvents = errorBudgetEvents - badEvents;
+    const minimumValidEvents = (_a = input.minimumValidEvents) !== null && _a !== void 0 ? _a : input.objective.minimumValidEvents.objectiveWindow;
+    count(minimumValidEvents, 'minimumValidEvents');
+    if (minimumValidEvents < 1) {
+        throw new Error('[runtime/reliability] `minimumValidEvents` must be positive.');
+    }
+    if (validEvents < minimumValidEvents) {
+        let state = 'data-insufficient';
+        if (input.objective.lowTraffic.mode === 'synthetic') {
+            if (input.syntheticSuccess === undefined) {
+                throw new Error('[runtime/reliability] A synthetic result is required by the low-traffic policy.');
+            }
+            state = input.syntheticSuccess ? 'synthetic-healthy' : 'synthetic-failed';
+        }
+        return {
+            badEvents,
+            burnRate: null,
+            errorBudgetEvents,
+            errorBudgetRemainingEvents,
+            goodEvents,
+            objectiveId: input.objective.id,
+            state,
+            target: input.objective.target,
+            validEvents,
+        };
+    }
+    const allowedErrorRate = 1 - input.objective.target;
+    const actualErrorRate = validEvents === 0 ? 0 : badEvents / validEvents;
+    const burnRate = allowedErrorRate === 0
+        ? actualErrorRate === 0
+            ? 0
+            : Number.POSITIVE_INFINITY
+        : actualErrorRate / allowedErrorRate;
+    let state = 'healthy';
+    if (burnRate >= input.objective.burn.fast) {
+        state = 'fast-burn';
+    }
+    else if (burnRate >= input.objective.burn.slow) {
+        state = 'slow-burn';
+    }
+    else if (errorBudgetRemainingEvents <= 0) {
+        state = 'exhausted';
+    }
+    else if (burnRate >= input.objective.burn.warning) {
+        state = 'warning';
+    }
+    return {
+        badEvents,
+        burnRate,
+        errorBudgetEvents,
+        errorBudgetRemainingEvents,
+        goodEvents,
+        objectiveId: input.objective.id,
+        state,
+        target: input.objective.target,
+        validEvents,
+    };
+}
+//# sourceMappingURL=slo.js.map

package/src/reliability/slo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slo.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/reliability/slo.ts"],"names":[],"mappings":"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"}

package/src/request-context.d.ts

@@ -4,38 +4,80 @@ export interface RequestActor {
     id?: string;
     type: 'service' | 'system' | 'user';
 }
-export interface RequestContext {
-    app: string;
-    actor?: RequestActor;
+/**
+ * The propagation context shared by HTTP, event, Next.js server, Service, and
+ * Job workloads. Identity and authorization data can coexist with this context
+ * in the more specific request/event types, but is deliberately not part of
+ * the logging projection.
+ */
+export interface RuntimeContext {
     causationId?: string;
     correlationId: string;
+    eventId?: string;
+    eventType?: string;
+    requestId?: string;
+    spanId?: string;
+    traceId?: string;
+    traceParent?: string;
+    traceState?: string;
+}
+export interface RuntimeContextInput {
+    causationId?: string;
+    correlationId?: string;
+    eventId?: string;
+    eventType?: string;
+    requestId?: string;
+    traceParent?: string;
+    traceState?: string;
+}
+export interface RequestContext extends RuntimeContext {
+    actor?: RequestActor;
     metadata: RequestMetadata;
     operation: string;
     requestId: string;
+    slice: string;
     source?: string;
     stage?: string;
     tenantId?: string;
-    traceParent?: string;
-    traceState?: string;
 }
-export interface RequestContextInput {
-    app: string;
+export interface RequestContextInput extends RuntimeContextInput {
     actor?: RequestActor;
-    causationId?: string;
-    correlationId?: string;
     metadata?: Record<string, RequestMetadataValue | undefined>;
     operation: string;
-    requestId?: string;
+    slice: string;
     source?: string;
     stage?: string;
     tenantId?: string;
-    traceParent?: string;
-    traceState?: string;
 }
+export type RequestContextOverrides = Omit<Partial<RequestContextInput>, 'slice'>;
 export declare function normalizePropagationId(value: string | null | undefined): string | undefined;
+export declare function normalizeEventType(value: string | null | undefined): string | undefined;
 export declare function normalizeTraceParent(value: string | null | undefined): string | undefined;
 export declare function normalizeTraceState(value: string | null | undefined): string | undefined;
+export declare function traceIdsFromParent(traceParent: string | null | undefined): Pick<RuntimeContext, 'spanId' | 'traceId'>;
+export declare function normalizeTraceId(value: string | null | undefined): string | undefined;
+export declare function normalizeSpanId(value: string | null | undefined): string | undefined;
+/**
+ * Creates the shared propagation context. Invalid inbound identifiers are
+ * rejected from the context rather than reflected; a fresh correlation ID is
+ * used when no valid propagation anchor remains.
+ */
+export declare function createRuntimeContext(input?: RuntimeContextInput): RuntimeContext;
 export declare function createRequestContext(input: RequestContextInput): RequestContext;
-export declare function extendRequestContext(context: RequestContext, overrides?: Partial<RequestContextInput>): RequestContext;
-export declare function toRequestHeaders(context: Pick<RequestContext, 'correlationId' | 'requestId' | 'traceParent' | 'traceState'>): Record<string, string>;
-export declare function toRequestLogMetadata(context: Partial<RequestContext>): RequestMetadata;
+export declare function extendRequestContext(context: RequestContext, overrides?: RequestContextOverrides): RequestContext;
+/**
+ * Named helpers keep generated workload entry points on one context contract
+ * without inventing per-workload propagation shapes.
+ */
+export declare function createPublisherContext(input?: RuntimeContextInput): RuntimeContext;
+export declare function createConsumerContext(input: RuntimeContextInput): RuntimeContext;
+export declare function createNextServerContext(input: RequestContextInput): RequestContext;
+export declare function createServiceContext(input?: RuntimeContextInput): RuntimeContext;
+export declare function createJobContext(input?: RuntimeContextInput): RuntimeContext;
+export declare function toRequestHeaders(context: Pick<RuntimeContext, 'causationId' | 'correlationId' | 'requestId' | 'traceParent' | 'traceState'>): Record<string, string>;
+/**
+ * Projects only operational lookup fields. Actor, tenant, arbitrary request
+ * metadata, network identity, headers, paths, query, and bodies are
+ * intentionally excluded.
+ */
+export declare function toLogContext(context: Partial<RuntimeContext>): Partial<RuntimeContext>;

package/src/request-context.js

@@ -1,15 +1,34 @@
 import { randomUUID } from 'node:crypto';
 const PROPAGATION_ID_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/;
-const TRACE_PARENT_PATTERN = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+const EVENT_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9._:-]{0,127}$/;
+const TRACE_PARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const TRACE_ID_PATTERN = /^[0-9a-f]{32}$/;
+const SPAN_ID_PATTERN = /^[0-9a-f]{16}$/;
+const ZERO_TRACE_ID = '0'.repeat(32);
+const ZERO_SPAN_ID = '0'.repeat(16);
+function assertNonEmpty(value, field) {
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        throw new Error(`[runtime/request-context] \`${field}\` is required.`);
+    }
+    return normalized;
+}
 export function normalizePropagationId(value) {
     const normalized = value === null || value === void 0 ? void 0 : value.trim();
     return normalized && PROPAGATION_ID_PATTERN.test(normalized)
         ? normalized
         : undefined;
 }
+export function normalizeEventType(value) {
+    const normalized = value === null || value === void 0 ? void 0 : value.trim();
+    return normalized && EVENT_TYPE_PATTERN.test(normalized)
+        ? normalized
+        : undefined;
+}
 export function normalizeTraceParent(value) {
     const normalized = value === null || value === void 0 ? void 0 : value.trim().toLowerCase();
-    return normalized && TRACE_PARENT_PATTERN.test(normalized)
+    const match = normalized === null || normalized === void 0 ? void 0 : normalized.match(TRACE_PARENT_PATTERN);
+    return match && match[1] !== ZERO_TRACE_ID && match[2] !== ZERO_SPAN_ID
         ? normalized
         : undefined;
 }
@@ -19,50 +38,111 @@ export function normalizeTraceState(value) {
         ? normalized
         : undefined;
 }
+export function traceIdsFromParent(traceParent) {
+    const normalized = normalizeTraceParent(traceParent);
+    const match = normalized === null || normalized === void 0 ? void 0 : normalized.match(TRACE_PARENT_PATTERN);
+    return match ? { traceId: match[1], spanId: match[2] } : {};
+}
+export function normalizeTraceId(value) {
+    const normalized = value === null || value === void 0 ? void 0 : value.trim().toLowerCase();
+    return normalized &&
+        TRACE_ID_PATTERN.test(normalized) &&
+        normalized !== ZERO_TRACE_ID
+        ? normalized
+        : undefined;
+}
+export function normalizeSpanId(value) {
+    const normalized = value === null || value === void 0 ? void 0 : value.trim().toLowerCase();
+    return normalized &&
+        SPAN_ID_PATTERN.test(normalized) &&
+        normalized !== ZERO_SPAN_ID
+        ? normalized
+        : undefined;
+}
 function normalizeMetadata(metadata) {
     const entries = Object.entries(metadata !== null && metadata !== void 0 ? metadata : {}).filter(([, value]) => value !== undefined);
     return Object.fromEntries(entries);
 }
+/**
+ * Creates the shared propagation context. Invalid inbound identifiers are
+ * rejected from the context rather than reflected; a fresh correlation ID is
+ * used when no valid propagation anchor remains.
+ */
+export function createRuntimeContext(input = {}) {
+    var _a, _b, _c;
+    const requestId = normalizePropagationId(input.requestId);
+    const eventId = normalizePropagationId(input.eventId);
+    const correlationId = (_c = (_b = (_a = normalizePropagationId(input.correlationId)) !== null && _a !== void 0 ? _a : requestId) !== null && _b !== void 0 ? _b : eventId) !== null && _c !== void 0 ? _c : randomUUID();
+    const traceParent = normalizeTraceParent(input.traceParent);
+    return Object.assign(Object.assign({ causationId: normalizePropagationId(input.causationId), correlationId,
+        eventId, eventType: normalizeEventType(input.eventType), requestId }, traceIdsFromParent(traceParent)), { traceParent, traceState: normalizeTraceState(input.traceState) });
+}
 export function createRequestContext(input) {
-    var _a, _b;
+    var _a, _b, _c;
     const requestId = (_a = normalizePropagationId(input.requestId)) !== null && _a !== void 0 ? _a : randomUUID();
-    return {
-        app: input.app,
-        actor: input.actor,
-        causationId: normalizePropagationId(input.causationId),
-        correlationId: (_b = normalizePropagationId(input.correlationId)) !== null && _b !== void 0 ? _b : requestId,
-        metadata: normalizeMetadata(input.metadata),
-        operation: input.operation,
-        requestId,
-        source: input.source,
-        stage: input.stage,
-        tenantId: normalizePropagationId(input.tenantId),
-        traceParent: normalizeTraceParent(input.traceParent),
-        traceState: normalizeTraceState(input.traceState),
-    };
+    const propagation = createRuntimeContext(Object.assign(Object.assign({}, input), { requestId, correlationId: (_b = normalizePropagationId(input.correlationId)) !== null && _b !== void 0 ? _b : requestId }));
+    return Object.assign(Object.assign({}, propagation), { actor: input.actor, metadata: normalizeMetadata(input.metadata), operation: assertNonEmpty(input.operation, 'operation'), requestId, slice: assertNonEmpty(input.slice, 'slice'), source: input.source, stage: ((_c = input.stage) === null || _c === void 0 ? void 0 : _c.trim()) || undefined, tenantId: normalizePropagationId(input.tenantId) });
 }
 export function extendRequestContext(context, overrides = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
-    return {
-        app: (_a = overrides.app) !== null && _a !== void 0 ? _a : context.app,
-        actor: (_b = overrides.actor) !== null && _b !== void 0 ? _b : context.actor,
-        causationId: (_c = normalizePropagationId(overrides.causationId)) !== null && _c !== void 0 ? _c : context.causationId,
-        correlationId: (_d = normalizePropagationId(overrides.correlationId)) !== null && _d !== void 0 ? _d : context.correlationId,
-        metadata: Object.assign(Object.assign({}, context.metadata), normalizeMetadata(overrides.metadata)),
-        operation: (_e = overrides.operation) !== null && _e !== void 0 ? _e : context.operation,
-        requestId: (_f = overrides.requestId) !== null && _f !== void 0 ? _f : context.requestId,
-        source: (_g = overrides.source) !== null && _g !== void 0 ? _g : context.source,
-        stage: (_h = overrides.stage) !== null && _h !== void 0 ? _h : context.stage,
-        tenantId: (_j = normalizePropagationId(overrides.tenantId)) !== null && _j !== void 0 ? _j : context.tenantId,
-        traceParent: (_k = normalizeTraceParent(overrides.traceParent)) !== null && _k !== void 0 ? _k : context.traceParent,
-        traceState: (_l = normalizeTraceState(overrides.traceState)) !== null && _l !== void 0 ? _l : context.traceState,
-    };
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    if ('slice' in overrides) {
+        throw new Error('[runtime/request-context] A request context cannot change its Slice.');
+    }
+    const requestId = (_a = normalizePropagationId(overrides.requestId)) !== null && _a !== void 0 ? _a : context.requestId;
+    const traceParent = overrides.traceParent === undefined
+        ? context.traceParent
+        : normalizeTraceParent(overrides.traceParent);
+    const traceState = overrides.traceState === undefined
+        ? context.traceState
+        : normalizeTraceState(overrides.traceState);
+    return Object.assign(Object.assign({ actor: (_b = overrides.actor) !== null && _b !== void 0 ? _b : context.actor, causationId: (_c = normalizePropagationId(overrides.causationId)) !== null && _c !== void 0 ? _c : context.causationId, correlationId: (_d = normalizePropagationId(overrides.correlationId)) !== null && _d !== void 0 ? _d : context.correlationId, eventId: (_e = normalizePropagationId(overrides.eventId)) !== null && _e !== void 0 ? _e : context.eventId, eventType: (_f = normalizeEventType(overrides.eventType)) !== null && _f !== void 0 ? _f : context.eventType, metadata: Object.assign(Object.assign({}, context.metadata), normalizeMetadata(overrides.metadata)), operation: overrides.operation === undefined
+            ? context.operation
+            : assertNonEmpty(overrides.operation, 'operation'), requestId, slice: context.slice, source: (_g = overrides.source) !== null && _g !== void 0 ? _g : context.source, stage: ((_h = overrides.stage) === null || _h === void 0 ? void 0 : _h.trim()) || context.stage, tenantId: (_j = normalizePropagationId(overrides.tenantId)) !== null && _j !== void 0 ? _j : context.tenantId }, traceIdsFromParent(traceParent)), { traceParent,
+        traceState });
+}
+/**
+ * Named helpers keep generated workload entry points on one context contract
+ * without inventing per-workload propagation shapes.
+ */
+export function createPublisherContext(input = {}) {
+    return createRuntimeContext(input);
+}
+export function createConsumerContext(input) {
+    return createRuntimeContext(input);
+}
+export function createNextServerContext(input) {
+    return createRequestContext(input);
+}
+export function createServiceContext(input = {}) {
+    var _a;
+    return createRuntimeContext(Object.assign(Object.assign({}, input), { requestId: (_a = normalizePropagationId(input.requestId)) !== null && _a !== void 0 ? _a : randomUUID() }));
+}
+export function createJobContext(input = {}) {
+    var _a;
+    return createRuntimeContext(Object.assign(Object.assign({}, input), { requestId: (_a = normalizePropagationId(input.requestId)) !== null && _a !== void 0 ? _a : randomUUID() }));
 }
 export function toRequestHeaders(context) {
-    return Object.assign(Object.assign({ 'x-causation-id': context.requestId, 'x-correlation-id': context.correlationId, 'x-request-id': context.requestId }, (context.traceParent ? { traceparent: context.traceParent } : {})), (context.traceState ? { tracestate: context.traceState } : {}));
+    var _a;
+    const causationId = (_a = context.requestId) !== null && _a !== void 0 ? _a : context.causationId;
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (causationId ? { 'x-causation-id': causationId } : {})), { 'x-correlation-id': context.correlationId }), (context.requestId ? { 'x-request-id': context.requestId } : {})), (context.traceParent ? { traceparent: context.traceParent } : {})), (context.traceState ? { tracestate: context.traceState } : {}));
 }
-export function toRequestLogMetadata(context) {
-    var _a, _b;
-    return normalizeMetadata(Object.assign({ actorId: (_a = context.actor) === null || _a === void 0 ? void 0 : _a.id, actorType: (_b = context.actor) === null || _b === void 0 ? void 0 : _b.type, app: context.app, causationId: context.causationId, correlationId: context.correlationId, operation: context.operation, requestId: context.requestId, source: context.source, stage: context.stage, tenantId: context.tenantId, traceParent: context.traceParent, traceState: context.traceState }, context.metadata));
+/**
+ * Projects only operational lookup fields. Actor, tenant, arbitrary request
+ * metadata, network identity, headers, paths, query, and bodies are
+ * intentionally excluded.
+ */
+export function toLogContext(context) {
+    const projected = {
+        causationId: normalizePropagationId(context.causationId),
+        correlationId: normalizePropagationId(context.correlationId),
+        eventId: normalizePropagationId(context.eventId),
+        eventType: normalizeEventType(context.eventType),
+        requestId: normalizePropagationId(context.requestId),
+        spanId: normalizeSpanId(context.spanId),
+        traceId: normalizeTraceId(context.traceId),
+        traceParent: normalizeTraceParent(context.traceParent),
+        traceState: normalizeTraceState(context.traceState),
+    };
+    return Object.fromEntries(Object.entries(projected).filter(([, value]) => value !== undefined));
 }
 //# sourceMappingURL=request-context.js.map