@mgcrea/mcp-apple-core 1.24.1 → 1.25.0

package/dist/index.d.ts

@@ -282,6 +282,69 @@ type StdioServerOptions = {
  */
 declare const runStdioServer: (opts: StdioServerOptions) => Promise<void>;
 //#endregion
+//#region src/diagnostics.d.ts
+/**
+ * The half of every surface's diagnostics report that is the same everywhere.
+ *
+ * ## Why this exists
+ *
+ * `apple_<surface>_diagnostics` is the tool an operator reaches for first, and
+ * the eight surfaces had four incompatible ideas of what it should say. Three of
+ * them — Notes, Reminders and Calendar — put their lane report under `server`
+ * and so could not report their own VERSION at all: the first question anyone
+ * asks about a misbehaving server had no answer. Four others reported a name and
+ * a version and then nothing about how they were configured, so `maxResults`,
+ * `indexMode` and the write gate were invisible on exactly the surfaces where
+ * "why can the model not see that tool" gets asked.
+ *
+ * Nothing here is a new fact. It is the union of what the most complete of them
+ * already reported, in one place, so a surface cannot quietly report less than
+ * its neighbour.
+ *
+ * ## What belongs here, and what does not
+ *
+ * `server` is identity: which build is running. `settings` is the configuration
+ * every surface has, from `BaseConfigSchema`. Everything else — lanes,
+ * permissions, stores, caveats — is surface-specific and stays with the surface,
+ * spread around this rather than folded into it.
+ */
+type BaseDiagnosticsInput = {
+  build: BuildInfo;
+  /** The surface's own config. Only the fields every surface shares are read. */
+  config: {
+    exposePrompts: boolean;
+    lazyTools: boolean;
+    maxResults: number;
+    /** Surfaces with a SQLite lane. Omitted by those without one. */
+    indexMode?: string;
+  };
+  /**
+   * Passed explicitly rather than read from `config`, because it is the tool
+   * context that decides what was REGISTERED — and a report that read the flag
+   * from somewhere other than the registration would be free to disagree with
+   * it. Contacts' diagnostics said the surface had no mutating tool for three
+   * releases after two shipped.
+   */
+  allowWrites: boolean;
+};
+type BaseDiagnostics = {
+  server: {
+    name: string;
+    version: string;
+    gitCommit: string;
+    node: string;
+    platform: string;
+  };
+  settings: {
+    allowWrites: boolean;
+    exposePrompts: boolean;
+    lazyTools: boolean;
+    maxResults: number;
+    indexMode?: string;
+  };
+};
+declare const buildBaseDiagnostics: ({ build, config, allowWrites }: BaseDiagnosticsInput) => BaseDiagnostics;
+//#endregion
 //#region src/codes.d.ts
 /**
  * One-time-code extraction, as a pure function over text.
@@ -376,6 +439,65 @@ type ExtractOptions = {
  */
 declare const extractCode: (text: string | null | undefined, { fromShortcode }?: ExtractOptions) => CodeMatch | null;
 //#endregion
+//#region src/confine.d.ts
+/**
+ * Write a file somewhere the caller is allowed to write it.
+ *
+ * ## Why this is shared
+ *
+ * Three surfaces save attachments — Mail, Notes and Messages — and each had its
+ * own copy of this, near enough identical that Messages' comment said so. All
+ * three had the same two holes, which is what a third copy buys you.
+ *
+ * ## The two boundaries
+ *
+ * `root` is the CONFINEMENT: a configured directory, and nothing may be written
+ * outside it. `directory` may only select a subdirectory of it — resolved
+ * *against* the root, so a relative path lands inside and an absolute one is
+ * caught. `name` is basename'd because it comes from message or note content,
+ * which is attacker-controlled in exactly the way path traversal needs.
+ *
+ * ## What the copies got wrong
+ *
+ * **The check was lexical.** `startsWith(root + sep)` compares strings, and a
+ * symlink is a string that points elsewhere: with any component of `directory` a
+ * link, the path passed and the bytes landed outside. Both the root and the
+ * directory are `realpath`ed here before they are compared, so the check is
+ * about where the write actually goes.
+ *
+ * **`existsSync` then `writeFileSync` is check-then-act.** Between the two, the
+ * name can be created — as a symlink to somewhere else, by anything that can
+ * write to that directory. Without `overwrite`, the file is created with `wx`,
+ * which fails if it exists rather than asking first, so the refusal and the
+ * write are one operation the kernel performs.
+ */
+type ConfinedWrite = {
+  /** The confinement boundary. Created if it is not there. */
+  root: string;
+  /** An optional subdirectory of `root`, chosen by the caller. */
+  directory?: string | undefined;
+  /** The leaf name. Basename'd here; callers need not do it first. */
+  name: string;
+  /**
+   * The content, or a function that produces it. A function is called only
+   * once the destination has passed every check, so a refused write never pays
+   * for reading or extracting what it would have written — Mail's extraction
+   * parses the whole message file, which is a lot to spend on a traversal
+   * attempt.
+   */
+  bytes: Uint8Array | (() => Uint8Array);
+  overwrite?: boolean | undefined;
+  /**
+   * Named in the refusal, so the message says how to change the destination
+   * rather than only that it was refused.
+   */
+  settingName: string;
+};
+declare const writeConfinedFile: ({ root, directory, name, bytes, overwrite, settingName }: ConfinedWrite) => {
+  path: string;
+  bytes: number;
+};
+//#endregion
 //#region src/config.d.ts
 /**
  * Environment parsing shared by every server.
@@ -398,7 +520,6 @@ declare const BaseConfigSchema: z.ZodObject<{
   allowWrites: z.ZodDefault<z.ZodBoolean>;
   exposePrompts: z.ZodDefault<z.ZodBoolean>;
   lazyTools: z.ZodDefault<z.ZodBoolean>;
-  debug: z.ZodDefault<z.ZodBoolean>;
   osascriptPath: z.ZodDefault<z.ZodString>;
   osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
   maxResults: z.ZodDefault<z.ZodNumber>;
@@ -751,7 +872,8 @@ declare const project: <T extends Record<string, unknown>>(rows: T[], select: st
  * - `diagnostics` is the live capability report.
  * - `inventory` is the set of containers you address by name: accounts, and
  *   whatever the surface calls its folders. Surfaces with no such containers
- *   (Messages, Safari) register two resources rather than inventing a third.
+ *   (Contacts, Messages, Safari, Maps) register two resources rather than
+ *   inventing a third.
  */
 declare const RESOURCE_SCHEME = "cupertino";
 /** `cupertino://mail/guide`. The one place this string is built. */
@@ -801,10 +923,24 @@ declare const fingerprintSchema: (db: DatabaseSync) => string;
  * disagree about this for Mail, and hardcoding the wrong one puts every date 31
  * years out — a bug that looks like corruption rather than a unit mismatch.
  */
-declare const detectEpoch: (maxTimestamp: number | null, now?: number) => {
+type Epoch = {
   offset: number;
   reason: string;
+  /**
+   * Whether the offset was MEASURED or fallen back to.
+   *
+   * The field that matters, and the reason it is returned here rather than
+   * derived by the caller. An offset of 0 means "measured as unix seconds" and
+   * also "nothing fitted, so unix was assumed", and rendering the second as
+   * though it were the first is the failure this whole module is built around.
+   *
+   * Two surfaces used to recover it by matching a REGEX against `reason` —
+   * prose, across a package boundary. Rewording a sentence here would have made
+   * both of them confidently wrong about an epoch nobody measured, silently.
+   */
+  confident: boolean;
 };
+declare const detectEpoch: (maxTimestamp: number | null, now?: number) => Epoch;
 //#endregion
 //#region src/sqlite.d.ts
 /**
@@ -908,5 +1044,5 @@ declare const limitArg: z.ZodOptional<z.ZodNumber>;
 declare const resolveLimit: (limit: number | undefined, maxResults: number, fallback?: number) => number;
 declare const confirmArg: z.ZodLiteral<true>;
 //#endregion
-export { type Aggregation, AppBusyError, AppNotRunningError, AppleAutomationError, type AxCall, type AxChannel, AxChannelError, BaseConfigSchema, type Bucket, type BuildInfo, CORE_DATA_EPOCH_OFFSET, type CodeConfidence, type CodeMatch, type DateKind, type ExecImpl, type ExtractOptions, type FileFacts, IndexUnavailableError, type Interference, type InterferenceWatch, InvalidDateError, type JxaEnvelope, type LazyToolsOptions, type Logger, type OpenOptions, type OpenedStore, type OsascriptOptions, type OsascriptRunner, OsascriptTimeoutError, type PackageIdentity, type ParsedDate, PlatformError, PreconditionError, type Projected, type PromptContext, ProtocolError, RESOURCE_SCHEME, type ReadOnlyMode, type ResourceReader, SchemaDriftError, type StdioServerOptions, type StoreFacts, type SurfaceContext, type SurfaceResourceOptions, TccDeniedError, type ToolResult, type WorkflowPrompt, WritesDisabledError, addLocalDays, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, endOfLocalDay, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseDate, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, startOfLocalDay, surfaceUri, tableMap, toFailure, toFileUri, toLocalIso, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
+export { type Aggregation, AppBusyError, AppNotRunningError, AppleAutomationError, type AxCall, type AxChannel, AxChannelError, BaseConfigSchema, type BaseDiagnostics, type BaseDiagnosticsInput, type Bucket, type BuildInfo, CORE_DATA_EPOCH_OFFSET, type CodeConfidence, type CodeMatch, type ConfinedWrite, type DateKind, type Epoch, type ExecImpl, type ExtractOptions, type FileFacts, IndexUnavailableError, type Interference, type InterferenceWatch, InvalidDateError, type JxaEnvelope, type LazyToolsOptions, type Logger, type OpenOptions, type OpenedStore, type OsascriptOptions, type OsascriptRunner, OsascriptTimeoutError, type PackageIdentity, type ParsedDate, PlatformError, PreconditionError, type Projected, type PromptContext, ProtocolError, RESOURCE_SCHEME, type ReadOnlyMode, type ResourceReader, SchemaDriftError, type StdioServerOptions, type StoreFacts, type SurfaceContext, type SurfaceResourceOptions, TccDeniedError, type ToolResult, type WorkflowPrompt, WritesDisabledError, addLocalDays, assertStaticScript, buildBaseDiagnostics, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, endOfLocalDay, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseDate, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, startOfLocalDay, surfaceUri, tableMap, toFailure, toFileUri, toLocalIso, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult, writeConfinedFile };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/ax.ts","../src/build-info.ts","../src/osascript.ts","../src/cli.ts","../src/codes.ts","../src/config.ts","../src/dates.ts","../src/facade.ts","../src/fs.ts","../src/listing.ts","../src/prompts.ts","../src/query.ts","../src/resources.ts","../src/schema.ts","../src/sqlite.ts","../src/tools.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/ax.ts","../src/build-info.ts","../src/osascript.ts","../src/cli.ts","../src/diagnostics.ts","../src/codes.ts","../src/confine.ts","../src/config.ts","../src/dates.ts","../src/facade.ts","../src/fs.ts","../src/listing.ts","../src/prompts.ts","../src/query.ts","../src/resources.ts","../src/schema.ts","../src/sqlite.ts","../src/tools.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,8 @@
 import { connect } from "node:net";
-import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { accessSync, constants, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { basename, join, resolve, sep } from "node:path";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
@@ -86,7 +87,7 @@ var PreconditionError = class extends AppleAutomationError {
 var InvalidDateError = class extends AppleAutomationError {
 	name = "InvalidDateError";
 	constructor(field, raw, reason) {
-		super(`Could not read ${field} from ${JSON.stringify(raw)}: ${reason}. Accepted: an ISO-8601 date "2026-08-20" (a whole day, local) or date-time "2026-08-20T09:00" (local unless it carries an offset), a signed offset like "+2d", "-3h", "+45m", "+1w", "today", "yesterday", "tomorrow 09:00", "next monday" or "last friday".`, {
+		super(`${field}: ${JSON.stringify(raw)} could not be read as a date — ${reason}. Accepted: an ISO-8601 date "2026-08-20" (a whole day, local) or date-time "2026-08-20T09:00" (local unless it carries an offset), a signed offset like "+2d", "-3h", "+45m", "+1w", "today", "yesterday", "tomorrow 09:00", "next monday" or "last friday".`, {
 			field,
 			raw
 		});
@@ -358,6 +359,103 @@ const readPackageIdentity = (packageJsonUrl, fallback) => {
 	}
 };
 //#endregion
+//#region src/config.ts
+/**
+* Environment parsing shared by every server.
+*
+* Configuration is environment-only. The sibling servers that also read a
+* `~/.config/<service>/config.json` do so because they hold a private key or an
+* OAuth token; these servers hold no secret at all — their access is the macOS
+* permission the user granted.
+*/
+const trimmed = (v) => {
+	const t = v?.trim();
+	return t ? t : void 0;
+};
+const parseBool = (v) => {
+	const t = trimmed(v)?.toLowerCase();
+	if (t === void 0) return void 0;
+	return t === "1" || t === "true" || t === "yes" || t === "on";
+};
+const parseIntOpt = (v) => {
+	const t = trimmed(v);
+	if (t === void 0) return void 0;
+	const n = Number(t);
+	return Number.isFinite(n) ? n : void 0;
+};
+const parseList = (v) => {
+	const t = trimmed(v);
+	if (t === void 0) return void 0;
+	return t.split(",").map((s) => s.trim()).filter(Boolean);
+};
+/**
+* Settings every Apple-app server has. Extend it rather than repeating them:
+*
+*   const ConfigSchema = BaseConfigSchema.extend({ ... }).strict();
+*/
+const BaseConfigSchema = z.object({
+	allowWrites: z.boolean().default(false),
+	/**
+	* Register the workflow prompts and the surface resources.
+	*
+	* ON by default, unlike `allowWrites`, and the difference is the point: the
+	* write gate is a SAFETY invariant — off means a mutation cannot be reached
+	* even by name — while this is a COST knob, in the same family as
+	* `maxResults`. Conflating the two would muddy the one that matters.
+	*
+	* What it costs, measured across all seven servers with writes on: the
+	* prompt and resource listings come to ~3.4k tokens against ~18.5k for the
+	* tool definitions, so roughly 18% on top of a bill that is dominated by
+	* tools either way. Resource CONTENTS cost nothing until something reads
+	* them. The knob exists for hosts that put every listing in the prompt and
+	* for people counting bytes; if context is the problem, running fewer
+	* servers is the bigger lever by far.
+	*
+	* One flag for both, not two, because they ship as a pair: every prompt
+	* embeds its surface guide, and a prompt naming a `cupertino://…/guide` that
+	* nothing serves would be a dangling reference by configuration.
+	*/
+	exposePrompts: z.boolean().default(true),
+	/**
+	* Serve a searchable index and a dispatcher instead of the full tool list.
+	*
+	* OFF by default, and a COST knob like `exposePrompts` above rather than a
+	* safety gate — but unlike that one it is a knob that TRADES. See
+	* `facade.ts` for the mechanism; the trade is that a host's permission rule
+	* stops naming the individual tool and starts naming a direction: one rule
+	* for this surface's reads, one for its writes.
+	*
+	* What it buys, measured with writes on: ~26.5k tokens of tool definitions
+	* across the eight servers becomes a handful per surface. What it costs
+	* besides the permission granularity is a round trip — a model must search
+	* before it can call.
+	*
+	* Worth switching on only for a client that does not already defer tool
+	* schemas itself. Claude Code and Claude Desktop do, and gain nothing here
+	* while paying both costs, which is why the app declines to write the flag
+	* into their config files at all.
+	*/
+	lazyTools: z.boolean().default(false),
+	osascriptPath: z.string().default("/usr/bin/osascript"),
+	osascriptTimeoutMs: z.number().int().min(1e3).max(6e5).default(3e4),
+	maxResults: z.number().int().min(1).max(1e3).default(200)
+});
+/**
+* Parse an env-derived object against a schema.
+*
+* Undefined values are dropped so zod's defaults apply, rather than failing on
+* an explicitly-undefined key.
+*/
+const parseConfig = (schema, raw) => {
+	const compacted = Object.fromEntries(Object.entries(raw).filter(([, v]) => v !== void 0));
+	const parsed = schema.safeParse(compacted);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+		throw new Error(`Invalid configuration: ${issues}`);
+	}
+	return parsed.data;
+};
+//#endregion
 //#region src/listing.ts
 /**
 * Trimming the SDK's own boilerplate out of `tools/list`.
@@ -476,7 +574,7 @@ const withTrimmedListing = (transport) => {
 */
 const runStdioServer = async (opts) => {
 	const { build, surface, logPrefix } = opts;
-	const debugEnabled = Boolean(process.env[`${surface.envPrefix}_DEBUG`]);
+	const debugEnabled = parseBool(process.env[`${surface.envPrefix}_DEBUG`]) ?? false;
 	const logger = {
 		debug: (...args) => {
 			if (debugEnabled) console.error(`[${logPrefix}]`, ...args);
@@ -500,6 +598,24 @@ const runStdioServer = async (opts) => {
 	process.on("SIGTERM", () => shutdown("SIGTERM"));
 };
 //#endregion
+//#region src/diagnostics.ts
+const buildBaseDiagnostics = ({ build, config, allowWrites }) => ({
+	server: {
+		name: build.name,
+		version: build.version,
+		gitCommit: build.gitCommit,
+		node: process.version,
+		platform: process.platform
+	},
+	settings: {
+		allowWrites,
+		exposePrompts: config.exposePrompts,
+		lazyTools: config.lazyTools,
+		maxResults: config.maxResults,
+		...config.indexMode === void 0 ? {} : { indexMode: config.indexMode }
+	}
+});
+//#endregion
 //#region src/codes.ts
 /**
 * One-time-code extraction, as a pure function over text.
@@ -759,102 +875,49 @@ const extractCode = (text, { fromShortcode = false } = {}) => {
 	};
 };
 //#endregion
-//#region src/config.ts
+//#region src/confine.ts
 /**
-* Environment parsing shared by every server.
+* `realpath` for a directory that may not exist yet.
 *
-* Configuration is environment-only. The sibling servers that also read a
-* `~/.config/<service>/config.json` do so because they hold a private key or an
-* OAuth token; these servers hold no secret at all — their access is the macOS
-* permission the user granted.
+* Resolving the deepest existing ancestor and re-joining what is left is what
+* makes this usable before `mkdir`: a link anywhere in the existing part is
+* followed, and the part that does not exist yet cannot be a link to anything.
 */
-const trimmed = (v) => {
-	const t = v?.trim();
-	return t ? t : void 0;
-};
-const parseBool = (v) => {
-	const t = trimmed(v)?.toLowerCase();
-	if (t === void 0) return void 0;
-	return t === "1" || t === "true" || t === "yes" || t === "on";
-};
-const parseIntOpt = (v) => {
-	const t = trimmed(v);
-	if (t === void 0) return void 0;
-	const n = Number(t);
-	return Number.isFinite(n) ? n : void 0;
-};
-const parseList = (v) => {
-	const t = trimmed(v);
-	if (t === void 0) return void 0;
-	return t.split(",").map((s) => s.trim()).filter(Boolean);
+const realpathOfNearest = (path) => {
+	let current = resolve(path);
+	const trailing = [];
+	for (;;) try {
+		return join(realpathSync(current), ...trailing.toReversed());
+	} catch {
+		const parent = resolve(current, "..");
+		if (parent === current) return resolve(path);
+		trailing.push(basename(current));
+		current = parent;
+	}
 };
-/**
-* Settings every Apple-app server has. Extend it rather than repeating them:
-*
-*   const ConfigSchema = BaseConfigSchema.extend({ ... }).strict();
-*/
-const BaseConfigSchema = z.object({
-	allowWrites: z.boolean().default(false),
-	/**
-	* Register the workflow prompts and the surface resources.
-	*
-	* ON by default, unlike `allowWrites`, and the difference is the point: the
-	* write gate is a SAFETY invariant — off means a mutation cannot be reached
-	* even by name — while this is a COST knob, in the same family as
-	* `maxResults`. Conflating the two would muddy the one that matters.
-	*
-	* What it costs, measured across all seven servers with writes on: the
-	* prompt and resource listings come to ~3.4k tokens against ~18.5k for the
-	* tool definitions, so roughly 18% on top of a bill that is dominated by
-	* tools either way. Resource CONTENTS cost nothing until something reads
-	* them. The knob exists for hosts that put every listing in the prompt and
-	* for people counting bytes; if context is the problem, running fewer
-	* servers is the bigger lever by far.
-	*
-	* One flag for both, not two, because they ship as a pair: every prompt
-	* embeds its surface guide, and a prompt naming a `cupertino://…/guide` that
-	* nothing serves would be a dangling reference by configuration.
-	*/
-	exposePrompts: z.boolean().default(true),
-	/**
-	* Serve a searchable index and a dispatcher instead of the full tool list.
-	*
-	* OFF by default, and a COST knob like `exposePrompts` above rather than a
-	* safety gate — but unlike that one it is a knob that TRADES. See
-	* `facade.ts` for the mechanism; the trade is that a host's permission rule
-	* stops naming the individual tool and starts naming a direction: one rule
-	* for this surface's reads, one for its writes.
-	*
-	* What it buys, measured with writes on: ~26.5k tokens of tool definitions
-	* across the eight servers becomes a handful per surface. What it costs
-	* besides the permission granularity is a round trip — a model must search
-	* before it can call.
-	*
-	* Worth switching on only for a client that does not already defer tool
-	* schemas itself. Claude Code and Claude Desktop do, and gain nothing here
-	* while paying both costs, which is why the app declines to write the flag
-	* into their config files at all.
-	*/
-	lazyTools: z.boolean().default(false),
-	debug: z.boolean().default(false),
-	osascriptPath: z.string().default("/usr/bin/osascript"),
-	osascriptTimeoutMs: z.number().int().min(1e3).max(6e5).default(3e4),
-	maxResults: z.number().int().min(1).max(1e3).default(200)
-});
-/**
-* Parse an env-derived object against a schema.
-*
-* Undefined values are dropped so zod's defaults apply, rather than failing on
-* an explicitly-undefined key.
-*/
-const parseConfig = (schema, raw) => {
-	const compacted = Object.fromEntries(Object.entries(raw).filter(([, v]) => v !== void 0));
-	const parsed = schema.safeParse(compacted);
-	if (!parsed.success) {
-		const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-		throw new Error(`Invalid configuration: ${issues}`);
+const writeConfinedFile = ({ root, directory, name, bytes, overwrite = false, settingName }) => {
+	const confinement = realpathOfNearest(root);
+	const requested = directory ? resolve(confinement, directory) : confinement;
+	const dir = realpathOfNearest(requested);
+	if (dir !== confinement && !dir.startsWith(confinement + sep)) throw new PreconditionError(`Refusing to write outside ${confinement}. Set ${settingName} to change the destination.`);
+	const leaf = basename(name);
+	const target = resolve(join(dir, leaf));
+	if (target !== join(dir, leaf) || !target.startsWith(dir + sep)) throw new PreconditionError(`Refusing to write outside ${dir}.`);
+	const data = typeof bytes === "function" ? bytes() : bytes;
+	mkdirSync(dir, { recursive: true });
+	try {
+		writeFileSync(target, data, {
+			mode: 384,
+			flag: overwrite ? "w" : "wx"
+		});
+	} catch (error) {
+		if (error.code === "EEXIST") throw new PreconditionError(`${target} already exists; refusing to overwrite it.`);
+		throw error;
 	}
-	return parsed.data;
+	return {
+		path: target,
+		bytes: data.length
+	};
 };
 //#endregion
 //#region src/dates.ts
@@ -1697,7 +1760,8 @@ const withBusyRetry = async (fn, delayMs = 1500) => {
 * - `diagnostics` is the live capability report.
 * - `inventory` is the set of containers you address by name: accounts, and
 *   whatever the surface calls its folders. Surfaces with no such containers
-*   (Messages, Safari) register two resources rather than inventing a third.
+*   (Contacts, Messages, Safari, Maps) register two resources rather than
+*   inventing a third.
 */
 const RESOURCE_SCHEME = "cupertino";
 /** `cupertino://mail/guide`. The one place this string is built. */
@@ -1928,16 +1992,11 @@ const fingerprintSchema = (db) => {
 	const ddl = db.prepare("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY type, name").all();
 	return createHash("sha256").update(ddl.map((r) => r.sql).join("\n")).digest("hex").slice(0, 12);
 };
-/**
-* Work out whether a timestamp column is Unix seconds or Core Data seconds by
-* seeing which reading lands near today. Two independent prior-art projects
-* disagree about this for Mail, and hardcoding the wrong one puts every date 31
-* years out — a bug that looks like corruption rather than a unit mismatch.
-*/
 const detectEpoch = (maxTimestamp, now = Date.now()) => {
 	if (maxTimestamp === null || !Number.isFinite(maxTimestamp) || maxTimestamp <= 0) return {
 		offset: 0,
-		reason: "no dated rows; assuming unix seconds"
+		reason: "no dated rows; assuming unix seconds",
+		confident: false
 	};
 	const nowSec = now / 1e3;
 	const tenYears = 315576e3;
@@ -1945,15 +2004,18 @@ const detectEpoch = (maxTimestamp, now = Date.now()) => {
 	const asCoreData = Math.abs(nowSec - (maxTimestamp + CORE_DATA_EPOCH_OFFSET));
 	if (asUnix < tenYears && asUnix <= asCoreData) return {
 		offset: 0,
-		reason: "raw value lands within 10 years of now"
+		reason: "raw value lands within 10 years of now",
+		confident: true
 	};
 	if (asCoreData < tenYears) return {
 		offset: CORE_DATA_EPOCH_OFFSET,
-		reason: "value + 978307200 lands within 10 years of now"
+		reason: "value + 978307200 lands within 10 years of now",
+		confident: true
 	};
 	return {
 		offset: 0,
-		reason: `neither epoch lands near now (max=${maxTimestamp}); assuming unix`
+		reason: `neither epoch lands near now (max=${maxTimestamp}); assuming unix`,
+		confident: false
 	};
 };
 //#endregion
@@ -1997,6 +2059,6 @@ const openReadOnly = (path, mode, opts = {}) => {
 	throw new IndexUnavailableError(`Could not open ${opts.label ?? path} at ${path}: ${message}.${opts.hint ? ` ${opts.hint}` : ""}`);
 };
 //#endregion
-export { AppBusyError, AppNotRunningError, AppleAutomationError, AxChannelError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, InvalidDateError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, addLocalDays, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, endOfLocalDay, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseDate, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, startOfLocalDay, surfaceUri, tableMap, toFailure, toFileUri, toLocalIso, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
+export { AppBusyError, AppNotRunningError, AppleAutomationError, AxChannelError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, InvalidDateError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, addLocalDays, assertStaticScript, buildBaseDiagnostics, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, endOfLocalDay, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseDate, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, startOfLocalDay, surfaceUri, tableMap, toFailure, toFileUri, toLocalIso, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult, writeConfinedFile };
 
 //# sourceMappingURL=index.js.map