@oddington/sdk 0.1.20 → 0.1.22

package/dist/types/packages/sdk/src/public.d.ts

@@ -2,7 +2,7 @@ import type { AskInput, CapturedRecords, DigestInput, InboxFile, PublicationRequ
 import type { FileAddOptions } from '../../../shared/inbox-files.js';
 import type { RecordReadInput } from '../../../shared/record-capture.js';
 import type { RecordDeleteRequest, RecordUpdateRequest, RecordWriteRequest } from '../../../shared/record-write.js';
-export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput, RoutineRuntime, RoutineArtifactInput, RoutineArtifact } from './routine-definition-types.js';
+export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput, RoutineRuntime, RoutineAccess, RoutineCapabilities, RoutineStep, RoutineSteps, RoutineStepInput, RoutineStepResult, RoutineStepOutput, RoutineArtifactInput, RoutineArtifact } from './routine-definition-types.js';
 export declare const defineRoutine: import('./routine-definition-types.js').DefineRoutine;
 export declare const schema: import('./routine-definition-types.js').RoutineSchemaBuilders;
 export declare const file: import('./routine-definition-types.js').RoutineFileSchema;
@@ -84,53 +84,105 @@ export declare const auth: {
 /** Customer-owned module augmentation supplies types, never runtime authority. */
 export interface AppRoutineTypes {
 }
-export type AppRoutineErrorReason = 'not_enabled' | 'authority_unavailable' | 'execution_unavailable' | 'invalid_input';
+/** Generated app declarations derive inference directly from the authored export. */
+export type RoutineAppBinding<Definition> = Definition extends import('./routine-definition-types.js').RoutineDefinition<infer Input extends import('./routine-definition-types.js').RoutineSchema<unknown> | undefined, infer Steps extends import('./routine-definition-types.js').RoutineSteps, infer Result extends import('./routine-definition-types.js').RoutineSchema<unknown> | undefined, any, any, any> ? Omit<AppRoutineBinding<import('./routine-definition-types.js').RoutineSchemaValue<Input>, import('./routine-definition-types.js').RoutineSchemaValue<Result>, {
+    [Key in keyof Steps]: Awaited<ReturnType<Steps[Key]['run']>>;
+}>, 'run'> & {
+    run(...input: Input extends undefined | import('./routine-definition-types.js').RoutineSchema<unknown, true> ? [input?: Input extends undefined ? Record<string, never> : import('./routine-definition-types.js').RoutineSchemaValue<Input>] : [input: import('./routine-definition-types.js').RoutineSchemaValue<Input>]): Promise<AppRoutineHandle<import('./routine-definition-types.js').RoutineSchemaValue<Result>, {
+        [Key in keyof Steps]: Awaited<ReturnType<Steps[Key]['run']>>;
+    }>>;
+} : never;
+export type AppRoutineErrorReason = 'authority_unavailable' | 'execution_unavailable' | 'invalid_input';
 export declare class AppRoutineError extends Error {
     readonly reason: AppRoutineErrorReason;
     constructor(reason: AppRoutineErrorReason);
 }
-export type AppRoutineEvent<Result, Steps> = {
-    type: 'started';
-} | {
-    [Key in Extract<keyof Steps, string>]: {
-        type: 'step';
-        id: Key;
-    } & (Steps[Key] extends undefined ? {
-        summary?: undefined;
+export type AppRoutineHandle<Result, Steps> = {
+    current(): Promise<Omit<RunSummary, 'result'> & {
+        result?: Result;
+    }>;
+    watch(): AsyncIterable<Omit<RunSummary, 'result'> & {
+        result?: Result;
+    }>;
+    step<Key extends Extract<keyof Steps, string>>(id: Key): Promise<Omit<StepDetail, 'summary' | 'data'> & (Steps[Key] extends {
+        summary: infer Summary;
+        data?: infer Data;
+    } ? {
+        summary?: Summary;
+        data?: Data;
     } : {
-        summary: Steps[Key];
-    });
-}[Extract<keyof Steps, string>] | ({
-    type: 'finished';
-    state: 'succeeded';
-} & ([Result] extends [undefined] ? {
-    result?: undefined;
-} : {
-    result: Result;
-})) | {
-    type: 'finished';
+        summary?: unknown;
+        data?: unknown;
+    })>;
+    publish(): Promise<Omit<RunSummary, 'result'> & {
+        result?: Result;
+    }>;
+};
+export type LocalPublication = {
+    state: 'not_needed' | 'ready' | 'published';
+} | {
     state: 'failed';
-    error: 'execution_failed';
+    message: string;
+};
+export type StepDetail = {
+    id: string;
+    title: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+    startedAt?: string;
+    finishedAt?: string;
+    summary?: unknown;
+    data?: unknown;
+};
+export type RunSummary = {
+    id: string;
+    routine: string;
+    placement: 'local' | 'remote';
+    status: 'queued' | 'running' | 'succeeded' | 'failed';
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    steps: Array<Omit<StepDetail, 'data'> & {
+        detailAvailable: boolean;
+    }>;
+    result?: unknown;
+    failure?: {
+        message: string;
+    };
+    publication?: LocalPublication;
+};
+export type RunHandle = {
+    current(): Promise<RunSummary>;
+    watch(): AsyncIterable<RunSummary>;
+    step(id: string): Promise<StepDetail>;
+    publish(): Promise<RunSummary>;
+};
+export type RoutineReadiness = {
+    state: 'ready';
+    placement: 'local' | 'remote';
 } | {
-    type: 'finished';
-    state: 'cancelled';
+    state: 'unavailable';
+    reason: 'not_deployed' | 'definition_invalid' | 'capability_unavailable';
+    message: string;
 };
-export type AppRoutineHandle<Result, Steps> = {
-    events(): AsyncIterable<AppRoutineEvent<Result, Steps>>;
-    cancel(): Promise<void>;
+export type RoutineDescription = Omit<import('../../../shared/app-descriptor.js').AppRoutineDescriptor, 'connections'> & {
+    connections: Array<{
+        id: string;
+        provider: string;
+        name: string;
+        available: boolean;
+    }>;
+    readiness: RoutineReadiness;
 };
 export type AppRoutineBinding<Input, Result, Steps> = {
-    availability(): Promise<{
-        available: true;
-        steps: Extract<keyof Steps, string>[];
-    } | {
-        available: false;
-        reason: 'not_enabled' | 'authority_unavailable' | 'execution_unavailable';
-    }>;
+    describe(): Promise<RoutineDescription>;
     run(input: Input): Promise<AppRoutineHandle<Result, Steps>>;
-    recover(): Promise<AppRoutineHandle<Result, Steps>[]>;
+    runs: {
+        list(): Promise<RunSummary[]>;
+        get(id: string): Promise<RunHandle>;
+    };
 };
 export declare const app: {
+    listRoutines(): Promise<RoutineDescription[]>;
     routines: AppRoutineTypes;
 };
 /** A declared stage without a summary takes no second argument. */

package/dist/types/packages/sdk/src/routine-definition-types.d.ts

@@ -2,14 +2,32 @@ import type { AppValueSchema } from '../../../shared/app-routine-contract.js';
 import type { File } from '../../../shared/files-contract.js';
 import type { Connections } from '../../../shared/airtable-contract.js';
 import type { DataRepository } from '../../../shared/data-contract.js';
+import type { Handler } from '../../../shared/inbox-contract.js';
 import type { files, RoutinePublicationClient } from './public.js';
+import type { RoutineAccess } from '../../../shared/routine-definition-contract.js';
+export type { RoutineAccess } from '../../../shared/routine-definition-contract.js';
 declare const valueType: unique symbol;
 /** Serializable declaration; the phantom type never carries authority. */
-export type RoutineSchema<Value> = AppValueSchema & {
+export type RoutineSchema<Value, Defaulted extends boolean = boolean> = AppValueSchema & {
     readonly [valueType]?: Value;
+    default(value: Value): RoutineSchema<Value, true>;
+    readonly hasDefault?: Defaulted;
 };
 export type RoutineSchemaValue<Schema> = Schema extends RoutineSchema<infer Value> ? Value : undefined;
-export type RoutineSteps = Record<string, RoutineSchema<unknown> | null>;
+export type RoutineStepOutput = {
+    summary: unknown;
+    data: unknown;
+};
+export type RoutineStep<Input = any, Output extends RoutineStepOutput = RoutineStepOutput, Access extends RoutineAccess = RoutineAccess> = {
+    readonly title: string;
+    readonly run: (input: Input, os: RoutineCapabilities<Access>) => Output | Promise<Output>;
+};
+export type RoutineSteps = Record<string, {
+    readonly title: string;
+    readonly run: (...args: any[]) => RoutineStepOutput | Promise<RoutineStepOutput>;
+}>;
+export type RoutineStepInput<Step extends RoutineSteps[string]> = Parameters<Step['run']>[0];
+export type RoutineStepResult<Step extends RoutineSteps[string]> = Awaited<ReturnType<Step['run']>>;
 export type RoutineInput<Value> = Value extends object ? {
     readonly [Key in keyof Value]: RoutineInput<Value[Key]>;
 } : Value;
@@ -29,45 +47,55 @@ export type RoutineArtifact = Readonly<{
     size: number;
     sha256: string;
 }>;
-export type RoutineRuntime<Steps extends RoutineSteps> = {
+type RepositoryFor<Mode> = Mode extends 'write' ? DataRepository : Omit<DataRepository, 'changes'>;
+type ConnectionName<Access extends RoutineAccess> = Access['connections'] extends readonly (infer Name)[] ? Name extends `airtable/${infer Alias}` ? Alias : never : never;
+export type RoutineCapabilities<Access extends RoutineAccess> = {
     readonly run: {
         readonly id: string;
     };
     readonly data: {
-        repository(name: string): DataRepository;
+        repository<Name extends Extract<keyof Access['repositories'], string>>(name: Name): RepositoryFor<NonNullable<Access['repositories']>[Name]>;
     };
-    readonly files: typeof files;
-    readonly connections: Connections;
-    readonly inbox: RoutinePublicationClient;
-    artifact(input: RoutineArtifactInput): Promise<RoutineArtifact>;
-    step<Key extends Extract<keyof Steps, string>>(id: Key, ...summary: Steps[Key] extends null ? [] : [summary: RoutineSchemaValue<Steps[Key]>]): Promise<void>;
+    readonly files: Access['files'] extends 'read-write' ? typeof files : Access['files'] extends 'read' ? Pick<typeof files, 'get' | 'read'> : {};
+    readonly connections: {
+        airtable(name: ConnectionName<Access>): ReturnType<Connections['airtable']>;
+    };
+    readonly inbox: Pick<RoutinePublicationClient, (Access['publish'] extends readonly string[] ? 'asks' extends Access['publish'][number] ? 'publishAsk' : never : never) | (Access['publish'] extends readonly string[] ? 'digests' extends Access['publish'][number] ? 'publishDigest' : never : never)>;
+};
+export type RoutineRuntime<Steps extends RoutineSteps, Access extends RoutineAccess = RoutineAccess> = RoutineCapabilities<Access> & {
+    step<Key extends Extract<keyof Steps, string>>(id: Key, ...input: Parameters<Steps[Key]['run']> extends [] ? [] : [input: RoutineInput<RoutineStepInput<Steps[Key]>>]): Promise<RoutineStepResult<Steps[Key]>>;
 };
-export type RoutineDefinition<Input extends RoutineSchema<unknown> | undefined, Steps extends RoutineSteps, Result extends RoutineSchema<unknown> | undefined> = {
+export type RoutineDefinition<Input extends RoutineSchema<unknown> | undefined = RoutineSchema<unknown> | undefined, Steps extends RoutineSteps = RoutineSteps, Result extends RoutineSchema<unknown> | undefined = RoutineSchema<unknown> | undefined, Access extends RoutineAccess = RoutineAccess, Responses extends readonly Handler<any>[] = readonly Handler<any>[], Id extends string = string> = {
+    readonly id: Id;
+    readonly title?: string;
     readonly input?: Input;
     readonly steps?: Steps;
     readonly result?: Result;
-    readonly run: (input: RoutineInput<Input extends undefined ? Record<string, never> : RoutineSchemaValue<Input>>, os: RoutineRuntime<Steps>) => Result extends undefined ? void | Promise<void> : RoutineSchemaValue<Result> | Promise<RoutineSchemaValue<Result>>;
+    readonly access?: Access;
+    readonly responses?: Responses;
+    readonly run: (input: RoutineInput<Input extends undefined ? Record<string, never> : RoutineSchemaValue<Input>>, os: RoutineRuntime<Steps, Access>) => Result extends undefined ? void | Promise<void> : RoutineSchemaValue<Result> | Promise<RoutineSchemaValue<Result>>;
 };
-export type DefineRoutine = <Input extends RoutineSchema<unknown> | undefined = undefined, const Steps extends RoutineSteps = {}, Result extends RoutineSchema<unknown> | undefined = undefined>(definition: RoutineDefinition<Input, Steps, Result>) => RoutineDefinition<Input, Steps, Result>;
+export type DefineRoutine = <const Id extends string, Input extends RoutineSchema<unknown> | undefined = undefined, const Access extends RoutineAccess = {}, const Steps extends Record<string, RoutineStep<any, RoutineStepOutput, Access>> = {}, Result extends RoutineSchema<unknown> | undefined = undefined, const Responses extends readonly Handler<any>[] = readonly []>(definition: RoutineDefinition<Input, Steps, Result, Access, Responses, Id> & {
+    steps?: Steps & Record<string, RoutineStep<any, RoutineStepOutput, Access>>;
+}) => RoutineDefinition<Input, Steps, Result, Access, Responses, Id>;
 export type RoutineSchemaBuilders = {
     object<const Properties extends Record<string, RoutineSchema<unknown>>>(properties: Properties): RoutineSchema<{
         [Key in keyof Properties]: RoutineSchemaValue<Properties[Key]>;
-    }>;
+    }, false>;
     array<Item extends RoutineSchema<unknown>>(items: Item, options: {
         maxItems: number;
-    }): RoutineSchema<RoutineSchemaValue<Item>[]>;
+    }): RoutineSchema<RoutineSchemaValue<Item>[], false>;
     string(options?: {
         maxLength?: number;
-    }): RoutineSchema<string>;
+    }): RoutineSchema<string, false>;
     integer(options?: {
         minimum?: number;
         maximum?: number;
-    }): RoutineSchema<number>;
+    }): RoutineSchema<number, false>;
     number(options?: {
         minimum?: number;
         maximum?: number;
-    }): RoutineSchema<number>;
-    boolean(): RoutineSchema<boolean>;
+    }): RoutineSchema<number, false>;
+    boolean(): RoutineSchema<boolean, false>;
 };
-export type RoutineFileSchema = () => RoutineSchema<File>;
-export {};
+export type RoutineFileSchema = () => RoutineSchema<File, false>;

package/dist/types/shared/app-descriptor.d.ts

@@ -0,0 +1,21 @@
+import type { AppValueSchema } from './app-routine-contract.js';
+/** Build-time structure only. Runtime readiness and availability belong to hosts. */
+export type AppRoutineDescriptor = {
+    id: string;
+    title?: string;
+    input: AppValueSchema & {
+        default?: unknown;
+    };
+    connections: {
+        id: string;
+        provider: string;
+        name: string;
+    }[];
+    steps: {
+        id: string;
+        title: string;
+    }[];
+};
+export type AppDescriptor = {
+    routines: AppRoutineDescriptor[];
+};

package/dist/types/shared/inbox-contract.d.ts

@@ -310,7 +310,11 @@ export declare function validateRecordReference(value: unknown): RecordReference
 export declare function validateRecordSource(value: unknown): RecordSource;
 export declare function validateResponseDefinition(value: unknown): ResponseDefinition;
 export declare function validateResponse(definition: unknown, value: unknown): QuestionResponse;
-export declare function defineHandler<Input extends JsonValue>(value: Handler<Input>): Handler<Input>;
+export declare function defineHandler<Input extends JsonValue, const Id extends string = string>(value: Handler<Input> & {
+    id: Id;
+}): Handler<Input> & {
+    id: Id;
+};
 export declare function respond<Input extends JsonValue>(handler: Handler<Input>, input: Input): HandlerReference;
 export declare function question(value: QuestionInput): Question;
 /** Structural validation is shared. Registered view/handler availability,

package/dist/types/shared/inbox-member-contract.d.ts

@@ -11,8 +11,8 @@ export declare const INBOX_LOCAL_INPUT_BYTES: number;
 export declare const INBOX_UUID: RegExp;
 export type InboxOperation = 'current' | 'items.list' | 'items.read' | 'items.see' | 'items.markDigestRead' | 'items.rename' | 'items.setLifecycle' | 'items.listRecipientCandidates' | 'items.addRecipient' | 'questions.list' | 'questions.answer' | 'questions.searchRecords' | 'files.read';
 export declare function isAppQuestionOperation(operation: InboxOperation): boolean;
-/** Closed wire vocabulary. Hosts select the listing mode; input cannot select it. */
-export declare function parseInboxRequest(value: unknown, questionListContext?: 'local' | 'hosted'): {
+/** Closed wire vocabulary; both placements require an explicit relevance filter. */
+export declare function parseInboxRequest(value: unknown): {
     operation: InboxOperation;
     input: Record<string, unknown>;
 };

package/dist/types/shared/inbox-member-types.d.ts

@@ -64,6 +64,7 @@ export type LinkedAskSnapshot = {
     done: boolean;
 };
 export interface InboxItem {
+    canonicalRoutineId?: string | null;
     id: string;
     workspaceId: string;
     number: number;
@@ -116,23 +117,20 @@ export interface ResponseAcceptance {
     acceptanceOrder?: number;
 }
 export interface AnswerableQuestion {
-    item: {
-        id: string;
-        number: number;
-        revision: number;
-        title: string;
-        href: string;
-    };
-    origin: {
-        routine: string;
-    };
-    question: {
+    itemId: string;
+    revision: number;
+    title: string;
+    inboxUrl: string;
+    questionId: string;
+    routine: string;
+    prompt: string;
+    instructions?: string;
+    response: ResponseDefinition;
+    answerable: boolean;
+    recordRefs: Array<{
+        repository: string;
         id: string;
-        prompt: string;
-        instructions: string | null;
-        response: ResponseDefinition;
-    };
-    recordRefs: string[];
+    }>;
 }
 export interface AskUpdate {
     item: InboxItem;
@@ -185,7 +183,7 @@ export interface InboxMember {
         }): Promise<RecipientAddition>;
     };
     questions: {
-        list(input?: InboxQuestionListInput): Promise<AnswerableQuestion[]>;
+        list(input: InboxQuestionListInput): Promise<AnswerableQuestion[]>;
         answer(input: InboxAnswerInput): Promise<ResponseAcceptance>;
         searchRecords(input: InboxSearchInput): Promise<RecordSelectionResult>;
     };

package/dist/types/shared/routine-definition-contract.d.ts

@@ -0,0 +1,33 @@
+import { type AppValueSchema } from './app-routine-contract.js';
+export type RoutineAccess = {
+    readonly repositories?: Readonly<Record<string, 'read' | 'write'>>;
+    readonly connections?: readonly string[];
+    readonly models?: readonly string[];
+    readonly files?: 'read' | 'read-write';
+    readonly publish?: readonly ('asks' | 'digests')[];
+};
+export type RoutineContract = {
+    id: string;
+    title?: string;
+    input: AppValueSchema;
+    inputDefault?: unknown;
+    access: RoutineAccess;
+    responses: {
+        id: string;
+    }[];
+    steps: {
+        id: string;
+        title: string;
+    }[];
+    result?: AppValueSchema;
+};
+export declare const routineTitle: (value: unknown) => value is string;
+export declare function freezeRoutineMetadata<Value>(value: Value): Value;
+/** Reject values JSON would drop, rewrite, or obtain by invoking authored code. */
+export declare function assertRoutineJson(value: unknown, ancestors?: Set<object>): void;
+/** Inspect property descriptors before reading authored metadata or functions. */
+export declare function assertRoutineFields(value: unknown, allowed?: string[]): asserts value is Record<string, any>;
+export declare function parseRoutineAccess(value: unknown): RoutineAccess;
+/** Inert report/admission grammar shared with authoring; imports no runtime or
+ * capability modules and never constructs executable customer functions. */
+export declare function parseRoutineDefinitionContract(value: unknown): RoutineContract;

package/dist/types/shared/routine-deployment-contract.d.ts

@@ -0,0 +1,47 @@
+import type { RoutineSourceProvenance } from './routine-source-provenance.js';
+import type { RoutineContract } from './routine-definition-contract.js';
+export declare const ROUTINE_DECLARATION_SCHEMA = "https://schemas.oddington.ai/routine/v1.json";
+export declare const ROUTINE_SOURCE_LIMITS: {
+    files: number;
+    bytes: number;
+    declarationBytes: number;
+};
+export type RoutineDeclaration = {
+    $schema: typeof ROUTINE_DECLARATION_SCHEMA;
+    access: {
+        repositories: Record<string, 'read' | 'write'>;
+        connections: string[];
+        models: string[];
+        files?: 'read' | 'read-write';
+        publish: Array<'asks' | 'digests'>;
+    };
+    runtime: {
+        features: Array<'python' | 'documents' | 'browser'>;
+        resources: 'standard' | 'large';
+        maxDuration: string;
+    };
+    retry: {
+        maxAttempts: number;
+    };
+    assets: string[];
+};
+export type RoutineDeploymentSource = {
+    digest: string;
+    declaration: RoutineDeclaration;
+    definition?: {
+        entry: string;
+        contract: RoutineContract;
+    };
+    files: Array<{
+        path: string;
+        sha256: string;
+        size: number;
+    }>;
+    provenance?: RoutineSourceProvenance;
+};
+/** An authored definition has one fixed, private execution profile. */
+export declare function routineDefinitionDeclaration(contract: RoutineContract): RoutineDeclaration;
+export declare function routineDefinitionDirectory(entry: string): string;
+export declare const routineAlias: (value: unknown) => value is string;
+export declare function routineAssetPattern(value: unknown): value is string;
+export declare function parseRoutineDeclaration(value: unknown): RoutineDeclaration;

package/dist/types/shared/routine-deployment-path.d.ts

@@ -0,0 +1,6 @@
+export declare const isRoutineSourceDirectory: (value: string) => boolean;
+/** Both the collector and untrusted upload/build admission use this boundary. */
+export declare function eligibleDeploymentPath(path: string): boolean;
+/** Package metadata is admitted only at the root and selected direct child.
+ * Inventory parsing has no selection yet; sealing supplies the exact name. */
+export declare function eligibleDeploymentInputPath(path: string, routine?: string): boolean;

package/dist/types/shared/routine-source-provenance.d.ts

@@ -0,0 +1,7 @@
+/** Checkout evidence is descriptive and never selects routine authority. */
+export type RoutineSourceProvenance = {
+    branch?: string;
+    commit?: string;
+    dirty: boolean;
+};
+export declare function parseRoutineSourceProvenance(value: unknown): RoutineSourceProvenance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Oddington routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",