apps 0.0.1-beta.4 → 0.0.1-beta.5

package/types/apps/src/contracts/storage.d.ts

@@ -2,7 +2,7 @@
 import { Schema, type Effect } from "effect";
 import type { RowMetadata, ReadTable, WriteTable } from "../../../app-data/src/index.js";
 import type { Fields, ObjectValue } from "../implementation/schema.js";
-import type { DatabaseSchema, DatabaseSession, AppDatabaseError } from "../../../app-data/src/contracts/database.js";
+import type { DatabaseSchema, DatabaseSession, DatabaseError } from "../../../app-data/src/contracts/database.js";
 /** Names for authored operations and tables. */
 export declare const StorageName: Schema.NonEmptyString;
 declare const AppStorageUnavailable_base: Schema.Class<AppStorageUnavailable, Schema.TaggedStruct<"AppStorageUnavailable", {}>, import("effect/Cause").YieldableError>;
@@ -15,8 +15,8 @@ export declare class AppStorageError extends AppStorageError_base {
 }
 /** The adapter owns the database connection and transaction for the whole authored invocation. */
 export interface AppStorage {
-    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
-    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
 }
 type InputValue<F extends Fields> = {
     readonly [K in keyof F as F[K]["optionalValue"] extends true ? never : F[K] extends {

package/types/apps/src/contracts/workflows.d.ts

@@ -24,14 +24,33 @@ export declare const WorkflowStepOptions: Schema.Struct<{
     readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
 }>;
 export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+/**
+ * Where and why a run failed: the failing step and the error the app's own code raised, its
+ * message bounded and with account secrets replaced. Runs from before these fields existed have none.
+ */
+export declare const WorkflowFailureDetail: {
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};
+/** A failed run's recorded step and app error. */
+export declare const WorkflowRunFailure: Schema.Struct<{
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+}>;
+export type WorkflowRunFailure = typeof WorkflowRunFailure.Type;
 declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
     readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
     readonly retryable: Schema.Boolean;
+    readonly step: Schema.optionalKey<Schema.String>;
+    readonly errorName: Schema.optionalKey<Schema.String>;
+    readonly message: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures cross host boundaries without authored exceptions or account fields. */
+/** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
 }
-/** Explicitly stop retrying an authored step. Its message stays inside the app runtime. */
+/** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {
     readonly name = "NonRetryableError";
 }
@@ -45,7 +64,7 @@ export declare const HostedWorkflow: Schema.Struct<{
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type HostedWorkflow = typeof HostedWorkflow.Type;
-/** Results are available only on completed runs; failure details are safe reason codes. */
+/** Results are available only on completed runs; failures carry a reason code and app error detail. */
 export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
@@ -66,6 +85,12 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    /** The failing step and the app's own error, when the run recorded them. */
+    readonly failure: Schema.optionalKey<Schema.Struct<{
+        step: Schema.optionalKey<Schema.String>;
+        errorName: Schema.optionalKey<Schema.String>;
+        message: Schema.optionalKey<Schema.String>;
+    }>>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
@@ -104,6 +129,12 @@ export declare const WorkflowRunPage: Schema.Struct<{
     }>, Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+        /** The failing step and the app's own error, when the run recorded them. */
+        readonly failure: Schema.optionalKey<Schema.Struct<{
+            step: Schema.optionalKey<Schema.String>;
+            errorName: Schema.optionalKey<Schema.String>;
+            message: Schema.optionalKey<Schema.String>;
+        }>>;
         readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;

package/types/apps/src/implementation/elicitation.d.ts

@@ -66,10 +66,10 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 } | {
                     readonly type: "number" | "integer";
                     readonly default?: number;
+                    readonly maximum?: number;
                     readonly description?: string;
                     readonly title?: string;
                     readonly minimum?: number;
-                    readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
                     readonly default?: boolean;

package/types/apps/src/implementation/failure-detail.d.ts

@@ -0,0 +1,25 @@
+import { Redacted } from "effect";
+import type { ResolvedAccounts } from "../contracts/host.js";
+/** Fields of `FailureDetail` as constructor input. */
+export interface FailureDetail {
+    readonly source?: "app" | "storage" | "service";
+    readonly errorName?: string;
+    readonly code?: string;
+    readonly message?: string;
+}
+/**
+ * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
+ * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ */
+export declare const accountFieldSecrets: (accounts: unknown) => string[];
+/** Every credential field value of an invocation's selected accounts. */
+export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
+/** Replace account secrets and bound the message for the runtime boundary. */
+export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/** `Name: message` for any thrown value, before redaction. */
+export declare const describeFailure: (error: unknown) => string;
+/**
+ * Describe what an operation raised for the app's own caller. App data failures keep their
+ * reason as a code; any other thrown value is the app's own error. Account secrets are replaced.
+ */
+export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

package/types/apps/src/implementation/storage.d.ts

@@ -1,10 +1,12 @@
-import { type DatabaseSession } from "../../../app-data/src/index.js";
+import { type DatabaseSession, type reservedFieldNames } from "../../../app-data/src/index.js";
+type ReservedFieldName = (typeof reservedFieldNames)[number];
 import { type AppStorage } from "../contracts/storage.js";
 import type { DatabaseDefinition, Database, Table, Tables } from "../contracts/storage.js";
 import { type Fields } from "./schema.js";
 export type { DatabaseDefinition, Database, DatabaseReader, Table, Tables, RowOf, } from "../contracts/storage.js";
-/** Declare scalar columns using the same schemas as operation inputs. */
-export declare const table: <const F extends Fields>(fields: F) => Table<F>;
+/** Declare scalar columns using the same schemas as operation inputs. The host adds `id`,
+ * `createdAt` and `updatedAt` to every row, so tables cannot declare those names. */
+export declare const table: <const F extends Fields & { readonly [K in ReservedFieldName]?: never; }>(fields: F) => Table<F>;
 /** Build a fresh Promise database facade for one authorized invocation. */
 export declare const authorDatabase: <T extends Tables>(tables: T, session: DatabaseSession, signal: AbortSignal, writable: boolean) => Database<T>;
 /** Declare storage independently of handlers; the host binds each invocation's database. */

package/types/apps/src/implementation/webhooks.d.ts

@@ -26,4 +26,4 @@ export declare const dispatchWebhook: <Context extends {
         readonly [x: string]: string;
     };
     readonly body: string;
-}, HostDeclarationInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+}, HostOperationNotFound | HostInputInvalid | HostOutputInvalid | HostDeclarationInvalid | HostOperationFailed, never>;

package/types/apps/src/implementation/workflow-context.d.ts

@@ -2,7 +2,15 @@
 import { Effect } from "effect";
 import type { AppDefinition } from "../contracts/app.js";
 import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext } from "../contracts/workflows.js";
-/** Preserve typed failures and cancellation; authored exception text never leaves the app. */
-export declare const workflowSafe: <A>(work: Effect.Effect<A, unknown>) => Effect.Effect<A, WorkflowFailure>;
+/**
+ * Preserve typed failures and cancellation. Other errors keep their name and bounded message,
+ * with the given account secrets replaced.
+ */
+export declare const workflowSafe: <A>(work: Effect.Effect<A, unknown>, secrets: readonly string[]) => Effect.Effect<A, WorkflowFailure>;
 /** Construct one replay's Promise context. Step callbacks acquire fresh capabilities per actual attempt. */
-export declare const makeWorkflowContext: (execution: WorkflowExecution, definition: Pick<AppDefinition<never>, "queries" | "mutations">, fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<WorkflowStepContext, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;
+export declare const makeWorkflowContext: (execution: WorkflowExecution, definition: Pick<AppDefinition<never>, "queries" | "mutations">, 
+/** A step attempt's context, and the raw account secrets its failures must not reveal. */
+fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<{
+    readonly context: WorkflowStepContext;
+    readonly secrets: readonly string[];
+}, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;