@oddington/sdk 0.1.38 → 0.1.40

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

@@ -3,7 +3,7 @@ export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput
 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 { AIError, 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';
@@ -14,7 +14,7 @@ export type { GmailRuntimeConnection, AirtableRuntimeConnection, DropboxRuntimeC
 export type { Connections } from '../../../shared/airtable-contract.js';
 export declare const connections: import('../../../shared/airtable-contract.js').Connections;
 export { DataOperationError } from '../../../shared/data-contract.js';
-export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordsReadInput, RecordsReadResult, RecordsSearchOptions, RecordsSearchResult, HistoryListOptions, HistoryEntry, HistoryChangesOptions, HistoryChange, HistoryChangesResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
+export type { DataRepository, DataErrorCode, DataValidationDetail, DataFieldExpectation, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordsReadInput, RecordsReadResult, RecordsSearchOptions, RecordsSearchResult, HistoryListOptions, HistoryEntry, HistoryChangesOptions, HistoryChange, HistoryChangesResult, RecordIdentity, RecordCreation, RecordUpdateSet, AppliedChanges, DataChangeSet, DataEffect, DataFailureDetail, DataFailureCauseCode, LocalDataFileAction } from '../../../shared/data-contract.js';
 declare global {
     namespace __OddingtonOS {
         /** Import-free OS-generated metadata; no runtime namespace is created. */
@@ -130,11 +130,13 @@ export type LocalRunActivity = {
         updated: string[];
         deleted: string[];
         failures?: string[];
+        failure?: import('../../../shared/data-contract.js').DataFailureDetail;
     }>;
     effects: Array<{
         capability: 'files' | 'inbox' | 'ai';
         operation: string;
         status: 'completed' | 'failed';
+        durationMs?: number;
         reference?: string;
         summary?: unknown;
     }>;

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

@@ -138,15 +138,18 @@ export type RecordsSearchResult = {
         record: SelectedRecord;
     }>;
 };
-export type RecordUpdateSet = Record<string, DataValue>;
+export type RecordUpdateSet = Record<string, DataValue> & {
+    $body?: string;
+};
 export type RecordCreation = {
     $ref: string;
     $filing?: Record<string, string>;
+    $body?: string;
     $version?: never;
     $path?: never;
     [field: string]: DataValue | undefined;
 };
-export type DataPublication = {
+export type AppliedChanges = {
     version: string;
     created: RecordIdentity[];
     updated: RecordIdentity[];
@@ -200,7 +203,7 @@ export interface DataChangeSet {
     update(record: RecordIdentity, set: RecordUpdateSet): void;
     delete(record: RecordIdentity): void;
     validate(): Promise<void>;
-    publish(): Promise<DataPublication>;
+    apply(): Promise<AppliedChanges>;
 }
 export interface DataRepository {
     collections: {
@@ -213,9 +216,27 @@ export interface DataRepository {
         all<Query extends RecordsQuery>(query: Query, options: {
             maxRecords: number;
         }): Promise<RecordsResult<Query>>;
-        read(ref: string): Promise<SelectedRecord | null>;
-        read(refs: readonly string[]): Promise<RecordsReadResult>;
-        read(input: RecordsReadInput): Promise<SelectedRecord | null | RecordsReadResult>;
+        read(ref: string, options: {
+            body: true;
+        }): Promise<(SelectedRecord & {
+            $body: string;
+        }) | null>;
+        read(refs: readonly string[], options: {
+            body: true;
+        }): Promise<Omit<RecordsReadResult, 'records'> & {
+            records: Array<(SelectedRecord & {
+                $body: string;
+            }) | null>;
+        }>;
+        read(ref: string, options?: {
+            body?: boolean;
+        }): Promise<SelectedRecord | null>;
+        read(refs: readonly string[], options?: {
+            body?: boolean;
+        }): Promise<RecordsReadResult>;
+        read(input: RecordsReadInput, options?: {
+            body?: boolean;
+        }): Promise<SelectedRecord | null | RecordsReadResult>;
         search(query: string, options?: RecordsSearchOptions): Promise<RecordsSearchResult>;
     };
     history: {
@@ -225,13 +246,64 @@ export interface DataRepository {
     };
     changes(): DataChangeSet;
 }
-export type DataErrorCode = 'context_unavailable' | 'unauthenticated' | 'access_denied' | 'invalid_query' | 'request_too_large' | 'capacity' | 'unavailable' | 'invalid_change' | 'conflict' | 'publication_pending';
+export type DataErrorCode = 'context_unavailable' | 'unauthenticated' | 'access_denied' | 'invalid_query' | 'request_too_large' | 'capacity' | 'unavailable' | 'invalid_change' | 'conflict' | 'apply_pending';
 export type DataEffect = 'unapplied' | 'uncertain' | 'applied';
+export type DataFieldExpectation = {
+    type: DataValueDefinition['kind'];
+    many: boolean;
+    nullable: boolean;
+    decimalPlaces?: number;
+    format?: 'month';
+};
+export type DataValidationDetail = {
+    record: string;
+    field: string;
+    reason: 'unknown_field' | 'missing_field' | 'invalid_value' | 'source_schema_mismatch';
+    schemaFile?: string;
+    expected?: DataFieldExpectation;
+};
+export type LocalDataFileAction = 'created' | 'updated' | 'deleted';
+export type DataFailureCauseCode = 'schema_validation_failed' | 'invalid_record' | 'unsafe_record' | 'stale_record' | 'path_conflict' | 'filesystem_unavailable';
+export type DataFailurePath = {
+    action: LocalDataFileAction;
+    path: string;
+};
+export type DataFailureDetail = {
+    code: 'local_data_read_failed' | 'local_data_write_failed' | 'local_data_write_partial';
+    operation: 'read' | 'write';
+    repository: string;
+    cause: {
+        code: DataFailureCauseCode;
+        message: string;
+        path?: string;
+    };
+    files: {
+        state: 'none' | 'partial';
+        saved: DataFailurePath[];
+        failed?: DataFailurePath;
+        notAttempted: DataFailurePath[];
+        savedOmitted?: number;
+        notAttemptedOmitted?: number;
+    };
+    nextAction: 'fix_failed_file_then_rerun' | 'review_resolve_then_rerun';
+};
+export type DataRecordLimitDetail = {
+    code: 'record_limit_exceeded';
+    maxRecords: number;
+    collections: string[];
+};
+export type DataOperationDetail = DataFailureDetail | DataRecordLimitDetail | DataValidationDetail;
+/** Parse the only local checkout detail allowed to cross the private SDK and
+ * retained-Run boundary. It contains no values, raw exceptions or host paths. */
+export declare function parseDataFailureDetail(value: unknown): DataFailureDetail;
+export declare function parseDataOperationDetail(value: unknown): DataOperationDetail;
+export declare function dataRecordLimitMessage(detail: DataRecordLimitDetail): string;
 export declare class DataOperationError extends Error {
     readonly code: DataErrorCode;
     readonly retryable: boolean;
     readonly effect?: DataEffect | undefined;
     readonly component?: string | undefined;
-    constructor(code: DataErrorCode, retryable?: boolean, effect?: DataEffect | undefined, component?: string | undefined);
+    readonly detail?: DataOperationDetail | undefined;
+    constructor(code: DataErrorCode, retryable?: boolean, effect?: DataEffect | undefined, component?: string | undefined, detail?: DataOperationDetail | undefined);
 }
 export {};

package/dist/types/shared/data-validation-message.d.ts

@@ -0,0 +1,23 @@
+import type { DataFieldExpectation, DataValidationDetail } from './data-contract.js';
+type FieldProblem = 'unknown' | 'missing' | 'invalid' | 'source_schema';
+export type FieldExpectation = DataFieldExpectation;
+/** Detach and validate only the approved bounded facts at every trust boundary. */
+export declare function parseDataValidationDetail(value: unknown): DataValidationDetail | undefined;
+export declare function recordFieldDetail(record: string, field: string, problem: FieldProblem, schemaFile?: string, expectation?: FieldExpectation): DataValidationDetail | undefined;
+/** Only bounded identifiers, relative schema locations and fixed advice enter
+ * public messages. Values and arbitrary upstream prose stay private. */
+export declare function recordFieldMessage(record: string, field: string, problem: FieldProblem, schemaPath?: string, expected?: FieldExpectation): string | undefined;
+export declare function safeRecordFieldMessage(value: unknown): string | undefined;
+export declare function dataValidationMessageFacts(error: {
+    code: string;
+    message: string;
+    detail?: unknown;
+}): {
+    message?: string;
+    detail?: DataValidationDetail;
+};
+export declare function explainDataValidation<T extends {
+    code: string;
+    message: string;
+}>(error: T, message: unknown, detail?: unknown): T;
+export {};

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

@@ -48,6 +48,7 @@ declare const fileValidationReasons: {
     invalid_enrichment_name: string;
     invalid_replacement: string;
     invalid_bytes: string;
+    original_changed: string;
 };
 export type FileErrorDetail = {
     reason: keyof typeof fileValidationReasons | 'size_mismatch' | 'size_limit';
@@ -59,6 +60,8 @@ export type FileErrorDetail = {
 /** 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 const FILE_CAPACITY_MESSAGE: string;
+export declare const FILE_INTEGRITY_MESSAGE: string;
 export declare class FileOperationError extends Error {
     readonly code: FileErrorCode;
     readonly status: number;

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

@@ -208,11 +208,13 @@ export type RecordUpdate = {
     ref: string;
     expectedVersion: string;
     set: JsonObject;
+    body?: string;
 };
 export type RecordCreate = {
     ref: string;
     path: string;
     fields: JsonObject;
+    body?: string;
 };
 export type RecordDelete = {
     ref: string;
@@ -269,6 +271,15 @@ export type Handler<Input extends JsonValue = JsonValue> = {
 export declare class InboxContractError extends Error {
     constructor(message: string);
 }
+export declare const INBOX_PUBLICATION_ITEM_BYTES: number;
+export declare const INBOX_PUBLICATION_REQUEST_BYTES: number;
+export declare const INBOX_PUBLICATION_TOO_LARGE = "Your Inbox item failed to publish. Its content exceeds the 1 MB limit. Trim the content, or attach long reports, data, and supporting materials as files instead. Then try again.";
+export declare class InboxPublicationSizeError extends InboxContractError {
+    readonly kind: Publication['kind'];
+    readonly bytes: number;
+    constructor(kind: Publication['kind'], bytes: number);
+}
+export declare function enforcePublicationSize(value: Publication): Publication;
 /** Copy only lossless JSON. In particular, JSON.stringify must not silently
  * erase undefined/functions or convert dates, sparse arrays, or nonfinite numbers. */
 export declare function serializable(value: unknown, ancestors?: Set<object>): JsonValue;

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

@@ -12,7 +12,7 @@ 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];
 /** The original answer is explicit recovery data, never part of the message or JSON logging. */
-export declare class RoutineAIError extends Error {
+export declare class AIError extends Error {
     readonly code: RoutineAIErrorCode;
     readonly detail?: RoutineAIOutputIssue;
     readonly text?: string;
@@ -21,13 +21,15 @@ export declare class RoutineAIError extends Error {
         text?: string;
     });
 }
+/** Compatibility alias: both names identify the same error constructor. */
+export { AIError as RoutineAIError };
 /** Explicit private transport projection; ordinary error logging excludes answer text. */
-export declare function routineAIErrorFacts(error: RoutineAIError): {
+export declare function routineAIErrorFacts(error: AIError): {
     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 declare function parseRoutineAIError(value: unknown): AIError;
 export type RoutineAIInput = string | File;
 export type RoutineAIRequest = {
     kind: 'generateText';

package/package.json

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