@lucern/sdk 0.2.0-alpha.4 → 0.2.0-alpha.6

package/dist/lucern/contracts/src/auth.contract.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @lucern/contracts — auth (canonical support contract)
+ *
+ * Consolidated flat support surface for Lucern authentication:
+ *   - Session primitives (auth modes, principal types, lifecycle)
+ *   - AuthContext shape + McpTransportKind + LucernSdkClient alias
+ *
+ * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts
+ * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).
+ */
+export declare const SESSION_AUTH_MODES: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
+export type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
+export declare const SESSION_PRINCIPAL_TYPES: readonly ["human", "service", "agent"];
+export type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];
+export declare const SESSION_LIFECYCLE_STATUSES: readonly ["active", "expired", "revoked"];
+export type SessionLifecycleStatus = (typeof SESSION_LIFECYCLE_STATUSES)[number];
+export type SessionDelegationHop = {
+    principalId: string;
+    principalType: SessionPrincipalType;
+    authMode?: SessionAuthMode;
+    sessionId?: string;
+    delegatedAt?: number;
+    reason?: string;
+};
+export type SessionAuditOutcome = "accepted" | "rejected" | "revoked" | "expired";
+export type SessionAuditEnvelope = {
+    sessionId: string;
+    authMode: SessionAuthMode;
+    principalId: string;
+    principalType: SessionPrincipalType;
+    tenantId: string;
+    workspaceId?: string;
+    apiKeyId?: string;
+    scopes: readonly string[];
+    roles?: readonly string[];
+    delegationChain?: readonly SessionDelegationHop[];
+    sourceSessionId?: string;
+    expiresAt?: number;
+    request?: {
+        endpoint?: string;
+        method?: string;
+        correlationId?: string;
+    };
+    result?: {
+        outcome: SessionAuditOutcome;
+        reason?: string;
+    };
+};
+export declare function inferSessionPrincipalType(principalId: string): SessionPrincipalType;
+export declare function normalizeDelegationChain(args: {
+    delegationChain?: readonly SessionDelegationHop[];
+    delegatedBy?: string;
+    delegatedByType?: SessionPrincipalType;
+    delegatedAt?: number;
+    reason?: string;
+}): SessionDelegationHop[] | undefined;
+export declare function lastDelegator(delegationChain?: readonly SessionDelegationHop[]): string | undefined;
+import type { ConvexAdminClient } from "./convex-admin.contract";
+export type McpTransportKind = "stdio" | "hosted";
+export type LucernSdkClient = unknown;
+/**
+ * Session authentication context — injected by withAuth() middleware.
+ *
+ * Built from TenantConfig at dispatch time. Agent sessions get
+ * AGENT_IDENTITY + "agent:internal" role + unrestricted access.
+ * User sessions get Clerk userId + resolved role + tool ACLs.
+ */
+export type AuthContext = {
+    sessionType: "agent" | "user";
+    userId: string;
+    tenantId: string;
+    role: string;
+    allowedTopics: string[] | null;
+    groupIds: string[];
+    permittedPackKeys: string[];
+    sessionId: string;
+    principalId?: string;
+    principalType?: SessionPrincipalType;
+    workspaceId?: string;
+    scopes?: string[];
+    authMode?: SessionAuthMode;
+    roles?: string[];
+    transportKind?: McpTransportKind;
+    lucernClient?: LucernSdkClient;
+    convex?: ConvexAdminClient;
+    setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;
+    matchesWorkspaceReasoningScope?: (node: unknown, scope: unknown) => boolean;
+};

package/dist/lucern/contracts/src/auth.contract.js

@@ -0,0 +1,57 @@
+/**
+ * @lucern/contracts — auth (canonical support contract)
+ *
+ * Consolidated flat support surface for Lucern authentication:
+ *   - Session primitives (auth modes, principal types, lifecycle)
+ *   - AuthContext shape + McpTransportKind + LucernSdkClient alias
+ *
+ * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts
+ * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).
+ */
+// =============================================================================
+// SESSION PRIMITIVES
+// (Formerly src/auth-session.contract.ts)
+// =============================================================================
+export const SESSION_AUTH_MODES = [
+    "interactive_user",
+    "service_principal",
+    "tenant_api_key",
+    "session_token",
+];
+export const SESSION_PRINCIPAL_TYPES = ["human", "service", "agent"];
+export const SESSION_LIFECYCLE_STATUSES = [
+    "active",
+    "expired",
+    "revoked",
+];
+export function inferSessionPrincipalType(principalId) {
+    if (principalId.startsWith("user:")) {
+        return "human";
+    }
+    if (principalId.startsWith("agent:")) {
+        return "agent";
+    }
+    return "service";
+}
+export function normalizeDelegationChain(args) {
+    if (args.delegationChain && args.delegationChain.length > 0) {
+        return [...args.delegationChain];
+    }
+    if (!args.delegatedBy) {
+        return;
+    }
+    return [
+        {
+            principalId: args.delegatedBy,
+            principalType: args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),
+            delegatedAt: args.delegatedAt,
+            reason: args.reason,
+        },
+    ];
+}
+export function lastDelegator(delegationChain) {
+    if (!delegationChain || delegationChain.length === 0) {
+        return;
+    }
+    return delegationChain[delegationChain.length - 1]?.principalId;
+}

package/dist/lucern/contracts/src/context-pack.contract.js

@@ -0,0 +1,169 @@
+/**
+ * Context-Pack Contract v1
+ *
+ * Canonical TypeScript types and constants for the context-pack output schema.
+ * This is the external contract consumed by:
+ *   - MCP tool `compile_context` (canonical compiler read)
+ *   - SDK/HTTP consumers that read compiled context packs programmatically
+ *   - Benchmark harnesses (context-pack-ab)
+ *
+ * BREAKING CHANGE RULES:
+ *   - Adding optional fields to ContextPackV1 is NON-breaking
+ *   - Removing fields or changing types is BREAKING (bump CONTEXT_PACK_SCHEMA_VERSION)
+ *   - Changing section budget ratios or ranking weights is NON-breaking (tuning)
+ *   - Changing the version string is BREAKING (consumers check it)
+ */
+// =============================================================================
+// SCHEMA VERSION
+// =============================================================================
+/** Canonical version string. Consumers MUST check this field for compatibility. */
+export const CONTEXT_PACK_SCHEMA_VERSION = "1.0.0";
+export const CONTEXT_RANKING_PROFILES = [
+    "baseline_v1",
+    "weighted_v1",
+];
+export const DEFAULT_RANKING_PROFILE = "weighted_v1";
+export const DEFAULT_COMPILATION_MODE = "standard";
+export const CONTEXT_PACK_SECTION_KEYS = [
+    "invariants",
+    "activeBeliefs",
+    "openQuestions",
+    "recentEvidence",
+    "contradictions",
+];
+// =============================================================================
+// SECTION BUDGET RATIOS
+// =============================================================================
+/**
+ * Token budget allocation ratios per section.
+ * These sum to 1.0 and determine how the total tokenBudget is divided.
+ *
+ * Rationale:
+ * - invariants (0.28): Highest-priority constraints, injected first
+ * - activeBeliefs (0.30): Largest section, carries domain knowledge
+ * - openQuestions (0.17): Unresolved work items guide agent behavior
+ * - recentEvidence (0.17): Implementation context for grounding
+ * - contradictions (0.08): Tension signals, smallest section
+ */
+export const SECTION_BUDGET_RATIOS = {
+    invariants: 0.28,
+    activeBeliefs: 0.3,
+    openQuestions: 0.17,
+    recentEvidence: 0.17,
+    contradictions: 0.08,
+};
+// =============================================================================
+// TOKEN BUDGET CONSTRAINTS
+// =============================================================================
+/** Minimum allowed token budget. Below this, context packs lose utility. */
+export const MIN_TOKEN_BUDGET = 400;
+/** Maximum allowed token budget. Above this, context packs bloat prompts. */
+export const MAX_TOKEN_BUDGET = 8000;
+/** Default token budget when caller does not specify. */
+export const DEFAULT_TOKEN_BUDGET = 1800;
+/** Default max items per section. */
+export const DEFAULT_SECTION_LIMIT = 8;
+/** Hard ceiling on items per section. */
+export const MAX_SECTION_LIMIT = 25;
+/** Minimum contradiction section budget floor (tokens). */
+export const MIN_CONTRADICTION_BUDGET = 40;
+export const RANKING_WEIGHTS = {
+    invariants: {
+        query: 0.35,
+        recency: 0.1,
+        confidence: 0.4,
+        beliefType: 0.15,
+    },
+    activeBeliefs: {
+        query: 0.5,
+        recency: 0.2,
+        confidence: 0.2,
+        beliefType: 0.1,
+    },
+    openQuestions: {
+        query: 0.55,
+        recency: 0.2,
+        priority: 0.25,
+    },
+    recentEvidence: {
+        query: 0.6,
+        recency: 0.4,
+    },
+    contradictions: {
+        query: 0.4,
+        recency: 0.2,
+        severity: 0.4,
+    },
+};
+/** Recency decay half-life in days. After 30 days, recency score = 0.5. */
+export const RECENCY_HALF_LIFE_DAYS = 30;
+/**
+ * Ranking weight vector for the relatedEntities section.
+ * Entities are ranked by query relevance and connectivity (bridge edge count).
+ * Separate from RANKING_WEIGHTS because entities are not part of the
+ * token-budgeted injection plan.
+ */
+export const ENTITY_RANKING_WEIGHTS = {
+    query: 0.4,
+    connectivity: 0.6,
+};
+/** Default max entities to include in the context pack. */
+export const DEFAULT_ENTITY_LIMIT = 10;
+/** Hard ceiling on entities per context pack. */
+export const MAX_ENTITY_LIMIT = 50;
+// =============================================================================
+// BELIEF TYPE BONUS MAP
+// =============================================================================
+/**
+ * Bonus multiplier for belief types in ranking.
+ * Invariants get 1.0, unknown types get 0.4.
+ */
+export const BELIEF_TYPE_BONUS = {
+    invariant: 1.0,
+    tenet: 0.8,
+    principle: 0.6,
+};
+export const DEFAULT_BELIEF_TYPE_BONUS = 0.4;
+// =============================================================================
+// PRIORITY / SEVERITY SCORE MAPS
+// =============================================================================
+export const PRIORITY_SCORES = {
+    critical: 1.0,
+    high: 0.85,
+    medium: 0.55,
+    low: 0.35,
+};
+export const DEFAULT_PRIORITY_SCORE = 0.5;
+export const SEVERITY_SCORES = {
+    critical: 1.0,
+    high: 0.85,
+    medium: 0.6,
+    low: 0.35,
+};
+export const DEFAULT_SEVERITY_SCORE = 0.5;
+// =============================================================================
+// RESOLVED QUESTION STATUSES
+// =============================================================================
+/**
+ * Question statuses that are considered "resolved" (not open).
+ * Used to filter which questions appear in the openQuestions section.
+ */
+export const RESOLVED_QUESTION_STATUSES = [
+    "answered",
+    "archived",
+    "closed",
+    "resolved",
+    "resolved_support",
+    "resolved_contra",
+    "belief_forked",
+];
+// =============================================================================
+// TOKEN ESTIMATION
+// =============================================================================
+/**
+ * Tokens-per-word multiplier for rough token estimation.
+ * Conservative estimate: ~1.35 tokens per whitespace-delimited word.
+ */
+export const TOKENS_PER_WORD = 1.35;
+/** Minimum token estimate for any non-empty string. */
+export const MIN_TOKEN_ESTIMATE = 8;

package/dist/lucern/contracts/src/convex-admin.contract.d.ts

@@ -0,0 +1,5 @@
+export interface ConvexAdminClient {
+    query<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+    mutation<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+    action<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+}

package/dist/lucern/contracts/src/convex-admin.contract.js

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

package/dist/lucern/contracts/src/events-types.contract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @lucern/contracts — events-types compat shim
+ *
+ * This file consolidated into ./events.contract.ts during EK-16 T1 PR 3b.
+ * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
+ * New code should import from "@lucern/contracts" (barrel) or "./events.contract".
+ */
+export * from "./events.contract";

package/dist/lucern/contracts/src/events-types.contract.js

@@ -0,0 +1,8 @@
+/**
+ * @lucern/contracts — events-types compat shim
+ *
+ * This file consolidated into ./events.contract.ts during EK-16 T1 PR 3b.
+ * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
+ * New code should import from "@lucern/contracts" (barrel) or "./events.contract".
+ */
+export * from "./events.contract.js";

package/dist/lucern/{packages/events/src/types.d.ts → contracts/src/events.contract.d.ts}

@@ -1,3 +1,14 @@
+/**
+ * @lucern/contracts — events (canonical support contract)
+ *
+ * Consolidated flat support surface for Lucern's domain event stream:
+ *   - Event type definitions, constants, and shared enums
+ *   - Event construction + cursor helpers
+ *
+ * Consolidated from the former split type-definition module
+ * and the prior src/events.contract.ts (helpers) in EK-16 T1 PR 3b.
+ * Compat shim remains at the old events-types path until Lucern 1.0.0 (D12).
+ */
 export declare const DOMAIN_EVENT_VERSION: "1.0";
 export declare const EVENT_RETENTION_DEFAULT_DAYS = 30;
 export declare const WEBHOOK_MAX_ATTEMPTS = 5;
@@ -149,3 +160,17 @@ export type ReplayEventsResult = EventListResult & {
     replayedDeliveries?: number;
     replayedWebhookId?: string;
 };
+export declare function createEventId(): string;
+export declare function normalizeRetentionDays(value: number | undefined): number;
+export declare function buildDomainEvent(input: CreateDomainEventInput): DomainEvent;
+export declare function compareEventCursor(left: EventCursor, right: EventCursor): number;
+export declare function encodeEventCursor(cursor: EventCursor): string;
+export declare function decodeEventCursor(cursor: string | undefined): EventCursor | null;
+export declare function isAfterCursor(event: Pick<DomainEvent, "timestamp" | "eventId">, cursor: EventCursor | null): boolean;
+export declare function sortEventsByCursor<T extends Pick<DomainEvent, "timestamp" | "eventId">>(events: readonly T[]): T[];
+export declare function inferActorType(args: {
+    sessionType?: "agent" | "user";
+    authMode?: string;
+    principalType?: string;
+}): DomainActorType;
+export declare function emitDomainEvent(invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>, input: CreateDomainEventInput): Promise<unknown>;

package/dist/lucern/contracts/src/events.contract.js

@@ -0,0 +1,159 @@
+/**
+ * @lucern/contracts — events (canonical support contract)
+ *
+ * Consolidated flat support surface for Lucern's domain event stream:
+ *   - Event type definitions, constants, and shared enums
+ *   - Event construction + cursor helpers
+ *
+ * Consolidated from the former split type-definition module
+ * and the prior src/events.contract.ts (helpers) in EK-16 T1 PR 3b.
+ * Compat shim remains at the old events-types path until Lucern 1.0.0 (D12).
+ */
+// =============================================================================
+// EVENT TYPE DEFINITIONS & CONSTANTS
+// (Formerly the split events type-definition module)
+// =============================================================================
+export const DOMAIN_EVENT_VERSION = "1.0";
+export const EVENT_RETENTION_DEFAULT_DAYS = 30;
+export const WEBHOOK_MAX_ATTEMPTS = 5;
+export const WEBHOOK_RETRY_DELAYS_MS = [1_000, 5_000, 30_000, 300_000];
+export const DOMAIN_EVENT_TYPES = [
+    "belief.created",
+    "belief.forked",
+    "belief.confidence_updated",
+    "belief.archived",
+    "belief.refined",
+    "belief.contract_created",
+    "belief.contract_evaluated",
+    "belief.lineage_queried",
+    "evidence.created",
+    "evidence.linked",
+    "evidence.search_executed",
+    "question.created",
+    "question.answered",
+    "question.refined",
+    "question.status_updated",
+    "question.archived",
+    "edge.created",
+    "contradiction.flagged",
+    "worktree.created",
+    "worktree.activated",
+    "worktree.merged",
+    "worktree.targets_updated",
+    "worktree.metadata_updated",
+    "topic.created",
+    "topic.updated",
+    "topic.archived",
+    "task.created",
+    "task.completed",
+    "task.updated",
+    "ontology.bound",
+    "context.compiled",
+    "identity.key_created",
+    "identity.key_rotated",
+    "identity.key_revoked",
+    "webhook.test",
+];
+// =============================================================================
+// EVENT HELPERS
+// (Formerly the body of src/events.contract.ts)
+// =============================================================================
+function toBase64(value) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(value, "utf8").toString("base64url");
+    }
+    return btoa(unescape(encodeURIComponent(value)))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+}
+function fromBase64(value) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(value, "base64url").toString("utf8");
+    }
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    return decodeURIComponent(escape(atob(normalized)));
+}
+export function createEventId() {
+    const random = crypto.randomUUID().replace(/-/g, "");
+    return `evt_${random}`;
+}
+export function normalizeRetentionDays(value) {
+    if (!Number.isFinite(value) || typeof value !== "number" || value <= 0) {
+        return EVENT_RETENTION_DEFAULT_DAYS;
+    }
+    return Math.max(1, Math.trunc(value));
+}
+export function buildDomainEvent(input) {
+    const timestamp = input.timestamp ?? Date.now();
+    const retentionDays = normalizeRetentionDays(input.retentionDays);
+    return {
+        eventId: input.eventId?.trim() || createEventId(),
+        type: input.type.trim(),
+        version: DOMAIN_EVENT_VERSION,
+        timestamp,
+        tenantId: input.tenantId?.trim() || undefined,
+        workspaceId: input.workspaceId?.trim() || undefined,
+        topicId: input.topicId.trim(),
+        resourceId: input.resourceId.trim(),
+        resourceType: input.resourceType.trim(),
+        actorId: input.actorId.trim(),
+        actorType: input.actorType,
+        data: input.data ?? {},
+        correlationId: input.correlationId?.trim() || undefined,
+        expiresAt: timestamp + retentionDays * 24 * 60 * 60 * 1000,
+    };
+}
+export function compareEventCursor(left, right) {
+    if (left.timestamp !== right.timestamp) {
+        return left.timestamp - right.timestamp;
+    }
+    return left.eventId.localeCompare(right.eventId);
+}
+export function encodeEventCursor(cursor) {
+    return toBase64(JSON.stringify(cursor));
+}
+export function decodeEventCursor(cursor) {
+    if (!cursor || cursor.trim().length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fromBase64(cursor.trim()));
+        if (typeof parsed.timestamp !== "number" ||
+            !Number.isFinite(parsed.timestamp) ||
+            typeof parsed.eventId !== "string" ||
+            parsed.eventId.trim().length === 0) {
+            return null;
+        }
+        return {
+            timestamp: parsed.timestamp,
+            eventId: parsed.eventId.trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isAfterCursor(event, cursor) {
+    if (!cursor) {
+        return true;
+    }
+    return compareEventCursor(event, cursor) > 0;
+}
+export function sortEventsByCursor(events) {
+    return [...events].sort((left, right) => compareEventCursor(left, right));
+}
+export function inferActorType(args) {
+    if (args.sessionType === "agent") {
+        return "agent";
+    }
+    if (args.authMode === "service_principal" ||
+        args.authMode === "tenant_api_key" ||
+        args.principalType === "service") {
+        return "service";
+    }
+    return "human";
+}
+export async function emitDomainEvent(invokeMutation, input) {
+    return await invokeMutation("events:recordEvent", input);
+}

package/dist/lucern/contracts/src/gateway.contract.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Gateway contract types — shared between Stack's gateway middleware and
+ * Lucern's server-core / gateway route handlers.
+ *
+ * These types describe the authenticated request context that flows from
+ * the gateway into Lucern route handlers. The gateway (Stack-side) creates
+ * the context; Lucern consumes it read-only.
+ *
+ * @module @lucern/contracts/src/gateway
+ */
+import type { SessionAuthMode, SessionDelegationHop, SessionPrincipalType } from "./auth-session.contract";
+export type PlatformApiErrorCode = "AUTH_REQUIRED" | "AUTHENTICATION_REQUIRED" | "AUTH_TOKEN_MISSING" | "INVALID_REQUEST" | "IDEMPOTENCY_KEY_REQUIRED" | "FORBIDDEN" | "SCOPE_INSUFFICIENT" | "ENVIRONMENT_MISMATCH" | "KEY_EXPIRED" | "KEY_REVOKED" | "RATE_LIMIT_EXCEEDED" | "NOT_FOUND" | "CONFLICT" | "UPSTREAM_ERROR" | "INTERNAL_ERROR";
+export type GatewayScope = {
+    tenantId?: string;
+    workspaceId?: string;
+};
+export type GatewayEnvironment = "sandbox" | "production";
+export type GatewayAuthMode = "interactive_user" | "service_principal" | "tenant_api_key" | "session_token";
+export type KeyLifecycleStatus = "active" | "rotating" | "rotated" | "expired" | "revoked";
+export type CutoverDomain = "graph" | "schema" | "identity" | "policy" | "audit" | "admin" | "agent" | "tool" | "prompt" | "intelligence";
+export type CutoverFlagState = "legacy" | "cutover" | "disabled";
+/**
+ * Authenticated request context created by the gateway middleware.
+ * Lucern route handlers receive this as a read-only parameter.
+ *
+ * The `convex` field is typed as `unknown` in the contract because Lucern
+ * consumers should not use the gateway's Convex client directly — they
+ * have their own kernel client. The gateway (Stack-side) narrows this to
+ * `ConvexHttpClient` at the construction site.
+ */
+export type GatewayAuthContext = {
+    userId: string;
+    convexToken?: string;
+    /** Opaque in contract — narrowed to ConvexHttpClient at the gateway. */
+    convex: any;
+    authMode: GatewayAuthMode;
+    principalId?: string;
+    principalType?: SessionPrincipalType;
+    tenantId?: string;
+    workspaceId?: string;
+    roles?: string[];
+    sessionId?: string;
+    sessionAuthMode?: SessionAuthMode;
+    sessionExpiresAt?: number;
+    delegationChain?: SessionDelegationHop[];
+    servicePrincipalId?: string;
+    servicePrincipalKeyId?: string;
+    servicePrincipalTenantId?: string;
+    servicePrincipalWorkspaceId?: string;
+    requestEnvironment: GatewayEnvironment;
+    keyEnvironment?: GatewayEnvironment;
+    keyStatus: KeyLifecycleStatus | "unknown";
+    grantedScopes: Set<string>;
+    cutoverDomain: CutoverDomain;
+    cutoverState: CutoverFlagState;
+};
+export type GatewayErrorArgs = {
+    code: PlatformApiErrorCode;
+    message: string;
+    status: number;
+    correlationId: string;
+    policyTraceId?: string;
+    invariant?: string;
+    suggestion?: string;
+    details?: unknown;
+    headers?: HeadersInit;
+};
+export type GatewaySuccessArgs = {
+    status?: number;
+    correlationId: string;
+    policyTraceId?: string;
+    idempotentReplay?: boolean;
+};
+export declare function requireActorPrincipalId(authContext: GatewayAuthContext): string;

package/dist/lucern/contracts/src/gateway.contract.js

@@ -0,0 +1,19 @@
+/**
+ * Gateway contract types — shared between Stack's gateway middleware and
+ * Lucern's server-core / gateway route handlers.
+ *
+ * These types describe the authenticated request context that flows from
+ * the gateway into Lucern route handlers. The gateway (Stack-side) creates
+ * the context; Lucern consumes it read-only.
+ *
+ * @module @lucern/contracts/src/gateway
+ */
+export function requireActorPrincipalId(authContext) {
+    const principalId = typeof authContext.principalId === "string"
+        ? authContext.principalId.trim()
+        : "";
+    if (principalId.length > 0) {
+        return principalId;
+    }
+    throw new Error("Access denied: federated principal context required.");
+}

package/dist/lucern/contracts/src/ids.contract.js

@@ -0,0 +1,24 @@
+const PREFIXED_ID_PATTERN = /^([a-z][a-z0-9]*)_(.+)$/;
+export function encodePrefixedId(prefix, value) {
+    const normalizedPrefix = prefix.trim();
+    const normalizedValue = value.trim();
+    if (!normalizedPrefix || !normalizedValue) {
+        throw new Error("Both prefix and value are required to encode a prefixed ID.");
+    }
+    return `${normalizedPrefix}_${normalizedValue}`;
+}
+export function decodePrefixedId(id) {
+    const normalized = id.trim();
+    const match = PREFIXED_ID_PATTERN.exec(normalized);
+    if (!match) {
+        throw new Error(`Invalid prefixed ID: ${id}`);
+    }
+    return {
+        prefix: match[1],
+        value: match[2],
+    };
+}
+export function hasPrefixedIdPrefix(id, prefix) {
+    const decoded = decodePrefixedId(id);
+    return decoded.prefix === prefix.trim();
+}