@cosmicdrift/kumiko-framework 0.397.0 → 0.399.0

package/agents/api/framework-errors.md

@@ -0,0 +1,119 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/errors/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/errors
+
+Import from `@cosmicdrift/kumiko-framework/errors`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function failNotFound(entity: string, id?: number | string): WriteFailure;
+function failTransition(from: string, to: string, allowed: string[]): WriteFailure; // Convenience for state-transition rejects: produces a WriteFailure with reason="invalid_transition", a structured `from`/`to`/`allowed` detail block, and a readable message.
+function failUnprocessable(reason: string, details?: Readonly<Record<string, unknown>> & { reason?: never; }): WriteFailure;
+function isKumikoError(e: unknown): e is KumikoError;
+function reraiseAsKumikoError(info: WriteErrorInfo): KumikoError;
+function subjectErasedConflict(cause?: unknown): ConflictError;
+function validationErrorFromZod(error: ZodError): ValidationError;
+function writeFailure(err: KumikoError): WriteFailure;
+```
+
+## Constants
+
+```ts
+const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
+```
+
+## Classes
+
+```ts
+class AccessDeniedError extends KumikoError {
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+  code: unknown;
+  httpStatus: unknown;
+}
+class ConflictError extends KumikoError {
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+  code: string;
+  httpStatus: unknown;
+}
+class FeatureDisabledError extends KumikoError {
+  constructor(feature: string, handler: string, opts?: Pick<ErrorOpts, "cause">);
+  code: unknown;
+  httpStatus: unknown;
+}
+class InternalError extends KumikoError {
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+  code: unknown;
+  httpStatus: unknown;
+}
+class KumikoError extends Error {
+  constructor(input: ErrorCtorInput);
+  code: string;
+  httpStatus: number;
+  i18nKey: string;
+  i18nParams: Readonly<Record<string, unknown>> | undefined;
+  details: unknown;
+  retryAfterSeconds: number | undefined;
+}
+class NotFoundError extends KumikoError {
+  constructor(entity: string, id?: string | number, opts?: Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause">);
+  code: unknown;
+  httpStatus: unknown;
+}
+class RateLimitError extends KumikoError {
+  constructor(details: RateLimitDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+  code: unknown;
+  httpStatus: unknown;
+  details: RateLimitDetails;
+}
+class UnconfiguredError extends UnprocessableError {
+  constructor(details: UnconfiguredDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+  code: string;
+}
+class UniqueViolationError extends ConflictError {
+  constructor(details: UniqueViolationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+  code: string;
+}
+class UnprocessableError extends KumikoError {
+  constructor(reason: string, opts?: UnprocessableOpts);
+  code: string;
+  httpStatus: unknown;
+}
+class ValidationError extends KumikoError {
+  constructor(details: ValidationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+  code: unknown;
+  httpStatus: unknown;
+}
+class VersionConflictError extends ConflictError {
+  constructor(details: VersionConflictDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+  code: string;
+}
+```
+
+## Types
+
+```ts
+type ErrorDocsConfig = { // Links an app's own error reasons to its own docs; uncovered reasons fall back to the framework page of the error code.
+  baseUrl: string;
+  reasons?: string[] | "all";
+};
+type FieldIssue = {
+  path: string;
+  code: string;
+  i18nKey: string;
+  params?: Readonly<Record<string, unknown>>;
+};
+type WriteErrorInfo = {
+  code: string;
+  httpStatus: number;
+  i18nKey: string;
+  i18nParams?: Readonly<Record<string, unknown>>;
+  message: string;
+  details?: unknown;
+  retryAfterSeconds?: number;
+};
+type WriteFailure = {
+  isSuccess: false;
+  error: WriteErrorInfo;
+};
+```

package/agents/api/framework-event-store.md

@@ -0,0 +1,99 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/event-store/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/event-store
+
+Import from `@cosmicdrift/kumiko-framework/event-store`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function append(db: DbRunner, event: EventToAppend): Promise<StoredEvent>;
+function appendEventInTenantDb(tenantDb: TenantDb, event: Omit<EventToAppend, "tenantId">, options?: AppendEventInTenantDbOptions): Promise<StoredEvent>;
+function appendProvenanceEvent(db: TenantDb, event: ProvenanceEventInput): Promise<void>;
+function archiveStream(db: DbRunner, args: ArchiveStreamArgs): Promise<void>;
+function assertSeedModeNotInProduction(env?: Readonly<Record<string, string | undefined>>): void;
+function backfillEventPiiEncryption(db: DbRunner, registry: Registry, options?: PiiBackfillOptions): Promise<PiiBackfillResult>;
+function backfillEventPiiEncryptionBatch(db: DbRunner, registry: Registry, options?: PiiBackfillBatchOptions): Promise<PiiBackfillBatchResult>;
+function createArchivedStreamsTable(db: DbConnection): Promise<void>;
+function createEventsTable(db: DbConnection): Promise<void>;
+function deleteRowsWithoutReplayableStream(db: AnyDb, args: DeleteRowsWithoutReplayableStreamArgs): Promise<string[]>;
+function getEventsHighWaterMark(db: DbRunner): Promise<bigint>;
+function getStreamVersion(db: DbRunner, aggregateId: string, tenantId: TenantId): Promise<number>;
+function getStreamVersionInTenantDb(tenantDb: TenantDb, aggregateId: string): Promise<number>;
+function getStreamVersions(db: DbRunner, aggregateIds: string[], tenantId: TenantId): Promise<Map<string, number>>;
+function getUnscopedAggregateStreamMaxVersion(db: DbRunner, aggregateId: string): Promise<number>; // MAX(version) for one aggregate — no tenant filter.
+function getUnscopedStreamMaxVersionForSeed(...args: Parameters<typeof getUnscopedAggregateStreamMaxVersion>): ReturnType<typeof getUnscopedAggregateStreamMaxVersion>; // Seed/orphan helper — prefer this over importing the restricted existence-oracle by name.
+function isSeedModeEnabled(env?: Readonly<Record<string, string | undefined>>): boolean;
+function isStreamArchived(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<boolean>;
+function loadAggregate(db: DbRunner, aggregateId: string, tenantId: TenantId, options?: { includeArchived?: boolean; aggregateType?: string; atVersion?: number; }): Promise<StoredEvent[]>;
+function makeUpcastCtx(db: DbRunner, tenantId: TenantId): EventUpcastCtx;
+function runSeedWritesAt<T>(createdAt: Temporal.Instant, fn: () => Promise<T>): Promise<T>; // Runs `fn` so that every event appended inside it (through the normal write path: handlers, validation, projections) is stored with `createdAt` instead of the database `now()`.
+function streamAllEventsByType(db: DbRunner, aggregateType: string, batchSize?, signal?: AbortSignal): AsyncIterable<StoredEvent>;
+function transferAggregateStreams(db: DbRunner, args: TransferAggregateStreamsArgs): Promise<number>;
+function upcastStoredEvent(event: StoredEvent, upcasters: EventUpcasters, ctx: EventUpcastCtx): Promise<StoredEvent>;
+```
+
+## Constants
+
+```ts
+const AGGREGATE_TRANSFERRED_EVENT_TYPE: "kumiko:system:aggregate.transferred";
+const AGGREGATE_TRANSFER_STREAM_TYPE: "aggregate-transfer";
+const APP_INSTANCE_STREAM_TYPE: "app-instance";
+const APP_STARTED_EVENT_TYPE: "kumiko:system:app.started";
+const SEED_MODE_ENV: "KUMIKO_TEST_SEED";
+const archivedStreamsTable: WritableSchemaTable;
+const eventsTable: WritableSchemaTable;
+const snapshotsTable: WritableSchemaTable;
+const upcasterDeadLetterTable: WritableSchemaTable;
+```
+
+## Classes
+
+```ts
+class SeedModeDisabledError extends Error {
+  constructor(message: string);
+}
+class SeedTimeOrderError extends Error {
+  constructor(aggregateType: string, aggregateId: string, version: number, seedCreatedAt: Temporal.Instant, predecessorCreatedAt: Temporal.Instant);
+  aggregateType: string;
+  aggregateId: string;
+  version: number;
+  seedCreatedAt: Temporal.Instant;
+  predecessorCreatedAt: Temporal.Instant;
+}
+class VersionConflictError extends Error {
+  constructor(aggregateId: string, expectedVersion: number, currentVersion?: number);
+  aggregateId: string;
+  expectedVersion: number;
+  currentVersion: number | undefined;
+}
+```
+
+## Types
+
+```ts
+type EventMetadata = {
+  userId: string;
+  requestId?: string;
+  correlationId?: string;
+  causationId?: string;
+  idempotencyKey?: string;
+  headers?: Readonly<Record<string, string | number | boolean>>;
+  feature?: string;
+  handler?: string;
+  writeOrigin?: WriteOrigin;
+};
+type StoredEvent<TPayload = Record<string, unknown>> = {
+  id: string;
+  aggregateId: string;
+  aggregateType: string;
+  tenantId: TenantId;
+  version: number;
+  type: string;
+  eventVersion: number;
+  payload: TPayload;
+  metadata: EventMetadata;
+  createdAt: Temporal.Instant;
+  createdBy: string;
+};
+```

package/agents/api/framework-seeding.md

@@ -0,0 +1,26 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/seeding/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/seeding
+
+Import from `@cosmicdrift/kumiko-framework/seeding`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function createTestUser(overrides?: Partial<Omit<SessionUser, "id">> & { id?: string | number; }): SessionUser;
+function runEventStoreSeed<TId extends string | number = string, TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>>(opts: RunEventStoreSeedOptions<TId, TExisting>): Promise<{ id: TId; }>; // Shared create-or-skip/update path for event-store boot-seed helpers.
+function testTenantId(n: number): TenantId;
+function testUserId(n: number): string;
+```
+
+## Constants
+
+```ts
+const TestUsers: { admin; systemAdmin; user; driver; otherTenant };
+```
+
+## Types
+
+```ts
+type SeedIfExists = "skip" | "update"; // Boot-seed semantics for event-sourced entity helpers.
+```