@oddington/sdk 0.1.0 → 0.1.2

package/README.md

@@ -13,6 +13,37 @@ import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/
 const inbox = routinePublicationClient();
 ```
 
+Bind a declared Airtable connection with `connections.airtable('project-management')`
+from the package root. Import and binding perform no network or credential work.
+The client exposes `tables.list()` and `records.list`, `get`, `create`, `update`
+and `delete`. Reads allow table names or stable IDs and return all ordered pages;
+writes require a stable table ID and one nonempty batch of at most ten records.
+Operations cannot select another workspace, base, token or provider URL.
+
+```ts
+import { connections } from '@oddington/sdk';
+
+const airtable = connections.airtable('project-management');
+const changed = await airtable.records.update({ table: 'tblContacts', records: [{
+  id: 'recRetained', expected: { Email: 'james@example.com', Company: null },
+  set: { Company: ['recCompany'] },
+}] });
+```
+
+Preserve original reviewed `expected` values. Non-null values must match exactly;
+`null` requires an omitted field key and cannot be used as an update value. Reads
+preserve Airtable's omitted-field shape. Create requires nonempty `fields`, update
+requires nonempty `set`, and untouched fields remain unchanged. Guarded methods
+read before a single batch write; this leaves a concurrency race and provides no
+atomic compare-and-swap, rollback or implicit retry.
+
+Success returns a safe Airtable `receipt` with the connection, configured base,
+table, operation and acknowledged IDs. Create/update also return acknowledged
+records separately. `AirtableOperationError` reports `unapplied`, `partial` or
+`uncertain` effects and known safe `receipts`. Stop after partial or uncertain
+work; never repeat the whole change blindly. Credentials must never be retained
+in files, publication, logs, handler input, errors or receipts.
+
 Managed routine launches supply workspace, scoped capability and working root.
 The defaults read `ODDINGTON_ROUTINE_WORKSPACE`, `ODDINGTON_ROUTINE_RUN` and
 `ODDINGTON_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
@@ -59,11 +90,3 @@ installation. Customer manifests cannot replace the runner-owned SDK. The runner
 selects the approved code revision and handler, and supplies only scoped capability
 transport. The package contains public runtime code, declarations, this README and
 its license; it has no executable, operator/server code or infrastructure credentials.
-
-From the product checkout, run `bun run --filter @oddington/sdk build`, then
-`bun run --filter @oddington/sdk verify:package`. Verification installs the actual
-tarball offline into a temporary consumer without the CLI, imports and typechecks
-through `@oddington/sdk`, and exercises retained evidence, handlerless publication
-and guarded repository calls. Set `PACKAGE_VERIFY_NODE` to the Node 22.12.0
-executable for supported-baseline proof. The CLI's corresponding verifier installs
-both local tarballs, checks `os --help` and refuses the removed subpath.

package/dist/index.js

@@ -7202,9 +7202,9 @@ var require_PDFContext = __commonJS((exports) => {
         return array2;
       } else {
         var dict = PDFDict_1.default.withContext(this);
-        var keys2 = Object.keys(literal);
-        for (var idx = 0, len = keys2.length;idx < len; idx++) {
-          var key = keys2[idx];
+        var keys3 = Object.keys(literal);
+        for (var idx = 0, len = keys3.length;idx < len; idx++) {
+          var key = keys3[idx];
           var value = literal[key];
           if (value !== undefined)
             dict.set(PDFName_1.default.of(key), this.obj(value));
@@ -13306,9 +13306,9 @@ var require_PDFWidgetAnnotation = __commonJS((exports) => {
       var _a;
       var normal = (_a = this.getAppearances()) === null || _a === undefined ? undefined : _a.normal;
       if (normal instanceof PDFDict_1.default) {
-        var keys2 = normal.keys();
-        for (var idx = 0, len = keys2.length;idx < len; idx++) {
-          var key = keys2[idx];
+        var keys3 = normal.keys();
+        for (var idx = 0, len = keys3.length;idx < len; idx++) {
+          var key = keys3[idx];
           if (key !== PDFName_1.default.of("Off"))
             return key;
         }
@@ -14091,28 +14091,28 @@ var require_PDFAcroForm = __commonJS((exports) => {
       this.dict = dict;
     }
     PDFAcroForm2.prototype.Fields = function() {
-      var fields2 = this.dict.lookup(PDFName_1.default.of("Fields"));
-      if (fields2 instanceof PDFArray_1.default)
-        return fields2;
+      var fields3 = this.dict.lookup(PDFName_1.default.of("Fields"));
+      if (fields3 instanceof PDFArray_1.default)
+        return fields3;
       return;
     };
     PDFAcroForm2.prototype.getFields = function() {
       var Fields = this.normalizedEntries().Fields;
-      var fields2 = new Array(Fields.size());
+      var fields3 = new Array(Fields.size());
       for (var idx = 0, len = Fields.size();idx < len; idx++) {
         var ref = Fields.get(idx);
         var dict = Fields.lookup(idx, PDFDict_1.default);
-        fields2[idx] = [utils_1.createPDFAcroField(dict, ref), ref];
+        fields3[idx] = [utils_1.createPDFAcroField(dict, ref), ref];
       }
-      return fields2;
+      return fields3;
     };
     PDFAcroForm2.prototype.getAllFields = function() {
       var allFields = [];
-      var pushFields = function(fields2) {
-        if (!fields2)
+      var pushFields = function(fields3) {
+        if (!fields3)
           return;
-        for (var idx = 0, len = fields2.length;idx < len; idx++) {
-          var field = fields2[idx];
+        for (var idx = 0, len = fields3.length;idx < len; idx++) {
+          var field = fields3[idx];
           allFields.push(field);
           var fieldModel = field[0];
           if (fieldModel instanceof PDFAcroNonTerminal_1.default) {
@@ -14129,13 +14129,13 @@ var require_PDFAcroForm = __commonJS((exports) => {
     };
     PDFAcroForm2.prototype.removeField = function(field) {
       var parent = field.getParent();
-      var fields2 = parent === undefined ? this.normalizedEntries().Fields : parent.Kids();
-      var index = fields2 === null || fields2 === undefined ? undefined : fields2.indexOf(field.ref);
-      if (fields2 === undefined || index === undefined) {
+      var fields3 = parent === undefined ? this.normalizedEntries().Fields : parent.Kids();
+      var index = fields3 === null || fields3 === undefined ? undefined : fields3.indexOf(field.ref);
+      if (fields3 === undefined || index === undefined) {
         throw new Error("Tried to remove inexistent field " + field.getFullyQualifiedName());
       }
-      fields2.remove(index);
-      if (parent !== undefined && fields2.size() === 0) {
+      fields3.remove(index);
+      if (parent !== undefined && fields3.size() === 0) {
         this.removeField(parent);
       }
     };
@@ -19086,20 +19086,20 @@ var require_PDFForm = __commonJS((exports) => {
     };
     PDFForm2.prototype.getFields = function() {
       var allFields = this.acroForm.getAllFields();
-      var fields2 = [];
+      var fields3 = [];
       for (var idx = 0, len = allFields.length;idx < len; idx++) {
         var _a = allFields[idx], acroField = _a[0], ref = _a[1];
         var field = convertToPDFField(acroField, ref, this.doc);
         if (field)
-          fields2.push(field);
+          fields3.push(field);
       }
-      return fields2;
+      return fields3;
     };
     PDFForm2.prototype.getFieldMaybe = function(name) {
       utils_1.assertIs(name, "name", ["string"]);
-      var fields2 = this.getFields();
-      for (var idx = 0, len = fields2.length;idx < len; idx++) {
-        var field = fields2[idx];
+      var fields3 = this.getFields();
+      for (var idx = 0, len = fields3.length;idx < len; idx++) {
+        var field = fields3[idx];
         if (field.getName() === name)
           return field;
       }
@@ -19222,9 +19222,9 @@ var require_PDFForm = __commonJS((exports) => {
       if (options.updateFieldAppearances) {
         this.updateFieldAppearances();
       }
-      var fields2 = this.getFields();
-      for (var i = 0, lenFields = fields2.length;i < lenFields; i++) {
-        var field = fields2[i];
+      var fields3 = this.getFields();
+      for (var i = 0, lenFields = fields3.length;i < lenFields; i++) {
+        var field = fields3[i];
         var widgets = field.acroField.getWidgets();
         for (var j = 0, lenWidgets = widgets.length;j < lenWidgets; j++) {
           var widget = widgets[j];
@@ -19271,9 +19271,9 @@ var require_PDFForm = __commonJS((exports) => {
     PDFForm2.prototype.updateFieldAppearances = function(font) {
       utils_1.assertOrUndefined(font, "font", [[PDFFont_1.default, "PDFFont"]]);
       font = font !== null && font !== undefined ? font : this.getDefaultFont();
-      var fields2 = this.getFields();
-      for (var idx = 0, len = fields2.length;idx < len; idx++) {
-        var field = fields2[idx];
+      var fields3 = this.getFields();
+      for (var idx = 0, len = fields3.length;idx < len; idx++) {
+        var field = fields3[idx];
         if (field.needsAppearancesUpdate()) {
           field.defaultUpdateAppearances(font);
         }
@@ -19351,9 +19351,9 @@ var require_PDFForm = __commonJS((exports) => {
       return nonTerminal;
     };
     PDFForm2.prototype.findNonTerminal = function(partialName, parent) {
-      var fields2 = parent instanceof core_1.PDFAcroForm ? this.acroForm.getFields() : core_1.createPDFAcroFields(parent.Kids());
-      for (var idx = 0, len = fields2.length;idx < len; idx++) {
-        var _a = fields2[idx], field = _a[0], ref = _a[1];
+      var fields3 = parent instanceof core_1.PDFAcroForm ? this.acroForm.getFields() : core_1.createPDFAcroFields(parent.Kids());
+      for (var idx = 0, len = fields3.length;idx < len; idx++) {
+        var _a = fields3[idx], field = _a[0], ref = _a[1];
         if (field.getPartialName() === partialName) {
           if (field instanceof core_1.PDFAcroNonTerminal)
             return [field, ref];
@@ -19408,9 +19408,9 @@ var require_PDFForm = __commonJS((exports) => {
     var parent = _a[0], parentRef = _a[1];
     var field = _b[0], fieldRef = _b[1];
     var entries = parent.normalizedEntries();
-    var fields2 = core_1.createPDFAcroFields("Kids" in entries ? entries.Kids : entries.Fields);
-    for (var idx = 0, len = fields2.length;idx < len; idx++) {
-      if (fields2[idx][0].getPartialName() === partialName) {
+    var fields3 = core_1.createPDFAcroFields("Kids" in entries ? entries.Kids : entries.Fields);
+    for (var idx = 0, len = fields3.length;idx < len; idx++) {
+      if (fields3[idx][0].getPartialName() === partialName) {
         throw new errors_1.FieldAlreadyExistsError(partialName);
       }
     }
@@ -21549,27 +21549,6 @@ function validateResponseDefinition(value) {
       return fail("Unsupported option source");
   }
 }
-function validateResponse(definition, value) {
-  const saved = validateResponseDefinition(definition);
-  const response = object(value, "response");
-  if (saved.source.type === "records") {
-    keys(response, ["selection"], "response");
-    const record = validateRecordReference(response.selection);
-    if (record.repository !== saved.source.collection.repository)
-      fail("Record belongs to another repository");
-    return { selection: record };
-  }
-  keys(response, ["selection", "note"], "response");
-  const choice = id(response.selection, "response selection");
-  const option = saved.source.options.find((option2) => option2.value === choice);
-  if (!option)
-    fail("Choice was not published");
-  if (option.note)
-    return { selection: choice, note: text(response.note, "required note").trim() };
-  if (Object.hasOwn(response, "note"))
-    fail("This choice does not accept a note");
-  return { selection: choice };
-}
 function handlerReference(value) {
   const source = object(value, "handler reference");
   keys(source, ["id", "input"], "handler reference");
@@ -21662,27 +21641,10 @@ function validatePublication(value) {
     recipients: [...new Set([...extra, ...questions.flatMap((entry) => [entry.to, ...entry.allowedResponders])])]
   };
 }
-function recipientPresentation(value) {
-  const publication = validatePublication(value);
-  if (publication.kind === "digest")
-    return publication;
-  return { ...publication, questions: publication.questions.map(({ handler: _private, ...question2 }) => question2) };
-}
-function oddington(value) {
-  const source = object(value, "Oddington assignment");
-  keys(source, ["reason"], "Oddington assignment");
-  return { type: "oddington", reason: text(source.reason, "Oddington reason") };
-}
 function continueAsk(value) {
   const source = object(value, "continueAsk");
-  keys(source, ["assignTo"], "continueAsk");
-  if (source.assignTo === undefined)
-    return { type: "continue" };
-  const assignment = object(source.assignTo, "assignment");
-  keys(assignment, ["type", "reason"], "assignment");
-  if (assignment.type !== "oddington")
-    fail("Only Oddington assignment is supported");
-  return { type: "continue", assignTo: oddington({ reason: assignment.reason }) };
+  keys(source, [], "continueAsk");
+  return { type: "continue" };
 }
 function resolution(value) {
   const source = object(value, "resolution");
@@ -21694,23 +21656,6 @@ function resolution(value) {
 function resolveAsk(value) {
   return { type: "resolve", ...resolution(value) };
 }
-function validateHandlerTransition(value, state) {
-  const source = object(value, "transition");
-  if (source.type === "resolve") {
-    keys(source, ["type", "outcome", "evidence"], "transition");
-    return resolveAsk({
-      outcome: source.outcome,
-      ...source.evidence === undefined ? {} : { evidence: source.evidence }
-    });
-  }
-  if (source.type !== "continue")
-    fail("Unsupported handler transition");
-  keys(source, ["type", "assignTo"], "transition");
-  const transition = continueAsk(source.assignTo === undefined ? {} : { assignTo: source.assignTo });
-  if (transition.type === "continue" && !transition.assignTo && !state.hasOtherViableWork)
-    fail("continueAsk would strand the ask without viable work");
-  return transition;
-}
 function validateResolution(value) {
   const source = object(value, "published resolution");
   keys(source, ["expectedRevision", "outcome", "evidence"], "published resolution");
@@ -21842,146 +21787,340 @@ function validateRoutineRecordWrite(value) {
 function validCreatePath(value) {
   return value === value.trim() && value.endsWith(".md") && !value.startsWith("/") && value.split("/").every((segment) => !!segment && ![".", ".."].includes(segment) && /^[a-zA-Z0-9_.-]+$/.test(segment));
 }
-// ../../shared/inbox-views.ts
-function validateCapturedRecordTableInput(value) {
-  const input = validateRecordTableInput(value);
-  if (!input.repository)
-    fail2("Repository capture is required");
-  return input;
+// ../../shared/connections.ts
+function validGoogleScopes(value) {
+  return Array.isArray(value) && value.length > 0 && value.length <= 32 && value.every((scope) => typeof scope === "string" && scope.length <= 256 && /^(https:\/\/www\.googleapis\.com\/auth\/[A-Za-z0-9._-]+|https:\/\/mail\.google\.com\/|openid|email|profile)$/.test(scope)) && new Set(value).size === value.length;
 }
-var commonViews = [
-  { name: "common/record", implementation: "common/record@1", workspaces: "*", validate: validateRecordViewInput },
-  { name: "common/record-table", implementation: "common/record-table@1", workspaces: "*", validate: validateRecordTableInput }
-];
+
+// ../../shared/connection-lease.ts
+var ROUTINE_CONNECTION_CREDENTIALS_ENV = "ODDINGTON_ROUTINE_CONNECTION_CREDENTIALS";
+var connectionUuid = (v) => typeof v === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(v);
+function parseConnectionLease(raw, now = Date.now()) {
+  const v = raw;
+  if (!v || typeof v !== "object" || Array.isArray(v) || !connectionUuid(v.connectionId) || !connectionUuid(v.runId) || typeof v.name !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(v.name) || typeof v.accessToken !== "string" || !/^[A-Za-z0-9._~+/-]{1,8192}={0,2}$/.test(v.accessToken))
+    throw new Error("Invalid connection credential");
+  if (v.provider === "gmail") {
+    if (Object.keys(v).sort().join(",") !== "accessToken,accountEmail,connectionId,expiresAt,name,provider,runId,scopes" || typeof v.accountEmail !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v.accountEmail) || !validGoogleScopes(v.scopes) || typeof v.expiresAt !== "string" || !Number.isFinite(Date.parse(v.expiresAt)) || Date.parse(v.expiresAt) <= now + 60000 || Date.parse(v.expiresAt) > now + 3600000)
+      throw new Error("Invalid connection credential");
+    return v;
+  }
+  if (v.provider === "airtable" && Object.keys(v).sort().join(",") === "accessToken,baseId,connectionId,name,provider,runExpiresAt,runId" && typeof v.baseId === "string" && /^app[A-Za-z0-9]+$/.test(v.baseId) && typeof v.runExpiresAt === "string" && Number.isFinite(Date.parse(v.runExpiresAt)) && Date.parse(v.runExpiresAt) > now + 60000 && Date.parse(v.runExpiresAt) <= now + 15 * 60000)
+    return v;
+  throw new Error("Invalid connection credential");
+}
+
+// ../../shared/airtable-contract.ts
+class AirtableOperationError extends Error {
+  effect;
+  receipts;
+  constructor(message, effect = "unapplied", receipts = []) {
+    super(message);
+    this.effect = effect;
+    this.receipts = receipts;
+    this.name = "AirtableOperationError";
+  }
+}
+
+// ../../shared/airtable-client.ts
+var recordId = (v) => typeof v === "string" && /^rec[A-Za-z0-9]+$/.test(v);
+var tableId = (v) => typeof v === "string" && /^tbl[A-Za-z0-9]+$/.test(v);
 function fail2(message) {
-  throw new InboxContractError(message);
+  throw new AirtableOperationError(message);
 }
-function object2(value, fields2, required, label) {
-  const copy = serializable(value);
-  if (!copy || typeof copy !== "object" || Array.isArray(copy) || Object.keys(copy).some((key) => !fields2.includes(key)) || required.some((key) => !Object.hasOwn(copy, key)))
-    fail2(`Invalid ${label} fields`);
-  return copy;
+function object2(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v) || ![null, Object.prototype].includes(Object.getPrototypeOf(v)))
+    fail2("Invalid Airtable data");
+  return v;
 }
-function text2(value) {
-  return typeof value === "string" && !!value.trim() && value === value.trim();
+function keys2(v, allowed, required = allowed) {
+  if (Object.keys(v).some((k) => !allowed.includes(k)) || required.some((k) => !Object.hasOwn(v, k)))
+    fail2("Invalid Airtable input");
 }
-function readable(value) {
-  return typeof value === "string" && !!value.trim();
+function text2(v) {
+  return typeof v === "string" && v.length > 0 && v.length <= 1024;
 }
-function recordFields(value) {
-  if (!Array.isArray(value) || !value.length)
-    fail2("Record fields must not be empty");
-  const labels = new Set;
-  for (const entry of value) {
-    const field = object2(entry, ["label", "value"], ["label", "value"], "record field");
-    if (!text2(field.label) || labels.has(field.label))
-      fail2("Record field labels must be distinct");
-    labels.add(field.label);
-    recordValue(field.value);
+function fields2(v, nonempty = false) {
+  const result = object2(v);
+  if (nonempty && !Object.keys(result).length || Object.keys(result).some((k) => !text2(k)))
+    fail2("Invalid Airtable fields");
+  try {
+    return serializable(result);
+  } catch {
+    return fail2("Invalid Airtable fields");
   }
 }
-function recordValue(value) {
-  const kind = value && typeof value === "object" ? value.kind : undefined;
-  switch (kind) {
-    case "text": {
-      const v = object2(value, ["kind", "text"], ["kind", "text"], "text value");
-      if (!readable(v.text))
-        fail2("Record text must be readable");
-      break;
-    }
-    case "missing": {
-      const v = object2(value, ["kind", "label"], ["kind", "label"], "missing value");
-      if (!text2(v.label))
-        fail2("Missing information requires a label");
-      break;
-    }
-    case "record": {
-      const v = object2(value, ["kind", "ref", "label", "recordType"], ["kind", "ref", "label"], "record link");
-      if (!text2(v.ref) || !text2(v.label) || v.recordType !== undefined && !text2(v.recordType))
-        fail2("Invalid supplied record link");
-      break;
+function record(v) {
+  const r = object2(v);
+  if (!recordId(r.id) || r.createdTime !== undefined && (typeof r.createdTime !== "string" || !Number.isFinite(Date.parse(r.createdTime))))
+    fail2("Malformed Airtable record");
+  return { id: r.id, ...r.createdTime === undefined ? {} : { createdTime: r.createdTime }, fields: fields2(r.fields) };
+}
+function equal(a, b) {
+  if (a === b)
+    return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object" || Array.isArray(a) !== Array.isArray(b))
+    return false;
+  const left = Object.keys(a), right = Object.keys(b);
+  return left.length === right.length && left.every((k) => Object.hasOwn(b, k) && equal(a[k], b[k]));
+}
+function createConnections(transport) {
+  return { airtable(name) {
+    if (typeof name !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(name))
+      fail2("Invalid Airtable connection name");
+    const call = (operation, input) => transport(name, operation, input);
+    return {
+      tables: { list: async () => await call("tables.list", {}) },
+      records: {
+        list: async (input) => await call("records.list", input),
+        get: async (input) => await call("records.get", input),
+        create: async (input) => await call("records.create", input),
+        update: async (input) => await call("records.update", input),
+        delete: async (input) => await call("records.delete", input)
+      }
+    };
+  } };
+}
+async function executeAirtableOperation(authority, operation, raw, options = {}) {
+  const { name, baseId, accessToken } = authority;
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(name) || !/^app[A-Za-z0-9]+$/.test(baseId) || !/^[A-Za-z0-9._~+/-]{1,8192}={0,2}$/.test(accessToken))
+    fail2("Airtable connection unavailable");
+  let input;
+  try {
+    input = object2(serializable(raw));
+  } catch {
+    return fail2("Invalid Airtable input");
+  }
+  const mutation = ["records.create", "records.update", "records.delete"].includes(operation);
+  const receipt = (ids2) => ({
+    provider: "airtable",
+    connection: `airtable/${name}`,
+    baseId,
+    table: input.table,
+    operation: operation.slice(8),
+    records: ids2.map((id2) => ({ id: id2 }))
+  });
+  async function request(path2, init = {}, write = false) {
+    let response;
+    try {
+      response = await (options.fetch ?? fetch)(`https://api.airtable.com/v0/${path2}`, {
+        ...init,
+        headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+        redirect: "manual",
+        signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000)
+      });
+    } catch {
+      throw new AirtableOperationError("Airtable request acknowledgment unavailable", write ? "uncertain" : "unapplied");
     }
-    case "list": {
-      const v = object2(value, ["kind", "items", "remaining"], ["kind", "items"], "list value");
-      if (!Array.isArray(v.items) || !v.items.length || v.remaining !== undefined && (!Number.isSafeInteger(v.remaining) || v.remaining < 0))
-        fail2("Invalid Record list or remaining count");
-      v.items.forEach(recordValue);
-      break;
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {});
+      throw new AirtableOperationError("Airtable request rejected", write && (response.status >= 500 || response.status === 408 || response.status < 400) ? "uncertain" : "unapplied");
     }
-    case "object": {
-      const v = object2(value, ["kind", "fields"], ["kind", "fields"], "object value");
-      recordFields(v.fields);
-      break;
+    try {
+      if (!response.headers.get("content-type")?.toLowerCase().includes("application/json"))
+        throw new Error;
+      const value = object2(await response.json());
+      const safe = serializable(value);
+      if (Object.hasOwn(value, "error") || JSON.stringify(safe).includes(accessToken))
+        throw new Error;
+      return value;
+    } catch {
+      throw new AirtableOperationError("Malformed Airtable acknowledgment", write ? "uncertain" : "unapplied");
     }
-    default:
-      fail2("Unknown Record value");
   }
-}
-function validateRecordViewInput(value) {
-  const v = object2(value, ["record", "related"], ["record"], "Record View");
-  if (v.related !== undefined && !Array.isArray(v.related))
-    fail2("Related records must be an array");
-  const refs = new Set;
-  for (const entry of [v.record, ...v.related ?? []]) {
-    const r = object2(entry, ["ref", "title", "recordType", "fields", "body"], ["ref", "title", "fields"], "record");
-    if (!text2(r.ref) || !text2(r.title) || refs.has(r.ref) || r.recordType !== undefined && !text2(r.recordType))
-      fail2("Invalid or duplicate Record reference");
-    refs.add(r.ref);
-    recordFields(r.fields);
-    if (r.body !== undefined) {
-      const body = object2(r.body, ["label", "markdown"], ["label", "markdown"], "Record body");
-      if (!text2(body.label) || !readable(body.markdown))
-        fail2("Invalid Record body");
-    }
+  if (operation === "tables.list") {
+    keys2(input, []);
+    const tables = [], seen = new Set;
+    let offset;
+    do {
+      const query2 = new URLSearchParams(offset ? { offset } : {});
+      const page = await request(`meta/bases/${baseId}/tables?${query2}`);
+      if (!Array.isArray(page.tables))
+        fail2("Malformed Airtable tables");
+      for (const value of page.tables) {
+        const t = object2(value);
+        if (!tableId(t.id) || !text2(t.name) || !text2(t.primaryFieldId) || !Array.isArray(t.fields) || tables.some((existing) => existing.id === t.id))
+          fail2("Malformed Airtable table");
+        const metadata = t.fields.map((value2) => {
+          const f = object2(value2);
+          if (typeof f.id !== "string" || !/^fld[A-Za-z0-9]+$/.test(f.id) || !text2(f.name) || !text2(f.type))
+            fail2("Malformed Airtable field");
+          return { id: f.id, name: f.name, type: f.type, ...f.options === undefined ? {} : { options: serializable(f.options) } };
+        });
+        if (!metadata.some((f) => f.id === t.primaryFieldId) || new Set(metadata.map((f) => f.id)).size !== metadata.length)
+          fail2("Malformed Airtable fields");
+        tables.push({ id: t.id, name: t.name, primaryFieldId: t.primaryFieldId, fields: metadata });
+      }
+      offset = nextOffset(page.offset, seen);
+    } while (offset);
+    return tables;
   }
-  return v;
-}
-function validDate(value) {
-  const parsed = new Date(`${value}T00:00:00Z`);
-  return !value.startsWith("0000-") && Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
-}
-function validateRecordTableInput(value) {
-  const v = object2(value, ["repository", "commit", "columns", "rows", "metadata"], ["columns", "rows"], "record table");
-  const captured = v.repository !== undefined;
-  if ((captured ? !validRepositoryAlias(v.repository) || !/^[0-9a-f]{40}$/.test(v.commit) : v.commit !== undefined) || !Array.isArray(v.columns) || !v.columns.length || !Array.isArray(v.rows) || !v.rows.length)
-    fail2("Invalid record-table capture");
-  const ids = new Set;
-  for (const entry of v.columns) {
-    const c = object2(entry, ["id", "label", "type", "unit", "values", "missing", "missingLabel"], ["id", "label", "type", "missing"], "column");
-    if (!text2(c.id) || !text2(c.label) || ids.has(c.id) || c.missing !== "reject" || !["string", "date", "integer", "number", "boolean", "enum", "nullable-enum", "link"].includes(c.type) || (["integer", "number"].includes(c.type) ? !text2(c.unit) : c.unit !== undefined) || (c.type === "nullable-enum" ? !text2(c.missingLabel) : c.missingLabel !== undefined))
-      fail2("Invalid column definition or units");
-    if (["enum", "nullable-enum"].includes(c.type)) {
-      if (!Array.isArray(c.values) || !c.values.length || c.values.some((s) => !text2(s)) || new Set(c.values).size !== c.values.length)
-        fail2("Enum columns require distinct values");
-    } else if (c.values !== undefined)
-      fail2("Only enum columns accept values");
-    ids.add(c.id);
+  if (!text2(input.table) || input.table === "." || input.table === "..")
+    fail2("Invalid Airtable table");
+  if (mutation && !tableId(input.table))
+    fail2("Airtable writes require a stable table ID");
+  const path = `${baseId}/${encodeURIComponent(input.table)}`;
+  if (operation === "records.get") {
+    keys2(input, ["table", "id"]);
+    if (!recordId(input.id))
+      fail2("Invalid Airtable record ID");
+    const result2 = record(await request(`${path}/${input.id}`));
+    if (result2.id !== input.id)
+      fail2("Malformed Airtable record");
+    return result2;
   }
-  const refs = new Set;
-  for (const entry of v.rows) {
-    const r = object2(entry, ["ref", "version", "values"], ["ref", "values"], "row");
-    if (!text2(r.ref) || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(r.ref) || r.ref.split("/").some((s) => !s || s === "." || s === "..") || refs.has(r.ref) || (captured ? !/^record-v1:[0-9a-f]{64}$/.test(r.version) : r.version !== undefined))
-      fail2("Invalid stable record reference or reviewed version");
-    const values = object2(r.values, [...ids], [...ids], "projected values");
-    for (const c of v.columns) {
-      const cell = values[c.id];
-      const valid = c.type === "nullable-enum" && cell === null || ["string", "enum", "nullable-enum", "link", "date"].includes(c.type) && typeof cell === "string" && (!c.values || c.values.includes(cell)) && (c.type !== "link" || /^\[\[[a-zA-Z0-9][a-zA-Z0-9._/-]*\]\]$/.test(cell)) && (c.type !== "date" || /^\d{4}-\d{2}-\d{2}$/.test(cell) && validDate(cell)) || ["integer", "number"].includes(c.type) && typeof cell === "number" && Number.isFinite(cell) && (c.type !== "integer" || Number.isSafeInteger(cell)) || c.type === "boolean" && typeof cell === "boolean";
-      if (!valid)
-        fail2(`Invalid projected value: ${c.id}`);
-    }
-    refs.add(r.ref);
+  if (operation === "records.list") {
+    keys2(input, ["table", "fields"], ["table"]);
+    if (input.fields !== undefined && (!Array.isArray(input.fields) || !input.fields.length || input.fields.some((f) => !text2(f)) || new Set(input.fields).size !== input.fields.length))
+      fail2("Invalid Airtable field selection");
+    const records2 = [], ids2 = new Set, seen = new Set;
+    let offset;
+    do {
+      const query2 = new URLSearchParams;
+      for (const field of input.fields ?? [])
+        query2.append("fields[]", field);
+      if (offset)
+        query2.set("offset", offset);
+      const page = await request(`${path}?${query2}`);
+      if (!Array.isArray(page.records))
+        fail2("Malformed Airtable records");
+      for (const value of page.records) {
+        const r = record(value);
+        if (ids2.has(r.id))
+          fail2("Malformed Airtable pagination");
+        ids2.add(r.id);
+        records2.push(r);
+      }
+      offset = nextOffset(page.offset, seen);
+    } while (offset);
+    return records2;
   }
-  if (v.metadata !== undefined && (!v.metadata || typeof v.metadata !== "object" || Array.isArray(v.metadata)))
-    fail2("Metadata must be an object");
-  return v;
+  if (!mutation)
+    fail2("Unsupported Airtable operation");
+  keys2(input, ["table", "records"]);
+  if (!Array.isArray(input.records) || !input.records.length || input.records.length > 10)
+    fail2("Invalid Airtable batch");
+  const kind = operation.slice(8), ids = new Set;
+  const records = input.records.map((value) => {
+    const r = object2(value);
+    keys2(r, kind === "create" ? ["fields"] : kind === "update" ? ["id", "expected", "set"] : ["id", "expected"]);
+    if (kind === "create")
+      return { fields: fields2(r.fields, true) };
+    if (!recordId(r.id) || ids.has(r.id))
+      fail2("Invalid Airtable batch record ID");
+    ids.add(r.id);
+    const set = kind === "update" ? fields2(r.set, true) : undefined;
+    if (set && Object.values(set).some((value2) => value2 === null))
+      fail2("Airtable guard null cannot be an update value");
+    return { id: r.id, expected: fields2(r.expected), ...set ? { set } : {} };
+  });
+  for (const r of records) {
+    if (!("id" in r))
+      continue;
+    const current = record(await request(`${path}/${r.id}`));
+    if (current.id !== r.id)
+      fail2("Malformed Airtable record");
+    for (const [key, value] of Object.entries(r.expected)) {
+      if (value === null ? Object.hasOwn(current.fields, key) : !Object.hasOwn(current.fields, key) || !equal(current.fields[key], value))
+        fail2("Airtable reviewed values are stale");
+    }
+  }
+  await options.beforeMutation?.();
+  const query = new URLSearchParams;
+  if (kind === "delete")
+    for (const id2 of ids)
+      query.append("records[]", id2);
+  const result = await request(`${path}${kind === "delete" ? `?${query}` : ""}`, {
+    method: kind === "create" ? "POST" : kind === "update" ? "PATCH" : "DELETE",
+    ...kind === "delete" ? {} : { body: JSON.stringify({ records: records.map((r) => ("id" in r) ? { id: r.id, fields: r.set } : r) }) }
+  }, true);
+  const acknowledged = [], returned = [];
+  try {
+    if (!Array.isArray(result.records))
+      throw new Error;
+    for (const value of result.records) {
+      const r = object2(value);
+      if (!recordId(r.id) || acknowledged.includes(r.id) || kind !== "create" && !ids.has(r.id) || kind === "delete" && r.deleted !== true)
+        throw new Error;
+      acknowledged.push(r.id);
+      if (kind !== "delete")
+        returned.push(record(r));
+    }
+    if (acknowledged.length !== records.length)
+      throw new Error;
+  } catch {
+    throw new AirtableOperationError("Incomplete Airtable mutation acknowledgment", acknowledged.length ? "partial" : "uncertain", acknowledged.length ? [receipt(acknowledged)] : []);
+  }
+  return { receipt: receipt(acknowledged), ...kind === "delete" ? {} : { records: returned } };
 }
-var registeredViews = commonViews;
-function resolveInboxView(view, workspace) {
-  const entry = registeredViews.find((entry2) => entry2.name === view.view && (entry2.workspaces === "*" || entry2.workspaces.includes(workspace)));
-  if (!entry)
-    fail2("View is unknown or unavailable to this workspace");
-  return { ...view, input: serializable(entry.validate(view.input)), implementation: entry.implementation };
+function nextOffset(value, seen) {
+  if (value === undefined)
+    return;
+  if (!text2(value) || seen.has(value))
+    fail2("Malformed Airtable pagination");
+  seen.add(value);
+  return value;
+}
+
+// ../../shared/airtable-transport.ts
+var MANAGED_CONNECTION_CAPABILITY_ENV = "ODDINGTON_MANAGED_CONNECTION_CAPABILITY";
+function managedConnections(capability) {
+  const endpoint = new URL(capability.endpoint);
+  if (endpoint.protocol !== "http:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port || endpoint.pathname !== "/" || endpoint.search || endpoint.hash || endpoint.username || endpoint.password || !/^[0-9a-f-]{36}$/.test(capability.token))
+    throw new AirtableOperationError("Airtable capability unavailable");
+  const transport = async (name, operation, input) => {
+    let safeInput;
+    try {
+      safeInput = serializable(input);
+    } catch {
+      safeInput = null;
+    }
+    try {
+      const response = await fetch(new URL("airtable", endpoint), {
+        method: "POST",
+        redirect: "error",
+        headers: { authorization: `Bearer ${capability.token}`, "content-type": "application/json" },
+        body: JSON.stringify({ name, operation, input: safeInput }),
+        signal: AbortSignal.timeout(125000)
+      });
+      const value = await response.json();
+      if (!response.ok)
+        throw new AirtableOperationError("Airtable operation failed; the execution retains its evidence", value.effect === "partial" || value.effect === "uncertain" ? value.effect : "unapplied", value.receipts ?? []);
+      return value;
+    } catch (error) {
+      if (error instanceof AirtableOperationError)
+        throw error;
+      throw new AirtableOperationError("Airtable parent acknowledgment unavailable", ["records.create", "records.update", "records.delete"].includes(operation) ? "uncertain" : "unapplied");
+    }
+  };
+  return createConnections(transport);
 }
+
+// src/connections.ts
+var connections = createConnections(async (name, operation, input) => {
+  try {
+    const managed = process.env[MANAGED_CONNECTION_CAPABILITY_ENV];
+    if (managed) {
+      const client = managedConnections(JSON.parse(managed)).airtable(name);
+      if (operation === "tables.list")
+        return await client.tables.list();
+      return await client.records[operation.slice(8)](input);
+    }
+    const raw = JSON.parse(process.env[ROUTINE_CONNECTION_CREDENTIALS_ENV] ?? "[]");
+    if (!Array.isArray(raw))
+      throw new Error;
+    const leases = raw.map((value) => parseConnectionLease(value));
+    if (leases.some((lease2) => lease2.provider !== "airtable") || new Set(leases.map((lease2) => lease2.name)).size !== leases.length)
+      throw new Error;
+    const lease = leases.find((lease2) => lease2.name === name);
+    if (!lease || lease.provider !== "airtable")
+      throw new Error;
+    return await executeAirtableOperation(lease, operation, input);
+  } catch (error) {
+    if (error instanceof AirtableOperationError)
+      throw error;
+    throw new AirtableOperationError("Airtable connection unavailable");
+  }
+});
 // ../../shared/delimited-text.ts
 function delimiterFor(value) {
   const counts = new Map([
@@ -22374,37 +22513,20 @@ function routinePublicationClient(options = {}) {
   };
 }
 export {
-  validateResponseDefinition,
-  validateResponse,
-  validateResolution,
-  validateRecordViewInput,
-  validateRecordTableInput,
-  validateRecordSource,
-  validateRecordReference,
-  validatePublication,
-  validateInboxFile,
-  validateHandlerTransition,
-  validateCapturedRecordTableInput,
-  validateBlock,
-  serializable,
   selection,
   routinePublicationClient,
   richTextBlock,
   respond,
-  resolveInboxView,
   resolveAsk,
-  registeredViews,
   recordsBlock,
   recordBlock,
-  recipientPresentation,
   question,
-  oddington,
   fileBlock,
   defineHandler,
-  createInboxPublisher,
   continueAsk,
-  commonViews,
+  connections,
   asksBlock,
   RoutineRecordWriteError,
-  InboxContractError
+  InboxContractError,
+  AirtableOperationError
 };

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

@@ -2,9 +2,16 @@ 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 * from '../../../shared/inbox-contract.js';
-export * from '../../../shared/inbox-views.js';
+export { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
+export type { AskInput, AuthoredSource, CapturedRecords, CsvDetails, 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, Connections } from '../../../shared/airtable-contract.js';
+export declare const connections: import('../../../shared/airtable-contract.js').Connections;
 export type InboxRequester = (path: string, init?: RequestInit) => Promise<Response>;
 export type RoutinePublicationClientOptions = {
     workspace?: string;

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

@@ -0,0 +1,82 @@
+import type { JsonObject, JsonValue } from './inbox-contract.js';
+export type AirtableField = {
+    id: string;
+    name: string;
+    type: string;
+    options?: JsonValue;
+};
+export type AirtableTable = {
+    id: string;
+    name: string;
+    primaryFieldId: string;
+    fields: AirtableField[];
+};
+export type AirtableRecord = {
+    id: string;
+    createdTime?: string;
+    fields: JsonObject;
+};
+export type AirtableListInput = {
+    table: string;
+    fields?: string[];
+};
+export type AirtableGetInput = {
+    table: string;
+    id: string;
+};
+export type AirtableCreateInput = {
+    table: string;
+    records: Array<{
+        fields: JsonObject;
+    }>;
+};
+export type AirtableUpdateInput = {
+    table: string;
+    records: Array<{
+        id: string;
+        expected: JsonObject;
+        set: JsonObject;
+    }>;
+};
+export type AirtableDeleteInput = {
+    table: string;
+    records: Array<{
+        id: string;
+        expected: JsonObject;
+    }>;
+};
+export type AirtableReceipt = {
+    provider: 'airtable';
+    connection: `airtable/${string}`;
+    baseId: string;
+    table: string;
+    operation: 'create' | 'update' | 'delete';
+    records: Array<{
+        id: string;
+    }>;
+};
+export type AirtableWriteResult = {
+    receipt: AirtableReceipt;
+    records?: AirtableRecord[];
+};
+export interface AirtableClient {
+    tables: {
+        list(): Promise<AirtableTable[]>;
+    };
+    records: {
+        list(input: AirtableListInput): Promise<AirtableRecord[]>;
+        get(input: AirtableGetInput): Promise<AirtableRecord>;
+        create(input: AirtableCreateInput): Promise<AirtableWriteResult>;
+        update(input: AirtableUpdateInput): Promise<AirtableWriteResult>;
+        delete(input: AirtableDeleteInput): Promise<AirtableWriteResult>;
+    };
+}
+export interface Connections {
+    airtable(name: string): AirtableClient;
+}
+/** Safe provider failure. An uncertain or partial mutation must never be retried blindly. */
+export declare class AirtableOperationError extends Error {
+    readonly effect: 'unapplied' | 'partial' | 'uncertain';
+    readonly receipts: AirtableReceipt[];
+    constructor(message: string, effect?: 'unapplied' | 'partial' | 'uncertain', receipts?: AirtableReceipt[]);
+}

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

@@ -188,17 +188,12 @@ export type QuestionInstance = {
 export type ResponseSubmission = QuestionInstance & {
     response: QuestionResponse;
 };
-export type OddingtonAssignment = {
-    type: 'oddington';
-    reason: string;
-};
 export type Resolution = {
     outcome: string;
     evidence?: JsonValue[];
 };
 export type HandlerTransition = {
     type: 'continue';
-    assignTo?: OddingtonAssignment;
 } | ({
     type: 'resolve';
 } & Resolution);
@@ -268,6 +263,7 @@ export type HandlerRuntime<Input extends JsonValue = JsonValue> = {
     responseDefinition: ResponseDefinition;
     questionId: string;
     repository: RepositoryCapabilities;
+    connections: import('./airtable-contract.js').Connections;
 };
 export type Handler<Input extends JsonValue = JsonValue> = {
     id: string;
@@ -322,12 +318,7 @@ export declare function validatePublication(value: unknown): Publication;
 /** Structural projection only. The read boundary must check current recipient,
  * workspace and repository/file access before returning this content. */
 export declare function recipientPresentation(value: unknown): RecipientPublication;
-export declare function oddington(value: {
-    reason: string;
-}): OddingtonAssignment;
-export declare function continueAsk(value: {
-    assignTo?: OddingtonAssignment;
-}): HandlerTransition;
+export declare function continueAsk(value: Record<string, never>): HandlerTransition;
 export declare function resolveAsk(value: Resolution): HandlerTransition;
 /** Call at the durable transition boundary with server-derived remaining work,
  * excluding the execution being completed. Lifecycle/effect guards also apply. */

package/package.json

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