@oddington/sdk 0.1.37 → 0.1.39

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

@@ -1,22 +1,20 @@
-import type { AskInput, DigestInput, InboxFile, PublicationRequest, PublishedAsk, PublishedDigest, ResolutionInput } from '../../../shared/inbox-contract.js';
-import type { FileAddOptions } from '../../../shared/inbox-files.js';
+import type { AskInput, DigestInput, PublicationRequest, PublishedAsk, PublishedDigest, ResolutionInput } from '../../../shared/inbox-contract.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 { 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';
 export type { CapturedRecordTableInput, RecordField, RecordTableInput, RecordValue, RecordViewInput, TableColumn, ViewRecord, } from '../../../shared/inbox-views.js';
-export type { FileAddOptions } from '../../../shared/inbox-files.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, OutlookRuntimeConnection, SharePointRuntimeConnection, RuntimeConnection, RuntimeConnectionFor } from '../../../shared/connection-runtime.js';
 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. */
@@ -41,7 +39,6 @@ export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions,
 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>;
-    delete(id: string): Promise<void>;
     upload(id: string): Promise<import('../../../shared/files-contract.js').File>;
     enrich(input: import('../../../shared/files-contract.js').FileEnrichOptions): Promise<import('../../../shared/files-contract.js').FileEnrichResult>;
     read(id: string): Promise<Response>;
@@ -125,15 +122,28 @@ export type AppRoutineHandle<Result, Steps> = {
         summary?: unknown;
         data?: unknown;
     })>;
-    publish(): Promise<Omit<RunSummary, 'result'> & {
-        result?: Result;
-    }>;
 };
-export type LocalPublication = {
-    state: 'not_needed' | 'ready' | 'published';
-} | {
-    state: 'failed';
-    message: string;
+export type LocalRunActivity = {
+    data: Array<{
+        repository: string;
+        created: string[];
+        updated: string[];
+        deleted: string[];
+        failures?: string[];
+        failure?: import('../../../shared/data-contract.js').DataFailureDetail;
+    }>;
+    effects: Array<{
+        capability: 'files' | 'inbox' | 'ai';
+        operation: string;
+        status: 'completed' | 'failed';
+        reference?: string;
+        summary?: unknown;
+    }>;
+    git?: {
+        branch?: string;
+        commit?: string;
+        dirty: boolean;
+    };
 };
 export type StepDetail = {
     id: string;
@@ -159,13 +169,12 @@ export type RunSummary = {
     failure?: {
         message: string;
     };
-    publication?: LocalPublication;
+    local?: LocalRunActivity;
 };
 export type RunHandle = {
     current(): Promise<RunSummary>;
     watch(): AsyncIterable<RunSummary>;
     step(id: string): Promise<StepDetail>;
-    publish(): Promise<RunSummary>;
 };
 export type RoutineReadiness = {
     state: 'ready';
@@ -209,7 +218,6 @@ export type RoutinePublicationClientOptions = {
     workspace?: string;
     capability?: string;
     request?: InboxRequester;
-    workingRoot?: string;
 };
 export type RoutinePublicationClient = {
     publishAsk(value: AskInput, options: {
@@ -219,9 +227,6 @@ export type RoutinePublicationClient = {
         requestKey: string;
     }): Promise<PublishedDigest>;
     publishResolution(askId: string, value: ResolutionInput): Promise<void>;
-    files: {
-        add(value: FileAddOptions): Promise<InboxFile>;
-    };
     check(body: PublicationRequest): Promise<void>;
 };
 export declare function routinePublicationClient(options?: RoutinePublicationClientOptions): RoutinePublicationClient;

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

@@ -110,8 +110,8 @@ 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;
+    array<Item extends RoutineSchema<unknown>>(items: Item, options?: {
+        maxItems?: number;
     }): RoutineSchema<RoutineSchemaValue<Item>[], false>;
     string(options?: {
         maxLength?: number;

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

@@ -17,7 +17,7 @@ export type AppValueSchema = {
 } | {
     type: 'array';
     items: AppValueSchema;
-    maxItems: number;
+    maxItems?: number;
 } | {
     type: 'boolean';
 } | {

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/inbox-member-contract.d.ts

@@ -9,7 +9,7 @@ export declare const INBOX_INPUT_BYTES = 8192;
 /** Includes the exact declaration only on the private CLI-authenticated ingress. */
 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 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';
 export declare function isAppQuestionOperation(operation: InboxOperation): boolean;
 /** Closed wire vocabulary; both placements require an explicit relevance filter. */
 export declare function parseInboxRequest(value: unknown): {

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

@@ -201,11 +201,5 @@ export interface InboxMember {
         answer(input: InboxAnswerInput): Promise<ResponseAcceptance>;
         searchRecords(input: InboxSearchInput): Promise<RecordSelectionResult>;
     };
-    files: {
-        read(input: {
-            itemId: string;
-            fileId: string;
-        }): Promise<Response>;
-    };
 }
 export {};

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.37",
+  "version": "0.1.39",
   "description": "OS routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/dist/types/shared/delimited-text.d.ts

@@ -1,2 +0,0 @@
-export declare function parseDelimitedText(value: string, declaredDelimiter?: string): string[][];
-export declare function delimitedDataRowCount(rows: string[][], headerRow?: number): number;

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

@@ -1,12 +0,0 @@
-import { type InboxFile } from './inbox-contract.js';
-export type FileAddOptions = {
-    path: string;
-    name?: string;
-};
-export declare function validateFileAddOptions(value: unknown): FileAddOptions;
-/** Consumer interpretation only: no parsing facts become File metadata. */
-export declare function previewCsvRows(bytes: Uint8Array): string[][];
-export declare function deriveInboxFile(bytes: Uint8Array, name: string): Promise<Omit<InboxFile, 'id'>>;
-/** Original integrity is independent of consumer format interpretation. */
-export declare function verifyInboxFile(bytes: Uint8Array, value: unknown): Promise<InboxFile>;
-export declare function publicationFiles(body?: import('./inbox-contract.js').InboxBlock[]): InboxFile[];