@oddington/sdk 0.1.34 → 0.1.36

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

@@ -1,18 +1,15 @@
-import type { AskInput, CapturedRecords, DigestInput, InboxFile, PublicationRequest, PublishedAsk, PublishedDigest, RepositoryReceipt, ResolutionInput } from '../../../shared/inbox-contract.js';
+import type { AskInput, DigestInput, InboxFile, PublicationRequest, PublishedAsk, PublishedDigest, ResolutionInput } from '../../../shared/inbox-contract.js';
 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, RoutineAccess, RoutineCapabilities, RoutineStep, RoutineSteps, RoutineStepInput, RoutineStepResult, RoutineStepOutput, RoutineArtifactInput, RoutineArtifact, RoutineAI } 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;
+export { RoutineAIError } from '../../../shared/routine-ai-contract.js';
+export type { RoutineAIOutputIssue } from '../../../shared/routine-ai-output-detail.js';
 export { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
 export type { AskInput, AuthoredSource, CapturedRecords, DigestInput, Handler, HandlerReference, HandlerRuntime, HandlerTransition, InboxBlock, InboxFile, JsonObject, JsonValue, PresentedField, PresentedRecord, PresentedRecordSummary, PublishedAsk, PublishedDigest, PublishedView, PublicationRequest, Question, QuestionInput, QuestionResponse, RecordCreate, RecordDelete, RecordReference, RecordSource, RecordUpdate, RepositoryCapabilities, RepositoryReceipt, Resolution, ResolutionInput, ResponseDefinition, } from '../../../shared/inbox-contract.js';
 export type { CapturedRecordTableInput, RecordField, RecordTableInput, RecordValue, RecordViewInput, TableColumn, ViewRecord, } from '../../../shared/inbox-views.js';
 export type { FileAddOptions } from '../../../shared/inbox-files.js';
-export type { RecordReadInput } from '../../../shared/record-capture.js';
-export type { RecordDeleteRequest, RecordUpdateRequest, RecordWriteRequest } from '../../../shared/record-write.js';
-export { RoutineRecordWriteError } from '../../../shared/record-write.js';
 export { AirtableOperationError } from '../../../shared/airtable-contract.js';
 export type { AirtableField, AirtableTable, AirtableRecord, AirtableListInput, AirtableGetInput, AirtableCreateInput, AirtableUpdateInput, AirtableDeleteInput, AirtableReceipt, AirtableWriteResult, AirtableClient } from '../../../shared/airtable-contract.js';
 export type { GmailRuntimeConnection, AirtableRuntimeConnection, DropboxRuntimeConnection, RuntimeConnection } from '../../../shared/connection-runtime.js';
@@ -40,7 +37,7 @@ export { InboxOperationError } from '../../../shared/inbox-member-contract.js';
 export type { InboxMember, InboxCurrent, InboxItem, AnswerableQuestion, QuestionSnapshot, ResponseConsequence, LinkedAskSnapshot, AskUpdate, DigestReadConfirmation, RecipientCandidate, RecipientAddition, ResponseAcceptance, InboxAnswerInput, InboxSearchInput } from '../../../shared/inbox-member-types.js';
 export type { RecordSelectionResult } from '../../../shared/record-selection.js';
 export declare const inbox: import('../../../shared/inbox-member-types.js').InboxMember;
-export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions, FileEnrichment, FileEnrichOptions, FileEnrichResult, FileErrorCode } from '../../../shared/files-contract.js';
+export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions, FileEnrichment, FileEnrichOptions, FileEnrichResult, FileErrorCode, FileErrorDetail } from '../../../shared/files-contract.js';
 export declare const files: {
     create(input: import('../../../shared/files-contract.js').FileCreateInput, options?: import('../../../shared/files-contract.js').FileCreateOptions): Promise<import('../../../shared/files-contract.js').File>;
     get(id: string): Promise<import('../../../shared/files-contract.js').File>;
@@ -222,25 +219,6 @@ export type RoutinePublicationClient = {
         requestKey: string;
     }): Promise<PublishedDigest>;
     publishResolution(askId: string, value: ResolutionInput): Promise<void>;
-    readRecords(input: RecordReadInput): Promise<CapturedRecords>;
-    repository: {
-        readRecords(input: RecordReadInput): Promise<CapturedRecords>;
-        updateRecords(input: RecordUpdateRequest, options: {
-            requestKey: string;
-        }): Promise<{
-            receipt: RepositoryReceipt;
-        }>;
-        writeRecords(input: RecordWriteRequest, options: {
-            requestKey: string;
-        }): Promise<{
-            receipt: RepositoryReceipt;
-        }>;
-        deleteRecords(input: RecordDeleteRequest, options: {
-            requestKey: string;
-        }): Promise<{
-            receipt: RepositoryReceipt;
-        }>;
-    };
     files: {
         add(value: FileAddOptions): Promise<InboxFile>;
     };

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

@@ -23,6 +23,7 @@ export type RoutineAI = {
     }): Promise<{
         text: string;
     }>;
+    /** Invalid output throws a catchable RoutineAIError with the original answer. */
     generateObject<Schema extends RoutineSchema<unknown>>(input: {
         instructions: string;
         input: RoutineAIInput;

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

@@ -49,7 +49,16 @@ export declare class AppRoutineContractError extends Error {
 export declare function isAppRoutineName(value: unknown): value is string;
 /** One operation owns the property budget across input, result and all summaries. */
 export declare function parseAppRoutineContract(value: unknown): AppRoutineContract;
-export declare function validateRoutineSchemaValue(schema: AppValueSchema, value: unknown): void;
+export type RoutineSchemaIssue = {
+    reason: 'missing_field' | 'unexpected_field' | 'wrong_type' | 'out_of_bounds' | 'invalid_file';
+    path: string;
+    expected: AppValueSchema['type'];
+    received: 'missing' | 'null' | 'object' | 'array' | 'boolean' | 'string' | 'number' | 'other';
+    constraint?: 'maxLength' | 'maxItems' | 'minimum' | 'maximum';
+    limit?: number;
+};
+/** The optional observer explains the existing rejection; it never accepts or repairs a value. */
+export declare function validateRoutineSchemaValue(schema: AppValueSchema, value: unknown, rejected?: (issue: RoutineSchemaIssue) => void): void;
 /** Structural validation grants no execution or File-use authority. Values stay unchanged. */
 export declare function validateAppRoutineInput(contract: AppRoutineContract, value: unknown): void;
 export declare function validateAppRoutineResult(contract: AppRoutineContract, value?: unknown): void;

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

@@ -37,12 +37,40 @@ export type File = {
     enrichments: Record<string, FileEnrichment>;
 };
 export type FileErrorCode = 'invalid_input' | 'unsupported_context' | 'unauthenticated' | 'access_denied' | 'request_too_large' | 'conflict' | 'local_only' | 'integrity' | 'unavailable' | 'capacity' | 'method_not_allowed';
+declare const fileValidationReasons: {
+    invalid_metadata: string;
+    invalid_name: string;
+    invalid_path: string;
+    invalid_storage: string;
+    invalid_media_type: string;
+    invalid_size: string;
+    invalid_request_key: string;
+    invalid_enrichment_name: string;
+    invalid_replacement: string;
+    invalid_bytes: string;
+};
+export type FileErrorDetail = {
+    reason: keyof typeof fileValidationReasons | 'size_mismatch' | 'size_limit';
+    expectedBytes?: number;
+    receivedBytes?: number;
+    limitBytes?: number;
+    receivedAtLeast?: true;
+};
+/** Only inert, bounded facts cross Files and Run error boundaries. */
+export declare function parseFileErrorDetail(value: unknown): FileErrorDetail | undefined;
+export declare function fileErrorExplanation(detail: FileErrorDetail): string;
 export declare class FileOperationError extends Error {
     readonly code: FileErrorCode;
     readonly status: number;
     readonly retryable: boolean;
-    constructor(code: FileErrorCode, status: number, retryable?: boolean);
+    readonly detail?: FileErrorDetail;
+    constructor(code: FileErrorCode, status: number, retryable?: boolean, detail?: FileErrorDetail);
 }
+export declare function fileErrorFacts(error: FileOperationError): {
+    code: FileErrorCode;
+    retryable?: boolean | undefined;
+    detail?: FileErrorDetail | undefined;
+};
 export declare const FILE_ID_PATTERN: RegExp;
 /** Descriptor admission is independent of each runtime's supported writes. */
 export declare const FILE_ORIGINAL_MAX_BYTES: number;
@@ -74,3 +102,4 @@ export type FileCreateMetadata = {
     requestKey: string;
 };
 export declare function parseFileCreateMetadata(value: unknown, maxBytes: number): FileCreateMetadata;
+export {};

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

@@ -1,19 +1,32 @@
 import { type AppValueSchema } from './app-routine-contract.js';
 import { type File } from './files-contract.js';
-/** Control values, explicit text and accepted output share the Run value bound.
+import { type RoutineAIOutputIssue } from './routine-ai-output-detail.js';
+/** Requests use the Run value bound; final answers use the same UTF-8 byte ceiling.
  * Raw Files have no universal AI byte cap: adapters must measure their final
  * encoded request against their own transport limit before dispatch. */
 export declare const ROUTINE_AI_VALUE_BYTES: number;
+/** Worst-case JSON escaping is six bytes per UTF-8 answer byte, plus framing. */
+export declare const ROUTINE_AI_RESULT_BYTES: number;
 export declare const ROUTINE_AI_EVIDENCE_BYTES: number;
 export declare const ROUTINE_AI_OPERATION_MS = 120000;
 export declare const ROUTINE_AI_ERROR_CODES: readonly ['access_denied', 'capability_unavailable', 'invalid_input', 'unsupported_file', 'file_unavailable', 'input_too_large', 'output_too_large', 'provider_failure', 'invalid_output', 'cancelled'];
 export type RoutineAIErrorCode = typeof ROUTINE_AI_ERROR_CODES[number];
-/** Safe failures contain only an allowlisted code, never provider payloads. */
+/** The original answer is explicit recovery data, never part of the message or JSON logging. */
 export declare class RoutineAIError extends Error {
     readonly code: RoutineAIErrorCode;
-    constructor(code: RoutineAIErrorCode);
+    readonly detail?: RoutineAIOutputIssue;
+    readonly text?: string;
+    constructor(code: RoutineAIErrorCode, options?: {
+        detail?: RoutineAIOutputIssue;
+        text?: string;
+    });
 }
-/** Private transports carry only the bounded failure code. */
+/** Explicit private transport projection; ordinary error logging excludes answer text. */
+export declare function routineAIErrorFacts(error: RoutineAIError): {
+    code: "access_denied" | "cancelled" | "capability_unavailable" | "file_unavailable" | "input_too_large" | "invalid_input" | "invalid_output" | "output_too_large" | "provider_failure" | "unsupported_file";
+    detail?: RoutineAIOutputIssue | undefined;
+    text?: string | undefined;
+};
 export declare function parseRoutineAIError(value: unknown): RoutineAIError;
 export type RoutineAIInput = string | File;
 export type RoutineAIRequest = {
@@ -26,6 +39,7 @@ export type RoutineAIRequest = {
     input: RoutineAIInput;
     schema: AppValueSchema;
 };
+/** Keep the existing successful transport shapes for deployed SDK compatibility. */
 export type RoutineAIResult = {
     text: string;
 } | {
@@ -34,7 +48,7 @@ export type RoutineAIResult = {
 export type RoutineAITransport = (request: RoutineAIRequest) => Promise<RoutineAIResult>;
 /** Inert schema grammar only. SDK builders must be resolved before transport. */
 export declare function parseRoutineAIRequest(value: unknown): RoutineAIRequest;
-/** Validate results again at delivery; provider text is never implicitly repaired. */
+/** Delivery revalidates the existing result envelope and caller-supplied schema. */
 export declare function parseRoutineAIResult(request: RoutineAIRequest, value: unknown): RoutineAIResult;
-/** Native adapters discard reasoning and pass only the final text here. */
+/** Native adapters discard reasoning and preserve the original final text on rejection. */
 export declare function acceptRoutineAIOutput(request: RoutineAIRequest, text: unknown): RoutineAIResult;

package/dist/types/shared/routine-ai-output-detail.d.ts

@@ -0,0 +1,11 @@
+import type { RoutineSchemaIssue } from './app-routine-contract.js';
+export type RoutineAIOutputIssue = RoutineSchemaIssue | {
+    reason: 'invalid_json';
+} | {
+    reason: 'invalid_response';
+} | {
+    reason: 'empty_text';
+};
+/** Public explanations carry schema facts and types, never model values or unknown field names. */
+export declare function parseRoutineAIOutputIssue(value: unknown): RoutineAIOutputIssue | undefined;
+export declare function routineAIOutputMessage(issue: RoutineAIOutputIssue): string;

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

@@ -16,12 +16,12 @@ export type RoutineDeclaration = {
         publish: Array<'asks' | 'digests'>;
     };
     runtime: {
-        features: Array<'python' | 'documents' | 'browser'>;
-        resources: 'standard' | 'large';
-        maxDuration: string;
+        features: [];
+        resources: 'standard';
+        maxDuration: '15m';
     };
     retry: {
-        maxAttempts: number;
+        maxAttempts: 1;
     };
     assets: string[];
 };

package/package.json

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

package/dist/types/shared/record-write.d.ts

@@ -1,33 +0,0 @@
-import { type RecordCreate, type RecordDelete, type RecordUpdate } from './inbox-contract.js';
-export type RecordWrite = RecordCreate | RecordUpdate;
-export type RecordUpdateRequest = {
-    repository: string;
-    records: RecordUpdate[];
-};
-export type RecordWriteRequest = {
-    repository: string;
-    records: RecordWrite[];
-};
-export type RecordDeleteRequest = {
-    repository: string;
-    records: RecordDelete[];
-};
-export type RecordChange = RecordWrite | RecordDelete;
-export type RecordChangeRequest = {
-    repository: string;
-    records: RecordChange[];
-};
-export type RoutineRecordWriteRequest = {
-    input: RecordChangeRequest;
-    requestKey: string;
-};
-export declare const RECORD_WRITE_INPUT_LIMIT: number;
-export declare class RoutineRecordWriteError extends Error {
-    readonly effect: 'unapplied' | 'uncertain' | 'pending';
-    constructor(message: string, effect: 'unapplied' | 'uncertain' | 'pending');
-}
-export declare function validateRecordWrite(value: unknown): RecordWriteRequest;
-export declare function validateRecordUpdate(value: unknown): RecordUpdateRequest;
-export declare function validateRecordDelete(value: unknown): RecordDeleteRequest;
-export declare function validateRecordChange(value: unknown): RecordChangeRequest;
-export declare function validateRoutineRecordWrite(value: unknown): RoutineRecordWriteRequest;