Plugin API v1 reference

Petti 1.4 · Plugin API v1 · Experimental

The complete implemented contract for Petti 1.4.0. Experimental APIs and unavailable capabilities are labeled explicitly. Start with the quickstart before using this reference.

This page is generated from the maintained API contract, not a second hand-maintained method list. Code blocks describe API shapes; some are callback fragments, not independently installable packages. Download the Markdown contract for offline reading.

Status: experimental plugin APIs, 2026-09-30. Commands, bounded text/binary previews, read-only inspectors and optional workspaces/jobs, selected-file import/export, bounded database reads/DML and explicit new-app creation/templates, owned-app upgrades, exact-schema adoption and bounded read-only/reviewed write jobs are implemented within the limits below. Bundled and eligible local user packages execute only with explicit consent; user execution also requires the signed isolated helper. Reviewed table/database actions, typed workspace record forms, native composed pages/trees and validated broader app migrations are implemented below. Explicit command file/clipboard grants, typed grid selection, scoped change subscriptions and configured cross-package templates are implemented below. Native streaming transfers and owned-App SELECT materialization are implemented below. General schema mapping, unbounded JavaScript streaming jobs and automatic workflows remain unavailable.

Audit: swift Tools/check-plugin-api.swift checks all runner registries, manifest permission names and JavaScript example syntax without executing examples. Runtime guarantees are exercised by the full source/packaged test suites and the linked safety matrix; syntax checks alone are not behavior verification. Re-run these checks whenever the public boundary changes.

Current public surface and callback scopes

This document describes the JavaScript wire API, not every Swift method used by Petti's native UI. APIs remain experimental. Local user packages require the signed isolated helper, explicit digest-bound enablement and declared permissions; installation never executes code. Registration is declarative; enabling a plugin never authorizes an automatic mutation. Callback capabilities are narrower than a package's complete permission list.

Permission, size, lifecycle and SQLite enforcement remains host-side even if a method exists on the JavaScript context. See PLUGIN_SAFETY_VERIFICATION.md for the test matrix. Runnable examples are the bundled packages in Resources/Plugins; their registration and callbacks run through the same runner/permissions as this contract. All APIs under “Planned, unavailable” are intentionally not promised.

Package and approval

A .petti-plugin directory contains manifest.json and its UTF-8 JavaScript entry:

{
  "id": "com.petti.json-tools",
  "name": "JSON Tools",
  "version": "1.0.0",
  "apiVersion": 1,
  "type": "extension",
  "entry": "main.js",
  "permissions": ["selection.read", "clipboard.write"]
}

IDs use lowercase reverse-domain segments (letters/digits/hyphens). Versions require numeric major.minor.patch without prerelease/build suffixes. Categories extension/tool/workspace/app are metadata; commands, read/reviewed-write table/database actions, structured/text/binary cell previewers and native read-only inspector pages are implemented. Entry paths must be contained relative .js paths. Traversal/symlink escape, oversized/nonregular files, duplicate IDs and unsupported API versions are rejected. Permissions are selection.read, clipboard.read, clipboard.write, database.read, database.events, schema.read, database.write, file.readSelected, file.writeSelected and storage; other requests fail validation. Network access remains unsupported.

Bundled packages: Petti.app/Contents/Resources/Plugins/. User discovery: ~/Library/Application Support/Petti/Plugins/. Opening a database does not scan/run plugins. Tools → Command Palette (Cmd-Shift-P) triggers discovery. Limits: 256 directory entries/root, 64 valid candidates, 16 KiB manifest, 128 KiB script. Malformed packages appear with errors. Duplicate IDs disable all conflicting candidates, including bundled/user collisions.

Bundled plugins start disabled. Enable shows permissions; approval/enabled state is stored in Application Support/Petti/plugin-approvals.json, tied to a digest of manifest/source. Changed content requires approval again on discovery. Disable removes commands, cancels execution and revokes result-copy permission. This is local approval, not publisher signing or cross-process revocation.

Command registration — implemented

petti.registerCommand({
  id: "format-json",
  title: "Format Selected JSON",
  run(context) {
    if (context.selection.text === null) throw new Error("Select one loaded text cell first.");
    return {title: "Formatted JSON", text: JSON.stringify(JSON.parse(context.selection.text), null, 2)};
  }
});

• Command IDs: lowercase letter followed by lowercase letters/digits/hyphens, maximum 80 characters, unique per package. Title: nonempty, maximum 120 JS characters. Maximum 32 commands/package.
• run(context) may be synchronous or async and returns {title: string, text: string}. Output title maximum 160 JS characters, text maximum 65,536 JS characters; host also enforces UTF-8 bounds. Throw Error to display failure. Awaited database calls and Promise results are supported within the same command deadline.
• context.selection.text is exactly one loaded selected Data-grid text cell captured when the palette opens, or null. Deferred/BLOB/multi-cell/query selections are not refetched. Input maximum 64 KiB UTF-8. Supplying selection without selection.read fails at the host boundary. Expanded typed cell/grid/table snapshots are documented below.
• Output is native selectable plain text, not HTML/private SwiftUI. Copy Result requires clipboard.write and is rechecked when clicked; plugins cannot access the clipboard directly.
• A fresh runtime handles registration and each execution; globals do not persist. No timers, fetch, Node require/process, native reflection, filesystem or SQLite objects are provided.

Lifecycle and bounds — implemented

PluginManager serializes installed state. PluginRuntime sends value-only JSON to a short-lived QuickJS interpreter helper (engine-only 2026-06-04, no OS module or CLI). No app/database handles cross the boundary. Request/response maximum 512 KiB, ordinary-invocation wall deadline three seconds, child CPU limit three seconds soft/four hard. Registered jobs instead receive 30 seconds wall / 15 seconds soft and 16 seconds hard CPU. Native transfer/materialization phases use separate bounded host deadlines documented below. Cancellation/disable kills the child. Unexpected exit, malformed output, missing helper, JS errors and timeout are surfaced; later executions recover independently.

Manager generations reject revoked results; the palette separately rejects close/reload/replacement results. Requests, replies and acknowledged events use inherited anonymous pipes with bounded length-prefixed frames. No shared temporary IPC files or plugin-chosen paths exist. Last bounded errors appear under Installed plugins. Commands/jobs have bounded in-memory structured logs; committed mutation outcomes have the separate native persistent history described below. Arbitrary persistent plugin logs are not an API.

The packaged helper is signed with App Sandbox and no file/network exceptions. Its JavaScript runtime uses a fixed 64-MiB mmap allocator arena, including object/string/typed-buffer/Promise allocations. Stack and bounded native bridge buffers are additional memory; the physical-memory watchdog is separate. User execution fails closed unless the host-owned helper has a valid strict signature, versioned identifier and sandbox entitlement. Reserved bundled IDs cannot be supplied by user packages. Unsigned development helpers execute genuine bundled packages only. JavaScript numbers can round large JSON integers; formatted output is interpretive and never edits source data.

Database reads — experimental implemented

The host binds context.database to the currently open database session. It is absent without a database or a declared database.read/schema.read/database.write/database.events permission. No path, raw SQLite handle or session selector is exposed.

petti.registerCommand({id: "find-table", title: "Find table", async run(context) {
  if (!context.database) throw Error("Open a database first.");
  const result = await context.database.query(
    "SELECT name FROM sqlite_schema WHERE type = ? ORDER BY name",
    [{type: "text", value: "table"}]
  );
  return {title: "Tables", text: result.rows.map(row => row[0].value).join("\n") +
    (result.truncated ? "\nResults truncated." : "")};
}});

• query(sql, parameters = []) requires database.read. Exactly one read-only statement, up to 32 KiB SQL, 128 bound parameters and 64 KiB parameter data. Parameters are positional, not interpolated.
• schema() requires schema.read. Returns columns name, type, tbl_name, sql from sqlite_schema, excluding internal sqlite_* names, sorted by name. This is a bounded schema listing, not a full relationship API. database.read can also query SQLite schema directly.
• Both resolve to {columns: string[], rows: Value[][], truncated: boolean}. Always check truncated. Up to 200 rows, 64 columns, 64 KiB per text/BLOB cell, approximately 192 KiB encoded cell data and 256 KiB transport. Oversized cells or transport fail clearly. Rows exceeding the total budget are omitted with truncated=true.
• Values/parameters use {type, value}: integer and finite real are decimal strings; text is UTF-8; blob is base64; null omits value. Output-only textBytes carries invalid UTF-8 SQLite TEXT as base64. Integer strings preserve all signed 64-bit values; converting them to JS Number can lose precision.
• Each call opens a fresh genuine read-only connection, even when the editor is unlocked. PRAGMAs, ATTACH/DETACH, writes, transaction control, extension loading and file functions are denied. Only a conservative built-in function allowlist is exposed; arbitrary SQL functions are not supported.
• Eight calls maximum per command. Query progress deadline 1.5 seconds; lock waits use the existing bounded busy timeout. Total command deadline remains three seconds. Results are buffered only within these bounds. Queries can fail on large sorts/scans; this API is for bounded inspections/samples, not streaming exports or unbounded jobs.
• Permission/enabled generation is rechecked before/after every call. Closing/reopening or observed replacement revokes the session and interrupts active SQL; file identity is checked before/after each read. Cancellation drops results; long SQL is additionally deadline-bounded. Independent calls are not one transaction or stable snapshot. Use Petti snapshots when a fixed historical view is required.
• Reads observe committed WAL data subject to SQLite's normal sidecar/access constraints. No source metadata is injected. The separate bounded write API below never makes query() writable.

Database Tools uses only these public methods for List Tables and Show Schema. Tests cover typed reads, permissions, write/PRAGMA/file denial, size/deadline limits, WAL committed visibility, revocation/replacement, actual helper IPC and locked Workspace/native palette execution.

Transactions — experimental implemented, restricted DML

await context.database.transaction(statements) requires database.write in the approved manifest, a native confirmation for this command invocation, the current database unlocked with a valid editing license, and the same live database session. Enabling a plugin does not mutate data. A helper cannot provide its own approval, policy ticket, database path or SQLite handle.

const result = await context.database.transaction([{
  sql: 'UPDATE "settings" SET "value" = ? WHERE "key" IS ? AND "value" IS ?',
  parameters: [
    {type: "text", value: "dark"},
    {type: "text", value: "theme"},
    {type: "text", value: "light"}
  ],
  expectedChanges: 1
}]);

• One successful commit per command; 1–20 statements, at most 100 expected changed rows, 64 KiB encoded request, 32 KiB SQL/128 parameters per statement. Parameters use the same tagged values as reads. Every statement requires an exact expectedChanges integer (0–100). A mismatch rolls back the entire batch. This is row-count checking, not automatic optimistic concurrency: include observed values/identity in the predicate as above.
• BEGIN IMMEDIATE, statements and COMMIT are owned by one host actor call. No transaction remains open between IPC calls. Results use {columns:["changedRows"], rows:[[{type:"integer",value:"…"}]], truncated:false}. Total changes include SQLite-reported FK cascades and must remain <=100.
• Supported: parameterized INSERT, UPDATE and DELETE on ordinary main-database tables. No RETURNING, DDL, PRAGMA, ATTACH, explicit transaction control, SQL functions, virtual/shadow tables, views, triggered statements, sqlite_* or _petti_* targets. REPLACE and tables whose SQL contains the REPLACE token are conservatively rejected because SQLite omits replacement deletions from change counts. This can reject identifiers/comments containing that token; use native editing for unsupported schemas. Schemas over 2,000 objects or large/unreadable table definitions can be refused.
• Schema inspection and execution share a 1.5-second budget, capped by the helper's remaining three-second command deadline. SQLite lock waits remain bounded. Cancellation, permission-disable task cancellation, session close/replacement, license revocation and relocking are checked at access, between statements, during SQLite progress and at SQLite's commit hook. Lock epochs reject old queued commands even after unlocking again. Checks run below UI/JS layers.
• A commit accepted by SQLite's commit hook is the authorization boundary. Revocation/cancellation after that point cannot undo the already accepted transaction. The host retains a commit receipt: later helper failure is reported as “transaction committed” rather than claiming rollback. Command cancellation does not promise undo of an earlier commit.
• Source identity and SQLite VFS moved-file status are checked; unsupported VFS write verification fails closed. This detects normal source replacement, not an adversarial atomic guarantee against another process renaming files at precisely the commit boundary. Source-preserving snapshots remain available separately.
• This slice does not automatically snapshot each small edit or add plugin changes to cell Undo. Native confirmation says so. Create a snapshot before an operation if a restore point is needed. The table refreshes and stale cell Undo history is cleared after closing a palette where an approved editing command was attempted.

Selected text-cell metadata

With selection.read, context.selection.cell is null or {table, column, identityColumns, identityValues, text} for one loaded editable Data-grid TEXT cell. Keys use the exact tagged representation. The native host refuses generated/deferred/unsupported identity cells. Selection is captured when Commands opens; it can become stale. Plugins must include observed values in update predicates. This API is not a query-result or multi-cell selection API.

The bundled JSON Editing plugin exercises only the public APIs. Compact JSON in Selected Cell validates syntax, removes whitespace outside strings, and writes one optimistic update. It preserves numeric spellings (including 64-bit integers) and duplicate keys rather than parsing and reserializing them. Read-only JSON Tools remains separately enabled and cannot write.

Cell previewers — experimental implemented text and binary slice

petti.registerCellPreviewer({
  id: "text-details",
  title: "Text Details",
  storageTypes: ["text"],
  preview(value) {
    return {title: "Text Details", text: "Characters: " + value.text.length};
  }
});

• Registration requires selection.read. IDs/title validation follows command registration; maximum eight previewers per package, IDs unique within that registry. storageTypes is a nonempty unique subset of ["text", "blob"] (at most two entries). Unsupported types and malformed registrations fail loading. A package can register previewers without commands.
• preview(value) may return or resolve {title, text}. This is Petti-rendered selectable plain text, never HTML or private SwiftUI. Output limits match commands (160 title / 65,536 text JS characters, with host UTF-8 and total IPC limits).
• Complete values up to 64 KiB are supplied: text receives {storageType:"text", text, byteCount}; binary receives {storageType:"blob", base64, byteCount}. Only the matching content field is present. byteCount is the UTF-8/raw-byte count, not base64 length. The host checks canonical base64 and exact decoded length before IPC (64 KiB expands to at most 87,384 base64 characters). Invalid UTF-8, numeric/null values and truncated native previews are not reinterpreted as text. Native cell fetching stays bounded/off-main; the plugin does not choose a row or trigger a second database query.
• Preview callbacks receive no database methods, cell identity, selection context, filesystem or native objects, even if their package also declares database.write. The helper database bridge has no host capability during previews. Previewing never requests unlock or an editing license.
• Enable JSON Tools in Tools → Command Palette → Installed plugins (a changed bundle requires approval again). Open a cell with Space/Preview Cell, then choose JSON Outline under Plugin Preview. Registration is discovered when a preview is opened if needed; no preview callback runs until explicitly chosen. Opening/scrolling a database never invokes a previewer.
• Native Raw/Hex/JSON/Image remain available. Plugin errors/timeouts leave native content intact. The runtime retains the existing three-second wall/CPU/IPC bounds. Close/reload/replacement cancels pending results; disable/re-discovery invalidates output and available choices through host lifecycle observation. Copy of plugin output additionally requires clipboard.write and rechecks enablement when clicked. Save Bytes always saves native fetched bytes, never plugin output.
• JSON Outline walks up to 256 entries and 16 levels, with bounded path/scalar labels. It is interpretive JSON.parse output (large numbers can round and duplicate keys collapse); its notice points to Raw for exact values. It now also supplies the public structured tree for native expansion/collapse. No source changes occur.

Verification: PluginPreviewerTests exercise the real helper/registry, permissions, duplicate/type validation, bounded input/output, absent capabilities, timeout/cancellation/disable/recovery and the actual bundled outline. PluginPreviewUITests exercises the native menu/model output, fallback on invalid JSON, disabled/closed output disposal, oversized-text refusal, copy permission and light/dark layout. It accepts PETTI_PLUGIN_TEST_BUNDLE to exercise packaged resources/helper. The host Swift changes() stream is internal lifecycle plumbing, not a JavaScript database-change event API.

Embedding Inspector — implemented interpretation, not detection

Enable Embedding Inspector in Tools → Command Palette → Installed plugins. It registers two BLOB previewers: Interpret as Float32 (Little Endian) and Interpret as Float32 (Big Endian). Open a BLOB with Space/Preview Cell, then choose the byte order under Plugin Preview. Matching previewers alone appear in that menu; none execute automatically. Enabling this preview-only plugin does not add a command or change the database.

The plugin decodes the public base64 payload into a bounded Uint8Array and uses DataView.getFloat32. No native decoder or private application API is used. Nonempty lengths divisible by four yield component count (candidate dimension), finite/NaN/+Infinity/-Infinity counts, finite min/max/mean/L2 norm and the first 16 component values. Statistics exclude non-finite components and say so. The output explicitly does not identify an embedding; ordinary bytes can also represent floats. Encoding/byte order must be confirmed with the originating application. Empty/misaligned inputs produce a clear error with native Raw/Hex still available.

There is no sqlite-vec detection, schema scan, model/provider inference, dimension guessing from common models, similarity search, vector editing or SQL extension loading in this slice. A maximum 64 KiB BLOB contains 16,384 Float32 components. Larger or truncated native previews cannot be sent to plugins: native fetch remains capped at 1 MiB, and oversized BLOBs are never refetched in full for this inspector. Copy requires clipboard.write; Save Bytes remains the unchanged native byte export.

BinaryPreviewTests cover byte order, exact transport, malformed/oversized/empty/misaligned inputs, finite/non-finite statistics, maximum payload and revocation. BinaryPreviewUITests covers menu type matching, lazy BLOB fetch, the 2 MiB truncated fixture, source-byte preservation, light/dark layout and close/disable invalidation. The generic helper tests also cover cancellation with binary input and absence of database access even for a package declaring database.write.

Table actions — implemented read-only slice

petti.registerTableAction({
  id: 'definition',
  title: 'Show Table Definition',
  async run(context) {
    const result = await context.database.query(
      "SELECT sql FROM sqlite_schema WHERE type='table' AND name=?",
      [{type:'text', value:context.table.name}]
    );
    return {title:'Definition', text:result.rows.map(row => row[0].value || '').join('\n') +
      (result.truncated ? '\nResults limited.' : '')};
  }
});

• Up to 32 actions per package. IDs use the command ID syntax and are unique within the table-action registry; titles are nonblank, at most 120 JavaScript code units and 480 UTF-8 bytes. A run function is required. Host validates the exported registry before making it available.
• Registration requires selection.read. The action receives a frozen context.table with name, schema:'main', kind:'table'. This is the explicitly chosen sidebar table, not necessarily the table currently being browsed. Names are limited to 4,096 UTF-8 bytes and cannot contain NUL. No row/cell data is supplied.
• Context database.query/schema use existing declared database.read/schema.read permissions and bounded parameterized read-only access. There is no transaction, selection, raw SQLite handle, file or write API. Host strips database.write even when granted to the package and the database is unlocked/licensed.
• Returns the existing command {title,text} output: at most 160/65,536 JavaScript code units, also host-capped at 640/262,144 UTF-8 bytes. Errors appear inline. Existing helper timeout, query cancellation, session revocation and permission checks apply.
• Right-click a sidebar table → Plugin Actions → Choose Action… opens the native action panel. Enable a bundled plugin there, select an action and Run. Discovery happens on this explicit request; normal opening and menu construction perform no plugin database queries. Results are selectable; Copy Result requires clipboard.write. Cancel/close/database refresh or replacement discards pending results. Enabling/disabling through the panel clears its output; manager revocation rejects running actions across windows.
• Database Tools supplies Show Table Definition using only this API. It binds the table name, handles removed/renamed tables, preserves query truncation and reports oversized definitions as errors. No table-data scan or count is performed. The updated package digest and selection.read capability require renewed explicit approval.
• Views, attached/temp schemas and direct per-plugin menu population remain unsupported. Reviewed write-capable table actions are documented below. Returned text is a point-in-time result, not live schema monitoring.

Verification: PluginTableActionTests cover registration/duplicate validation, quoted/missing names, closed sessions, exact context, malformed output, missing permissions, writes denied while unlocked, source preservation, timeout/cancel/disable/recovery. PluginUITests covers native table-action panel behavior, the clicked-table context, read-only operation, disable/close/closed-session and light/dark layout. Ordinary command and inspector APIs remain intact.

Database actions — implemented read-only slice

petti.registerDatabaseAction({
  id: 'schema-names',
  title: 'Show Schema Names',
  async run(context) {
    const result = await context.database.schema();
    return {title:'Schema names', text:result.rows.map(row => row[0].value).join('\n') +
      (result.truncated ? '\nPartial listing; more objects may exist.' : '')};
  }
});

• Maximum 32 actions per package, unique IDs within this registry using command ID syntax. Nonblank title <=120 JavaScript code units / 480 UTF-8 bytes, required run function. Both helper and host validate registrations. IDs may coincide with IDs in other registries.
• At least one of database.read/schema.read is required to register. No selection.read requirement: no table, cell, selected text, database URL or native objects are supplied. The frozen context contains only the frozen database query/schema interface.
• query requires database.read; schema requires schema.read. schema returns name/type/tbl_name/sql, excludes SQLite internal objects, and retains existing 200-row/cell/byte/time caps. Output is not a full database analysis. A nonempty schema can exceed output limits.
• Host strips write permissions even when the package declares database.write and the session is unlocked/licensed. No transaction, file access or raw SQLite handles are exposed. Requires a current database session; existing revocation, cancellation, deadlines and read-only authorizer remain active.
• Returns the same validated title/text output as table actions (<=160/65,536 JavaScript code units and host <=640/262,144 UTF-8 bytes). Copy is a separate native action requiring clipboard.write.
• Tools → Database Actions… opens a native filtered action panel with plugin approval, explicit Run, Cancel, output/error and Done. Opening this panel discovers registrations; it does not run actions or query the database. No plugin work is added to normal database opening or menu construction.
• Database Tools → Show Schema Overview uses the public schema API. It shows object types/names/owning tables and the number actually displayed, explicitly excludes internal objects, labels row/byte/text truncation as partial, and distinguishes empty schema from zero objects fitting in the text budget. No table rows are counted or scanned. Oversized schema cells produce the existing explicit query error.
• Close/reload/replacement cancels panel work; manager revocation rejects running actions. Results are point-in-time text, not live monitoring. Reviewed write actions and jobs are documented below; specialized doctor/PII/ER tools are separate.

Verification: PluginDatabaseActionTests cover reference names/count-of-shown semantics, empty/200-row/text-budget limits, invalid/duplicate/excess registrations, permissions, missing/closed sessions, narrow context, write denial while unlocked, source preservation, malformed output and timeout/cancel/disable/recovery. PluginUITests covers the native action panel with read-only results, enable/disable, close/revocation and both appearances. Packaged tests exercise the bundled helper/resources.

Importers — implemented bounded file-to-table slice

petti.registerImporter({
  id: 'my-format',
  title: 'Import My Format',
  parse(input) {
    // input.text is the chosen UTF-8 file, never a path or database context.
    return {columns:['value'], rows:[[{type:'text',value:input.text}]], truncated:false};
  }
});

• Up to eight importers/package, IDs unique in this registry with command ID syntax, title nonblank <=120 JavaScript code units / 480 UTF-8 bytes, required parse function (may return a Promise). Registration requires file.readSelected and database.write. Existing third-party execution restrictions still apply.
• file.readSelected is a single native-selected file-content grant, not a filesystem API. The host opens a regular non-symlink file, reads at most 32 KiB plus one byte to detect oversize, requires UTF-8, and passes only frozen {text}. No path, filename, database handle/query/write bridge or arbitrary file access is supplied to parse. Native file reading and helper parsing are off the UI thread.
• Result uses existing tagged SQL values: complete {columns,rows,truncated:false}, 1–20 rows, 1–8 unique nonempty source column names <=128 UTF-8 bytes, <=32 KiB encoded parsed result. Only text, integer (exact Int64 string), finite real string and NULL are accepted. Invalid types/shape, truncated or oversized results fail before a draft is created.
• A host-owned, session-bound, single-use draft is shown in a native preview/mapping sheet. Plugin code cannot change a reviewed draft or submit SQL. Each source field maps to a distinct writable destination column or Skip; at least one mapping is required. Omitted destination columns use SQLite defaults; explicit NULL stays NULL. Destination generated columns cannot be mapped.
• Host generates quoted, parameterized INSERTs into an existing main-schema ordinary user table, with one expected affected row per input row. Existing 20-statement/100-change/64-KiB transaction limits apply. No create-table, replace/upsert, triggers, virtual/shadow/internal/Petti metadata writes are added. Existing conservative plugin write restrictions may reject tables supported by native CSV import.
• Preview may run while locked. Commit requires explicit native confirmation, an editing license and unlocked database, plus unchanged plugin approval/session. Host compares schema_version and table SQL inside BEGIN IMMEDIATE before inserting. Relock, close/replacement, cancellation and plugin revocation are checked at the write/commit boundary. Constraint errors roll back the entire import.
• Drafts are invalidated on reload/enable-disable and consumed on an approved commit attempt (including failure). Rechoose/review the file to retry. Cancelling after SQLite has already accepted COMMIT cannot undo it; the panel reports this possibility and the browser refreshes after closing the parent palette. Imports are not cell-Undo actions; the confirmation suggests a manual snapshot.
• Select a table, open Tools → Command Palette, enable JSONL Import under Installed plugins, then Importers → Import JSONL. A table's Plugin Actions panel also exposes its importers. Choose a file, review source values, map columns, Import Rows… and confirm. Opening/enabling the plugin never imports anything. Native CSV import/export is unchanged.
• Bundled JSONL Import uses only registerImporter. Nonblank lines must be flat objects with the same 1–8 keys, at most 20 rows. Strings, NULL, booleans (0/1) and safe integer JSON numbers are supported. Duplicate keys (including escaped aliases), nesting, decimal/exponent numeric tokens and integers beyond ±9,007,199,254,740,991 are rejected before JSON.parse can round them. Quote larger integers/decimals as strings; SQLite destination affinity still applies, so use a TEXT destination when exact textual representation must be preserved.
• The parse callback is a small-file importer; the separate nativeFormat registrations below support whole-file streaming. No file picker/paths in JavaScript, generic file API, persistent file grant, background job, XLSX/Parquet or schema creation is implied.

Verification: PluginImporterTests exercise actual JSONL parsing/mapping/commit, exact string values/defaults, source-row limits, malformed/precision/duplicate-key rejection, file-size/symlink limits, registration/permissions/parser isolation, invalid results, lock/license/confirmation, single-use drafts, schema change, disable/closed session, constraint rollback, cancellation, timeout and invalid mappings. PluginUITests exercises native preview/mapping in both appearances, locked denial, actual unlocked import, refresh, close and expired session. Existing plugin transaction tests remain regression coverage.

Custom JavaScript exporters — implemented bounded preview-to-file slice

petti.registerExporter({
  id: 'jsonl',
  title: 'Export Previewed Rows as JSONL',
  fileExtension: 'jsonl',
  render(input) {
    return input.rows.map(row => '{' + row.map((cell, i) => {
      let value;
      if (cell.type === 'null') value = 'null';
      else if (cell.type === 'text') value = JSON.stringify(cell.value);
      else if (cell.type === 'integer' || cell.type === 'real') value = cell.value;
      else throw Error('Unsupported storage type');
      return JSON.stringify(input.columns[i]) + ':' + value;
    }).join(',') + '}\n').join('');
  }
});

• Up to eight exporters/package. IDs are unique within the exporter registry and use command ID syntax; title nonblank <=120 JavaScript code units / 480 UTF-8 bytes. fileExtension is 1–10 lowercase ASCII letters/digits. A render function (possibly async) is required. Registration requires database.read and file.writeSelected.
• Explicit native Preview fetches at most the first 21 rows of the chosen ordinary main-schema table through the existing read-only query boundary. Only the first 20 are passed to the renderer; the extra row detects a subset. No COUNT or full-table materialization. Current grid filters/sort/selection are intentionally not used; the UI labels this scope before querying and saving.
• Frozen input contains {scope:'firstRows',limit:20,columns,rows,truncated}. Arrays and tagged cell objects are frozen. Input uses the existing exact SQL value tags, at most eight columns and 32 KiB encoded preview data. This is a point-in-time bounded subset; truncated means more data existed at capture. Data that exceeds cell/input limits fails clearly.
• Renderer receives no database methods, source/destination paths, selected-cell context, native objects or filesystem access. Host-owned prepared output cannot be changed by the plugin after review. Return a text string <=65,536 JavaScript code units AND <=65,536 UTF-8 bytes. Normal helper timeout/cancellation/message bounds apply.
• Bundled JSONL Export preserves full Int64 strings by emitting validated numeric tokens without converting them through JavaScript Number. Text uses JSON.stringify, NULL is null, and empty text stays "". Finite real values retain the SQLite double’s representation. BLOB and non-UTF-8 TEXT are explicitly rejected; there is no implicit hex/base64 scheme.
• Select a table → Tools → Command Palette → enable JSONL Export → Exporters. The same exporters are available from a table’s Plugin Actions panel. Preview First 20 Rows is explicit; opening/enabling does not query/export. Review the native row table and optional file-text preview, then Save Previewed Rows… in a native Save panel. Default filename includes first-20. Saving an empty preview creates an empty file.
• file.writeSelected grants only host-controlled writing to the native-chosen destination. The plugin never supplies a path. Existing destinations require the native Save panel’s replacement approval. The host rejects the source database and -wal/-shm/-journal paths (case-insensitive conservatively, including absent companions), aliases via symlinks/hard links, directories and final-component symlinks.
• Host stages a 0600 file with exclusive creation in the opened destination directory, fsyncs its data, rechecks session/revocation/cancellation and destination identity/size/mtime, then publishes with atomic rename. New destinations use exclusive rename so an appearing file is not silently replaced. Approved replacement uses atomic rename; failures before publication clean up staging and preserve the existing target. This is not a cross-process filesystem lock.
• Preview drafts are single-use on a save attempt; regenerate after an error. Disable/discovery, close/replacement or cancellation invalidates pending saves. Cancellation after publication cannot remove an already-saved file; the UI says so. Saving remains available in locked/unlicensed read-only sessions and never requests database.write.
• The render callback remains first-20 only. nativeFormat registrations below add full-table streaming; plugin filtered/selected-row streaming, binary output, arbitrary file access and persistent file grants remain unavailable. Native streaming CSV/JSON/SQL export is unchanged. Destination/format limits are explicit rather than silently exporting a sample as a whole table.

Verification: PluginExporterTests cover exact Int64/NULL/empty/escaped JSON bytes, locked-session saves, first-20/empty scope, unsupported values, input/output/registration/permission limits, missing approval, one-shot/disabled/closed/cancelled drafts, timeout, source/companion hard-link and symlink protection, replacement, staged cancellation, changed destination and temporary cleanup. PluginUITests covers native preview/save/subset labeling/light/dark, unchanged read-only source, close and disabled-save behavior. Packaged runs use actual bundled resources/helper.

Declarative inspectors — experimental flat-page slice

petti.registerInspector({
  id: 'find-schema',
  title: 'Find Schema Objects',
  description: 'Search schema metadata without scanning table rows.',
  actionTitle: 'Search',
  fields: [
    {id:'name', type:'text', label:'Name contains', initialValue:''},
    {id:'kind', type:'select', label:'Type', initialValue:'', options:[
      {value:'',label:'All'}, {value:'table',label:'Tables'}, {value:'view',label:'Views'}
    ]}
  ],
  async run(context, fields) {
    if (!context.database) throw Error('Open a database first.');
    return await context.database.query(
      "SELECT name,type,sql FROM sqlite_schema WHERE instr(name,?) > 0 AND (?='' OR type=?) ORDER BY name",
      [{type:'text',value:fields.name},{type:'text',value:fields.kind},{type:'text',value:fields.kind}]
    );
  }
});

Registration declares inert data; Petti renders the title, description, native form, explicit action button and bounded native table. There are no private SwiftUI objects, web views, raw HTML or arbitrary UI event callbacks. Bounded recursive declarative component trees are supported through layout/page, documented below. Fields support text, select, multiSelect, date, number and checkbox. No jobs, workspaces or app schema changes are implied.

• Maximum eight inspectors/package, eight fields/page and 16 KiB encoded page. IDs use command ID syntax and are unique within each registry/page. Required title (<=480 UTF-8 bytes), description (<=2,048 bytes), actionTitle (nonempty <=160 bytes), fields array and run function. Unsupported field types, duplicate IDs and invalid definitions fail loading.
• Fields require id/type/label/initialValue. Labels <=160 UTF-8 bytes; text/select initial and user values are strings <=1,024 bytes. Selects require 1–32 unique string-valued options {value,label}, and initial/user value must match an option. Only select and multiSelect fields accept options. All fields must be supplied exactly once; extra/missing input keys fail before execution.
• Multi-select uses type:"multiSelect" with a string-array initialValue and submitted value, plus 1–32 unique options using the select option shape. Each selected string is <=1,024 UTF-8 bytes, unique and present in options; no scalar, mixed array, nesting or coercion is accepted. Empty selections are valid and mean none in the reference Schema Inspector. Defaults are validated too. All submitted fields together are limited to 16 KiB of encoded JSON. Native labeled checkboxes emit selections in declared option order; the host accepts any valid unique order and preserves it. Both fields and selection arrays are frozen in the helper. No automatic query runs when toggling a choice.
• Example: {id:"kinds",type:"multiSelect",label:"Object types",initialValue:["table","view"],options:[{value:"table",label:"Tables"},{value:"view",label:"Views"}]}.
• Date fields use type:"date", a strictly validated Gregorian YYYY-MM-DD string initialValue and submitted value, and optional inclusive minimumDate/maximumDate strings. Supported years are 1600–9999 (avoids historical calendar cutover ambiguity). Impossible dates, non-padded dates, time/offset suffixes, whitespace, wrong types, invalid/reversed bounds and out-of-range values fail at the host. Date bounds are only valid on date fields; numeric constraints/options are rejected. The default bounds are 1600-01-01 and 9999-12-31. No empty/null date is supported yet.
• Petti renders a native date-only picker using a Gregorian UTC calendar, even on Macs using another calendar/time zone. The plugin receives a calendar day string, not a JavaScript Date or implicit local instant. Existing text fields remain plain strings. The host does not change SQLite result values. Example: {id:'day',type:'date',label:'Day',initialValue:'2024-02-29',minimumDate:'2024-01-01',maximumDate:'2024-12-31'}.
• Database Tools → UTC Date & Timestamp is an offline reference inspector: choose a day, click Convert Date, see UTC midnight ISO text and exact integer Unix seconds (negative before 1970). It defaults to the current UTC day at registration, performs no database access and also runs without a database context. It uses the public inspector API only; cancellation, disable and close discard pending results as usual. Updated package content requires approval again.
• Number fields use JSON numbers for initialValue and submitted values, with optional finite numeric minimum/maximum and optional boolean integer. Bounds are inclusive and ordered; all numbers/bounds must be finite and within ±9,007,199,254,740,991. integer:true rejects fractional inputs. Values use JavaScript double precision; decimals are approximate. Use text fields for exact larger integers/decimal strings. SQLite query-result Int64 strings are unchanged. Numeric constraints on other field types are rejected.
• Checkbox initialValue and submitted values must be JSON booleans. There is no string/number/boolean coercion. Missing/extra fields, invalid defaults, wrong types and invalid ranges fail at the host before executing the action.
• Number UI preserves draft input until Run; invalid/empty drafts show an inline error, never silently reuse an older value. Decimal entry uses a period (scientific notation accepted). Native toggles and labeled fields participate in keyboard/accessibility navigation.
• Example additional fields: {id:'limit',type:'number',label:'Maximum results',initialValue:200,minimum:1,maximum:200,integer:true} and {id:'internal',type:'checkbox',label:'Include internal objects',initialValue:false}. Existing text/select package definitions and their string-valued run inputs are unchanged.
• run(context, fields) can be async and returns either the existing typed {columns, rows, truncated} shape or the tabbed result shape documented below. Petti validates 1–64 columns (names <=512 UTF-8 bytes), <=200 equally sized rows, supported tagged cell types and <=256 KiB encoded result. Text/BLOB cells are bounded at 64 KiB; integer values stay strings, preserving full Int64 precision. A malformed result is an error, not an empty table.
• Inspector context supplies declared database.read/schema.read capabilities via query/schema/tableSchema, plus bounded progress events (see composed pages below). No selection, file or write capability is supplied, even if the package declares database.write. The host removes write permissions at the DB callback boundary. Existing query limits, RO connections, cancellation and session identity checks apply. No unlock/license is requested for reading.
• Opening a page does not run its action or query data. Explicit clicks run in the short-lived helper/background database worker, with the existing three-second command deadline. The native page provides loading/cancel/error/empty-result/explicit truncation states. Cancel/close/replacement discard late results; plugin configuration changes clear displayed results and require reopening. Field edits do not automatically query.
• Enable Database Tools under Tools → Command Palette → Installed plugins, then open Inspectors → Schema Inspector. Its changed source digest requires approval again. It initially selects tables/views/indexes/triggers, supports multiple kinds with bound SQL parameters, and returns zero matches when none are selected. It uses parameterized schema-name/type filters, excludes SQLite internal objects by default, offers an explicit inclusion checkbox and a 1–200 result limit, and never counts or scans data tables. It requests one extra row to distinguish complete results from a user limit, preserving the bridge’s own row/byte truncation flag. The ordinary browser stays available outside this optional sheet.
• Table display is read-only and separate from the main grid. NULL is explicit; BLOB/invalid-UTF8 cells display labeled base64 prefixes. No inline editing, paging, sorting, copying/exporting or richer cell rendering is promised for this secondary result table yet.

The original fixed page/form/action/results arrangement remains supported. The composed native page API below adds stacks, forms, alerts/progress, charts and calendars. Writable workspace CRUD forms are documented below; arbitrary inspector callback graphs remain planned. Manager lifecycle streams remain host-only; the explicit public database change API is documented below.

Verification: PluginInspectorTests cover registration/field/result bounds, duplicates, parameterized quoted names, empty/truncated results, source preservation, read permission denial, no write capability even in a write-permitted package, exact Int64 output, closed sessions, timeout/cancellation/disable/recovery. PluginInspectorUITests cover the actual palette/form/table flow, locked unlicensed reading, light/dark layout, error/empty/disable/close states and exact native integer/NULL display. PETTI_PLUGIN_TEST_BUNDLE runs native tests against packaged resources/helper.

Reference and verification

Resources/Plugins/JSONTools.petti-plugin uses only registerCommand, selection and text output. JSON Outline uses public preview registration and the bounded structured tree output. Native Raw/Hex/JSON/Image representations remain separate; Embedding Inspector uses the same public preview registry and value-only input. Structured trees are implemented below; arbitrary custom native renderers remain unavailable.

PluginTests cover validation/paths/version/duplicates, consent/persistence/digest changes, user rejection, permissions/absent native APIs, actual JS execution/errors, timeout/cancellation/output/recovery and in-flight disable. PluginUITests cover native output/layout, copy permission, disable, missing selection and late-close results. PETTI_PLUGIN_TEST_BUNDLE=/absolute/Petti.app swift test --filter PluginUITests checks packaged helper/resources.

Planned, unavailable

Unrestricted network/filesystem access; SQLite native extension loading; custom JavaScript streaming transformations and filtered/selected-row plugin stream scopes; durable/resumable jobs and unattended automation; production vertical allocation/timetable applications. The bounded Analytics Workbook and its supported sources/transforms are implemented below. General foreign-key/CHECK definitions and raw SQL/data-transform App migrations are unavailable. Implemented extensions are documented in the sections below; ordinary databases are never implicitly adopted.

Inspector result tabs (implemented, experimental V1)

An inspector may return {tabs:[{id,title,table}]} instead of a single table. Each table is the same typed {columns,rows,truncated} result. Do not mix top-level tabs with columns/rows/truncated, even null values: the host rejects ambiguous shapes. Existing single-table plugins continue unchanged.

return {tabs:[
  {id:'tables',title:'Tables',table:tablesResult},
  {id:'views',title:'Views',table:viewsResult}
]};

• One to six tabs, unique IDs using command ID syntax, unique nonblank titles <=80 UTF-8 bytes. Keep titles short for native tab labels. No arbitrary view objects, HTML, nested tab layouts or per-tab callbacks.
• The entire result has a shared 256-KiB JSON limit and 200-row limit across all tabs. Each table retains the existing rectangular shape, 1–64 columns, cell/type/byte checks. Extra tabs do not multiply these bounds. Invalid results fail as a whole; the host does not silently discard tabs or rows.
• Each tab carries its own truncation flag and native result count/empty state. Switching tabs changes presented data without rerunning JavaScript or querying SQLite. The first tab is selected after each successful run. A new run, cancellation, plugin configuration change, close or replacement clears all output and selection.
• Native macOS tabs use the existing read-only table renderer and preserve exact integer strings. The normal browser/grid is unchanged.
• Database Tools → Schema Overview is the reference: four schema queries, up to 50 non-internal objects per kind (tables/views/indexes/triggers), one look-ahead row for accurate truncation. It never counts/scans table data or requests editing. Separate queries can observe schema changes between reads; this is live metadata, not an atomic snapshot. Very large schema SQL may exceed the shared byte cap and produce an explicit error.
• Internal Swift callers use PluginManager.inspectPage for the result union. The previous inspect convenience method accepts single-table inspectors and explicitly rejects tabbed output instead of flattening it. These host methods are not JavaScript access to application internals.

Inspector metrics (implemented, experimental V1)

Both single-table and tabbed responses may add a top-level metrics array. Omit it or use [] for none; null is invalid. Metrics-only responses are not supported: retain a table (which may be empty) or tabs.

return {tabs,metrics:[{id:'tables',label:'Tables (total)',value:'52'}]};

• At most four metrics, with unique IDs using command ID syntax, nonblank labels <=80 UTF-8 bytes and canonical signed Int64 decimal strings. Examples: "0", "-5", "9223372036854775807". Numeric JSON values, leading zeros/plus signs, -0, decimals, exponents, NaN and overflow are rejected. No Double conversion or numeric formatting is used to display values. Fractional/percentage/text metrics are not implemented.
• Metrics share the full result's 256-KiB encoded limit; they do not create an extra payload allowance. Malformed metrics reject the entire result before rendering. Existing table/tab responses without metrics retain their behavior. The host's legacy single-table inspect method returns only the table; inspectPage exposes metrics.
• Petti renders labeled, selectable exact values above the results, with native accessibility labels/values. Long labels use two bounded lines and a help tooltip; full metric labels remain available to accessibility. Metrics do not contain custom formatting, colors, actions, executable views or HTML.
• Metrics appear only after explicit execution and clear with all other result data on rerun/cancel/disable/close. Switching tabs does not query or change metric values.
• Schema Overview now issues one metadata-only grouped COUNT on sqlite_schema and returns exact totals for non-internal tables/views/indexes/triggers, including zero for missing kinds. Labels explicitly say “total”; the tables still show at most 50 objects per tab with their own truncation flags. It never COUNTs or scans user-table rows. Counts are exact at the count query's read snapshot; subsequent detail queries can observe external schema changes. A truncated count response is an error, never silently presented as a total.

Verification covers exact Int64 extrema through the helper and JSON roundtrip, invalid types/formats/limits, shared payload bounds, empty schema zeroes, totals beyond the tab limit, read permission denial, source preservation, lifecycle and native light/dark bounded rendering.

Inspector bar charts (implemented, experimental V1)

A single-table or tabbed response may add one top-level chart. Omit chart when absent; null is invalid. Existing table/tab/metric responses retain their behavior. Charts-only responses are not supported.

return {tabs,metrics,chart:{
  type:'bar',title:'Schema object totals',
  points:[{id:'tables',label:'Tables',value:'52'}, {id:'views',label:'Views',value:'0'}]
}};

• One categorical bar series, zero to 12 points. Each point has a unique command-syntax id, a unique nonblank label <=80 UTF-8 bytes, and a canonical nonnegative Int64 decimal string. Chart title must be nonblank and <=160 UTF-8 bytes. Numeric JSON, negatives, fractions/exponents, nonfinite values, leading zeros and overflow are rejected. Unsupported types, duplicate IDs/labels and malformed data fail the whole result before rendering.
• Chart data shares the full 256-KiB encoded result limit with metrics/tables. It adds at most 12 exact values, not a new unbounded result set. Empty categories show “No categories to display”; an all-zero series has a zero-state label and a stable zero-based axis.
• Petti adds a native Chart result tab, using Swift Charts with no third-party library or web view. Chart/Values switching runs no query or helper. Bar geometry/axis ticks use approximate Double values, explicitly labeled as approximate. Bar accessibility values and the selectable native Values table preserve the exact integer strings, including Int64.max. The categorical axis starts at zero; long axis labels are bounded. The ordinary results tab stays selected initially.
• Chart state is discarded with the result on rerun/cancel/disable/close. No plugins control colors, executable formatters, layouts or callbacks. No stacked/time-series/multiple-series/floating-point chart support is implied.
• Schema Overview reuses the exact schema count query already used for metrics; charts add no queries and never scan/count user-table rows. Counts retain the previously documented live-snapshot limitation. The old internal Swift inspect convenience method returns only the single table; inspectPage exposes the full response.

Verification covers malformed/oversized charts, aggregate byte caps, exact maximum integer transport/roundtrip, real counts beyond truncated tab rows, empty/all-zero states, native light/dark rendering at 12 categories, Chart tab switching and the actual native Values selector/table.

Inspector form sections (implemented, experimental V1)

Registration can add sections:[{id,title,description?,fields:[fieldID]}]. Omit sections (or null) to retain the original flat form. Field definitions and submitted values stay unchanged.

sections:[
  {id:'criteria',title:'Object criteria',description:'Match object names and types.',fields:['name','kind']},
  {id:'options',title:'Result options',fields:['limit','internal']}
]

One to four nonempty sections are allowed. IDs must be unique and use command-ID syntax; titles are nonblank and <=160 UTF-8 bytes; optional descriptions <=512 bytes. Every declared field must be referenced exactly once across sections; unknown, repeated or missing references reject registration atomically. Sections share the existing 16-KiB page limit. They are ordered inert layout metadata, not nested executable views or additional fields.

Petti uses native form sections with accessible headings and help text inside the bounded scrolling form. Field order follows section/reference order. The same field renderer/bindings serve both flat and grouped pages; changes never auto-run queries. Existing number drafts, UTC dates, multi-select ordering, lock/permissions and cancellation rules are unchanged. Schema Inspector groups existing criteria and options through this public metadata; no new queries or capabilities are added.

Verification covers invalid section counts/IDs/labels/help/references, reordered fields, old definitions, real helper registration/submission, native text editing and explicit execution in both appearances, and existing result/lifecycle regressions.

Inspector-backed workspaces (implemented, experimental V1)

A workspace is an explicit optional collection of existing inspector pages and registered job actions. It does not own/adopt a database or create metadata. Registration uses the same public JavaScript API as third-party definitions (user execution requires the isolated helper and consent).

petti.registerWorkspace({
  id:'orders',title:'Order Inspector',description:'Inspect order metadata.',
  match:{tables:['orders']},
  pages:[{id:'overview',title:'Overview',inspector:'schema-overview'}]
});

• Requires schema.read permission. At most four workspaces/package; unique command-syntax IDs, nonblank title <=160 UTF-8 bytes, description <=1,024 bytes, total definition <=8 KiB. One to eight pages have unique IDs, nonblank titles <=80 bytes, and unique references to registered inspectors in the same package. Unknown/duplicate pages fail package registration atomically. Registration order within source does not matter because references are validated after all declarations.
• Matching is declarative only: match.tables lists zero to eight unique nonempty table names <=512 UTF-8 bytes, without NUL. Every named main-schema table must exist with exact case-sensitive name equality. Views do not satisfy the rule. Empty tables explicitly means any valid SQLite database, not implicit app adoption. No custom SQL/function/dynamic code runs for matching.
• Matching uses host-generated parameterized metadata queries on existing read-only worker connections, lifetime/path checks and cancellation/time limits. No table contents, COUNT/ANALYZE or schema mutation. At most 16 candidate workspaces can be checked per request; excess produces an explicit error. Each match checks a three-second budget between required-table queries; each query also retains its existing 1.5-second SQLite deadline. Schema matching is advisory: concurrent external schema changes can occur afterwards.
• Tools → Command Palette → Workspaces… explicitly matches enabled packages against this window's database. No workspace discovery/matching is added to normal database open. Users choose Open Workspace; the first page appears without execution. Page changes clear prior output and do not automatically query. Run rechecks enablement, schema match, session identity and permissions before invoking the registered inspector. Inspector context stays read-only even if the package has write permission.
• The optional native sheet has a page selector and an always-available native View Raw Database button (also Escape). It closes the workspace/palette and exposes the original grid without changing its selection, rows, paging, filters or access mode. Plugin changes clear matches/pages/results; window close/database replacement follows existing palette cleanup. There are no arbitrary plugin-native views or raw SQLite handles.
• Database Tools registers Database Explorer with match.tables:[] and two real pages, Schema Overview and Schema Inspector. This intentionally matches all opened SQLite databases. It uses only this public API. Package source changes require renewed approval as usual.
• Limits: read-only inspector-backed pages only; no direct editable inspector tables, persistence or automatic app metadata/migrations/template execution; explicit record forms are documented below. Optional registered jobs are documented below. Required-column/type/relationship matching is not implemented. Inspector-backed composed layouts are implemented below. General standalone page lifecycles remain incomplete.

Verification: real reference matching/execution without source mutations, required-table match/mismatch and stale-schema rejection, malformed registration, schema permission denial, disabled/closed sessions, explicit entry/page execution, cancellation on page change, native light/dark layout, native raw button/accessibility/Escape and preserved raw grid state.

Experimental app creation — implemented, new files only (upgrades below)

petti.registerApp(definition) registers inert metadata. Requires approved database.write; it does not execute DDL during registration, discovery, matching or database opening. The host's File → New Database… window lists enabled app definitions, shows the tables/version, requires an editing license and an explicit destination. Enabling a package alone never creates a file. Notes App is the bundled public-API reference; enable it explicitly.

petti.registerApp({
  id:'notes', title:'Notes', description:'A local notes database.',
  migrations:[{version:1,tables:[{name:'notes',columns:[
    {name:'id',type:'INTEGER',primaryKey:true},
    {name:'title',type:'TEXT',required:true},
    {name:'body',type:'TEXT'}
  ]}]}]
});

Implemented contract:

• Up to four definitions/package. IDs use command ID syntax; title is nonblank and <=160 UTF-8 bytes, description <=1,024. Each encoded definition <=32 KiB. Versions must be exactly 1…N (1–16 migrations), each containing 1–8 combined table creations/schema operations, at most 32 table creations total and 1–32 columns/table.
• Table/column names match [a-zA-Z][a-zA-Z0-9_]{0,63}, excluding sqlite_ names. Leading underscore forbids Petti metadata names. Column names are case-insensitively unique; types are exactly INTEGER, REAL, TEXT or BLOB. Optional required and primaryKey are booleans; at most one primary key/table. Repeated object creation is rejected during validation.
• Only create-table definitions are supported. No arbitrary SQL, JavaScript migration functions, raw SQLite handles, defaults, foreign keys, index creation, alterations, sample rows or configuration callbacks. Existing command/write APIs retain their independent restrictions.
• The host creates a private mode-0600 staging file beside the chosen destination. All generated DDL and _petti_app ownership / _petti_migrations history commit in one transaction off the UI thread. Ownership is plugin ID + app ID + metadata format; history stores ordered versions, SHA-256 fingerprints of canonical migration definitions and UTC timestamps. Internal migration checks reject foreign ownership, changed history and newer versions; identical history is a no-op. This is compatibility checking, not tamper-proof authentication.
• Live license/write-policy epoch, cancellation and plugin revocation are checked before/during migration and at SQLite commit; migration execution has a three-second budget. A separate explicit new-file write grant never unlocks any existing database. Publication checks cancellation/authorization again. SQLite closes before the flushed file is atomically renamed without replacement. Existing destinations (including links/directories) and SQLite WAL/SHM/journal companions are refused. Ordinary failures/cancellation remove staging artifacts; force termination can leave a hidden .petti-app-* staging file.
• Publication is the success boundary: later cancellation or plugin disable does not delete a successfully created file. The app opens the new database through normal opening, read-only. Workspace matching remains explicit and read-only; a workspace does not acquire ownership just by matching its table names.

Notes App creates notes, note_labels and note_links across four versions and registers a schema inspector/workspace using existing public read APIs. The normal grid remains available for editing; the optional Records menu now provides reviewed typed CRUD. The Notes workspace also provides the bounded listing/cleanup job flow documented below. This is a platform reference, not a finished notes product.

Planned, not exposed: broader schema matching/conversion, arbitrary SQL/data-transform migrations, remote template dependencies and persistent/streaming jobs. Bounded new-file templates/sample data and read-only jobs are documented below. No ordinary database gains _petti_* tables merely by opening it. User execution requires the isolated helper and explicit consent.

Verification: public reference creation, permission and duplicate-registration rejection, ordered/idempotent/appended migrations, wrong owner/newer/tampered history, real rollback, ordinary/RO-file rejection, stale policy/revoked lifetime, cancellation, existing destination/sidecar/symlink protection, staging cleanup and native license/create/read-only-open/lifecycle/light-dark layout tests.

Experimental owned-app upgrades — implemented

The same immutable registerApp migration list now supports upgrading an already owned database. Append contiguous versions; do not edit previously applied definitions. Notes App v3 adds note_links without changing v1/v2. Package content changes require renewed approval. There is no new JavaScript SQLite/DDL capability or automatic upgrade callback.

Host UI: Tools → Command Palette → App Database… → choose the enabled owning app → Review → Create Snapshot and Upgrade… → native confirmation. Review is read-only and shows current/target versions and pending table creation and exact generated schema-operation SQL. Up-to-date is a no-op. Wrong owner, ordinary databases, missing/changed/future history, altered metadata tables and extra metadata triggers/indexes are rejected. Review never adopts a database. Metadata validation is deliberately strict; manually recreated/rewritten metadata may be incompatible.

Execution:

• Requires explicit confirmation, approved/enabled owner, unchanged app definition, session identity, live editing license and unlocked session policy. Final-component symbolic links are rejected for upgrades; open the actual database file. Plan schema version/history are rechecked under BEGIN IMMEDIATE; stale review fails. This is separate from creating a new file, which uses its own new-file grant.
• Reserves the SQLite writer for the entire backup/migration interval. Other connections may read, but writes can return busy until completion. The confirmation warns about this. An existing long-lived reader may prevent commit in rollback-journal mode; errors roll back the migration.
• Reuses SnapshotService's SQLite backup API through a separate read-only connection. The writer reservation prevents other commits between snapshot capture and migration. Captures the latest committed data, including WAL. Existing snapshot disk-space limits, cancellation, real page progress and five-minute capture deadline apply. Cancellation, license/session/plugin revocation are also checked each backup step. No direct main-file copying of active sources.
• A completed recovery snapshot is leased before migrations. Missing/failed snapshot stops the upgrade. Snapshot capture occurs before any DDL; the existing source is never swapped for a copy. Migrations/history commit together with the existing three-second migration budget, progress/commit access checks and source identity/VFS-moved checks. Failure rolls back pending DDL/history; an already completed snapshot remains available in Snapshots.
• Snapshot publication can precede an error/cancellation. The UI discloses retained snapshots on failure; successful results expose Show Recovery Snapshot in Finder. Snapshot leases protect the recovery file while the result is shown. Restoration is a separate explicit workflow: do not overwrite open databases; this action does not automatically restore or delete snapshots.
• Accepted SQLite COMMIT is the success boundary. Later cancellation cannot undo it. Closing the palette after an attempted upgrade clears stale Undo and refreshes the existing schema/grid. Normal edit policy is preserved; file replacement follows the existing session-revocation/reopen path.

Bounds/limits: the implemented validated schema DSL below, not arbitrary SQL/data transforms; no generic schema adoption. Metadata history verifies compatibility, not authenticity against a user deliberately forging a database. This is not protection against adversarial same-user filesystem rename races. Upgrades are user-triggered, can hold writer access for snapshot duration, and never run on the UI thread. Ordinary open/matching/enabling remains mutation-free.

Verification covers v2→v3 on WAL and DELETE journaling, committed data after review, competing writer exclusion, snapshot reopening/restoration to a separate file, no-op without another snapshot, DDL rollback, snapshot failure, stale schema, malformed history/metadata, lock/license/approval denial, cancellation/relock/session revocation, plugin disable/source replacement during capture, and native review/result/error/lifecycle/light-dark rendering.

Experimental exact-schema adoption — implemented

Adoption is a separate explicit action in Command Palette → App Database… → Review Adoption → As schema vN. The user selects the enabled app and a declared schema version. It does not infer an app/version, automatically adopt matching workspaces, run pending migrations, or reinterpret arbitrary databases.

Review is genuinely read-only. The host builds the expected schema from the registered ordered schema migrations through the selected version and compares SQLite's stored sqlite_schema.sql with the exact canonical SQL generated by Petti's existing schema writer. Table names alone are insufficient. The table set must match exactly. Extra/missing/modified tables, views, undeclared indexes, triggers, SQLite analysis/statistics objects, existing/partial/foreign _petti_* metadata and duplicate migration table names are rejected. Implicit primary-key indexes with NULL SQL belonging to matched tables are allowed. Up to 90 declared table/index objects and 129 schema entries are inspected; the existing inspection deadline applies. No table rows are scanned or counted.

Intentional limitation: SQL with equivalent semantics but different quoting/formatting/declarations may fail matching. This first implementation requires exact canonical definitions. It does not claim general schema equivalence or provide a mapping/conversion wizard. No existing user schema is normalized or rewritten to make it match.

A successful review names the app/plugin, selected version and matched tables. Native confirmation states that _petti_app and _petti_migrations will be added, existing rows/tables remain intact, and other writers may pause for snapshot capture. Enabling the plugin or reviewing the file does not change ownership.

Execution uses the existing host-only app operation route (the reviewed plan carries adoption intent). All upgrade safeguards apply: explicit consent, live license/unlock epoch, enabled/current owner definition, source identity/regular-file checks, cancellation/revocation, schema-version recheck under BEGIN IMMEDIATE, writer-reserved SQLite backup, recovery lease, transactional metadata and commit guards. Compatibility is checked again under the writer reservation and immediately before metadata creation. Only ownership plus fingerprints/history for the selected migration prefix are inserted; no declared app table is created or modified and no later migration runs. A subsequent upgrade requires another review/confirmation and snapshot.

Failure rolls back both metadata tables and history. Completed snapshots remain available even after cancellation/failure; success can reveal the recovery snapshot in Finder. The pre-adoption snapshot contains the original ordinary database without Petti metadata. Closing the palette refreshes schema/grid and clears stale Undo after an attempt. Existing database viewing/editing and View Raw Database remain available.

Verification: metadata-free read-only review, exact schema/version and extra-object rejection, no table-content changes, WAL/DELETE snapshots, adoption→separate upgrade, existing ownership denial, lock/license/consent/stale review, snapshot failure, forced metadata-insert rollback, relock/cancellation/plugin disable/source replacement during capture, and native review/adoption/recovery/upgrade flow in both appearances. The native flow remains optional. Typed template configuration and local dependency resolution are implemented below; implemented templates/jobs and broader migration operations are documented below.

Experimental new-file templates — implemented

petti.registerTemplate({
  id:'notes-starter', title:'Notes Starter', description:'An optional example note.',
  app:'notes', workspace:'notes',
  sampleData:[{table:'notes',columns:['title','body'],rows:[[
    {type:'text',value:'Welcome'}, {type:'text',value:'Edit or delete this example.'}
  ]]}]
});

By default app references a registered app in the same approved/enabled package (the optional external-owner extension is documented below); optional workspace must reference that package's registered workspace and its required tables must exist in the app's declared schema. References are checked after all registration, so declaration order does not matter. Missing/incompatible references fail package loading atomically. No dependency downloads or automatic permission approval; external-owner resolution below does not run a dependency callback.

Limits: four templates/package; unique command-syntax IDs; nonblank title <=160 UTF-8 bytes, description <=1,024, definition <=64 KiB. Optional sampleData defaults to [] in the JavaScript bridge. At most eight insert groups, 100 total rows and 64 KiB encoded seed payload. Each group has an exact declared table name, 1–32 unique declared column names, nonempty rows of matching width. Values use the existing tagged SQLite encoding: integer as Int64 decimal text, finite real text, UTF-8 text, base64 blob, null without a payload. Invalid types, unsupported targets, wrong widths and excess budgets fail validation. Transport preserves Int64/BLOB values; ordinary SQLite column affinity and constraints still apply. Shared helper/package output limits also apply.

File → New Database… offers:

• Blank SQLite Database…: no plugin needed; creates a valid SQLite file/header with an empty schema and no _petti_* metadata.
• Templates: enabled registrations, their app/plugin dependency and optional workspace. Include sample data is off by default, displays the exact sample-row count and resets when the window closes/reloads or plugin enablement changes. File creation freezes the choice; sample rows are never inserted implicitly.
• Empty App Databases: the existing direct schema/history-only creation path remains available.

All three require an editing license and an explicit new destination; existing files/SQLite sidecars/symlinks are never replaced. Publication remains private staging → complete transaction → close/flush → no-replace rename. Failed/cancelled/revoked template work is not published. For templates, schema, ownership/history and optional parameter-bound inserts commit in one transaction, under the existing migration deadline and per-row policy/commit checks. A seed constraint failure rolls everything back, including schema/history. Seeds cannot target Petti metadata or existing files and are unavailable during upgrade/adoption. There is no raw SQL or JavaScript seed callback.

The new file opens through the normal read-only browser. A referenced workspace remains available through Tools → Command Palette → Workspaces…; it does not replace/trap the raw database UI. No extra template metadata is injected. Notes Starter demonstrates the same public API with an optional note and label. This is a data template, not a finished notes app.

Limits: remote dependency acquisition and arbitrary configuration callbacks, arbitrary seed transformations, auto-entering a workspace and richer template lifecycle are not implemented. No automatic snapshots are needed for new-only files; no source is modified. Existing new-file cancellation/publication and force-termination staging limitations still apply.

Verification: reference with/without samples; exact Int64/text/real/NULL/BLOB values; missing app/workspace and duplicate registration; seed target/shape/budget/type rejection; seed constraint rollback and revocation; cancellation cleanup; valid blank SQLite header/empty schema/no metadata; no overwrite and consent/license/disable gates; native blank/empty/template creation, read-only reopen and sample-choice reset in the normal new-file flow.

Read-only jobs — implemented, experimental

petti.registerJob({id, title, async run(context, fields) { ... }}) registers an explicitly run read-only job. Maximum eight per package; IDs/titles follow command rules, and a package must request database.read or schema.read. Supported keys are id, title, run, optional fields, mode (defaults to read) and snapshotBeforeRun (defaults to false for read jobs). Read jobs cannot request snapshots or return mutations. Write jobs use the separate reviewed protocol below; unsupported flags fail registration. Registration never runs the job. Tools → Command Palette → Jobs offers native Run/Cancel, actual counts, structured logs, result/error/status and Done. The panel must remain open. The host Automation inbox below can queue explicitly enabled rules, but running executions are not persisted or replayed. Snapshot-backed writes are recorded in Plugin Edit History; read-job output remains session-only. There is no scheduler.

petti.registerJob({
  id: 'inspect-sample', title: 'Inspect a bounded sample',
  async run(context) {
    const sample = await context.database.query('SELECT name FROM sqlite_schema LIMIT 20');
    const total = sample.rows.length;
    let characters = 0;
    for (let i = 0; i < total; i++) {
      characters += (sample.rows[i][0].value || '').length;
      context.progress(i + 1, total);
    }
    context.log('info', 'Sample inspected without writing.');
    return {title:'Schema sample', text:`${total} names sampled`,
      metadata:{nameCharacters:String(characters), scope:'bounded sample'}};
  }
});

The frozen job context exposes database.query(sql, typedParameters = []), database.schema(), database.tableSchema(name, section), optional database.changes/onChange with database.events, progress(completed,total) and log(level,message). Database methods retain the existing read/schema permissions, eight calls/run, per-query deadlines, 200-row/64-column/byte limits and genuine read-only connections. No selection, file, clipboard, transaction or arbitrary app internals are provided. Even a package with database.write running against an unlocked file receives only reads in this API. Separate queries do not share a transactional snapshot; live commits may differ between reads.

Progress counts must be integers: total 1…1,000,000,000, fixed throughout a run, and completed 0…total, nondecreasing. Omit progress for zero work; completion state is independent and never fabricates 100%. Logs use info, warning, or error plus a nonempty message of at most 1,024 UTF-8 bytes. The host allows at most 128 events including at most 64 logs; each serialized event is at most 4 KiB. Event delivery waits for host validation/acknowledgement, preventing an unbounded producer queue. Invalid events terminate the invocation. Logging an error does not itself fail the job: throw to fail it.

Return {title, text, metadata?}. Title is nonblank, at most 640 UTF-8 bytes; text at most 64 KiB. Metadata defaults to {} and supports at most 16 string pairs, keys 1…80 bytes, values up to 512 bytes, at most 4 KiB encoded total. Native UI displays it as text, not executable UI or paths. No automatic clipboard or file output.

Job budget is separate from commands: 30 seconds wall time, helper CPU soft/hard limits 15/16 seconds. Ordinary command limits remain unchanged. Cancel kills the helper and cancels active database work; no cooperative JS cancellation polling is required. Package disable/discovery, session close/replacement, or closing/reopening the job/palette invalidates work. The host checks session identity while computation runs and before accepting the result, with bounded polling. Late results do not repopulate a closed panel. Failure can leave genuine earlier progress/logs visible; Run Again starts a fresh run.

Database Tools' Sample table storage types uses only this API: bounded schema, up to six ordinary tables and 100 rows per table, tagged storage-type counts and genuine per-table progress. Output states its sample scope and live-read limitation. Existing approvals are digest-bound, so the changed bundled package requires consent again.

Read-only job limitations: no direct write/transaction bridge, background persistence or unrestricted third-party execution. Optional workspace job buttons are documented below. Reviewed write jobs are separately documented below. The fixed JavaScript arena and separate process watchdog apply to jobs as well. Do not market this as the complete app computation platform.

Reviewed write jobs — implemented, experimental

Register petti.registerJob({id, title, mode:'write', snapshotBeforeRun:true, async run(context) {...}}). The package must request database.write and at least one approved read/schema permission. The helper still receives only reads, progress and logs; it never receives a writable connection or transaction capability. Computation produces a bounded inert DML plan or owned-App SELECT materialization descriptor; it cannot directly save changes. Existing read job defaults are unchanged.

For ordinary DML, return {title,text,metadata?} plus statements, using the existing transaction statement shape. The separate materialization shape below replaces statements, never combines with it:

return {
  title: 'Review title change', text: 'One note title would change.',
  statements: [{
    sql: 'UPDATE notes SET title=? WHERE id=? AND title=?',
    parameters: [
      {type:'text',value:'Updated title'},
      {type:'integer',value:'42'},
      {type:'text',value:'Original title'}
    ],
    expectedChanges: 1
  }]
};

Limits: zero to 20 statements, at most 100 expected changed rows in total, at most 64 KiB encoded plan, SQL up to 32 KiB per statement and 128 typed parameters. Integer/text/real/blob/null values use the existing exact tagged encoding; NULL must omit its payload. An empty array is a legitimate no-change preview with no save action. Invalid shape/budgets/types fail before any write. Native review displays the actual SQL, parameter types/values and expected changes alongside the plugin's descriptive text. Prepared plans stay in memory and expire when discarded, replaced by a new preview, disabled/rediscovered or closed. They are not persisted or reusable after a save attempt.

Preview Changes → review → Snapshot and Save… → native confirmation → save is the only write-job UI flow. Preview can run while locked. Saving requires an editing license, actual unlocked write policy, an enabled approved package, a current session and explicit native confirmation. The native host saves only its immutable reviewed plan ID, not newly supplied helper SQL. Neither enabling a plugin, opening a database nor previewing a plan writes to the database or adds _petti_* metadata.

Petti retains a read-only connection's PRAGMA data_version from before computation until review is resolved. It compares that same connection before publishing the plan and again after acquiring BEGIN IMMEDIATE for saving. External SQLite commits, including changes made through Petti's other connections, invalidate the plan even if row counts are unchanged. Source identity/path checks reject replacement or symbolic-link source files. This deliberately favors a fresh preview over applying stale computations; it is not an adversarial filesystem tamper detector.

The writer reservation spans the complete SQLite backup and DML transaction. Other writers may pause; snapshot time/space scales with database size. SnapshotService's existing cancellation/space/deadline protection applies, with real copied-page progress. The snapshot is taken after computation/review, immediately before mutation with other writers excluded. snapshotBeforeRun:true therefore means before saving the prepared plan, not before the read-only computation. Disabling snapshots for write jobs is not supported in this first version. Snapshot failure prevents mutation; completed recovery snapshots remain in the normal history even if later validation or execution fails.

The existing authorizer/transaction engine enforces ordinary-table INSERT/UPDATE/DELETE only, no DDL/PRAGMA/ATTACH/RETURNING/functions/triggers/virtual or shadow tables/SQLite or Petti metadata/REPLACE. Per-statement affected rows must equal the reviewed expectation, and total changes including cascades remain capped. The mutation phase retains the existing approximately 1.5-second preparation/execution budget; the 30-second helper computation budget does not make SQL writes unbounded. Relock/license loss, cancellation, plugin disable and session revocation are checked before/during backup, during SQL work and at the SQLite commit hook. Source identity/path is rechecked before and after backup, during SQL work and at commit. A later statement failure rolls back earlier changes in the same plan.

COMMIT is the success boundary: the host returns actual changed-row count and a recovery snapshot lease with no further helper callback or cancellation rejection after an accepted commit. Cancel during saving requests rollback but cannot undo a commit already accepted. Closing the panel discards visible state; closing the palette refreshes the raw table and clears stale cell Undo after any attempted write. Jobs do not add individual changes to cell Undo. Recovery opens/reveals a separate snapshot; Petti never silently restores over the source.

Notes App's Trim note title whitespace (up to 20) is the public reference: reads the first 20 integer-ID/text-title notes, computes trimmed titles in JavaScript, reports genuine progress, then returns parameterized updates with old-title predicates. Users review and save explicitly. It works on a compatible ordinary notes table without adopting it or creating app metadata. It is a bounded maintenance action, not a finished notes application.

Owned-App large SELECT results are supported by materialization below; custom JavaScript streaming transforms remain planned. Also unavailable: directly editable inspector result tables, persistent job queues/resumable execution, scheduling/WASM, custom transaction management. Persistent mutation outcomes are available separately from a job queue. General app/schema migrations remain a separate API.

Workspace job actions — implemented, experimental

A workspace may include jobs, an ordered array of up to eight unique job IDs registered by the same package. Omit it (or use []) for the existing inspector-only workspace. Unknown/duplicate IDs, cross-package references and malformed arrays reject the entire package registration atomically. Registration order does not matter; definitions resolve after all declarations. Job references share the workspace's existing 8-KiB metadata budget and grant no additional permissions.

petti.registerWorkspace({
  id:'notes', title:'Notes Database', description:'Inspect and maintain notes.',
  match:{tables:['notes','note_labels']},
  pages:[{id:'notes',title:'Notes',inspector:'notes-list'}],
  jobs:['trim-note-titles','edit-note-title'] // A job registered in this package.
});

The workspace shows a small native Jobs menu only when it has actions. Choosing one opens the existing job panel in its ready state; it does not execute the job. Read-only jobs require Run, write jobs require Preview Changes followed by the established SQL/parameter review, confirmation, licensed unlock, recovery snapshot and atomic save. No helper receives private native views or a writable SQLite handle. Inspectors remain read-only.

The host rechecks current workspace registration, the same-package job binding, schema match, session identity and enabled permissions when Run/Preview is invoked. For write jobs the match check is included in the retained data-version review interval, so later commits/schema changes invalidate the plan. The host-only runJob/prepareWriteJob paths carry an optional workspace ID; it is not an arbitrary plugin privilege. Global palette jobs retain their existing independent behavior.

Closing the nested job cancels work and discards uncommitted plans. A write attempt clears stale workspace inspector results when the job panel closes; Load Notes/Run explicitly loads fresh data. It does not add automatic polling/querying. Closing/replacing the workspace or changing plugin configuration closes the nested job as well. Read/write job cancellation, budgets, COMMIT boundary and recovery semantics are unchanged. Reopening a normal palette resets the attempt state, but nested sheet cleanup preserves it until the raw browser has refreshed and cleared stale Undo. No individual job mutation is added to cell Undo.

View Raw Database / Escape remains available in the workspace, including after errors or plugin revocation. The job panel has its own Done/Cancel/Escape to return to the workspace. Returning raw preserves the selected table and current search/filter/sort controls; after an attempted write the existing grid reloads rather than displaying stale rows. The raw browser still opens first for every database/template.

Public bundled examples:

• Notes Starter → Notes Database: optional template sample, explicit first-50-notes inspector (id,title,body, ORDER BY id), schema page, the first-20-title cleanup job, and an exact-ID title edit form with reviewed recovery-backed save. No automatic load, cleanup, adoption or metadata insertion when matching an ordinary compatible database. Creation still uses the explicit App/template API.
• Database Explorer → Sample table storage types: its existing bounded read-only sample job, exposed through the same workspace declaration and job UI.

Verification: invalid/missing/duplicate/foreign references and omitted-field compatibility; same-package read invocation and stale schema/disabled/unbound rejection; native template creation → locked raw open → Notes listing → denied locked save → intentional unlock → reviewed save → recovery → refreshed listing → native raw Escape, preserving selection/search and clearing Undo. Closed reviews and revoked workspaces cannot later commit. Existing job cancellation/replacement and workspace lifecycle tests remain in the regression suite.

Remaining: direct editable workspace tables, arbitrary page composition and persistent page/job state. The bounded Notes reference workflow is documented below. Bounded job forms are implemented below. This bounded integration does not introduce scheduling, pipelines or a new execution engine.

Typed job input forms — implemented, experimental

Both read and reviewed-write jobs accept optional fields, using the same field definitions as inspectors: text, number, checkbox, select, multiSelect and calendar date. Omission/null/empty array preserves input-free jobs. The second callback argument is the submitted, validated field dictionary; existing one-argument callbacks still work.

petti.registerJob({
  id:'lookup', title:'Look up a note',
  fields:[{id:'note-id',type:'text',label:'Note ID (exact integer)',initialValue:'1'}],
  async run(context, fields) {
    const id = fields['note-id'];
    if (!/^-?(0|[1-9][0-9]*)$/.test(id)) throw Error('Enter an integer ID.');
    const result = await context.database.query(
      'SELECT title FROM notes WHERE id=? LIMIT 1', [{type:'integer',value:id}]);
    return {title:'Note', text:result.rows.length ? result.rows[0][0].value : 'Not found'};
  }
});

Up to eight unique declared fields, 16 KiB encoded definitions and 16 KiB submitted values. Existing field limits apply: text/select values up to 1,024 UTF-8 bytes; finite numeric values within JavaScript's exact integer range, optional min/max/integer constraints; actual booleans; strict bounded YYYY-MM-DD dates; up to 32 distinct declared multi-select options. Registration validates defaults; execution rejects missing/extra fields, wrong types, invalid options and exceeded bounds at the host. Numeric drafts are parsed on explicit Run/Preview; an invalid draft never reuses the previous value. Exact SQLite Int64 identifiers should use text plus tagged integer binding, not number fields.

Opening a job only initializes defaults. Run/Preview captures values once. The helper freezes the field object and nested selection arrays; values remain inert data, never code. The native form is disabled while running/saving. No new database permission or writable helper capability is introduced. Fields are not automatically persisted; reopening restores defaults. Job forms are flat and scroll within a bounded area; inspector sections/general recursive layouts are not job APIs.

Editing any field clears old output/errors/progress and synchronously revokes a pending write preview. The next save needs a fresh preview; confirmation is bound to that specific preview ID. Close/replacement also revokes the review. Host-only PluginJobPlan.invalidate() shares the transaction's revocation lease so invalidation is effective before asynchronous draft cleanup. Existing source-revision, lock/license, snapshot, rollback and accepted-COMMIT semantics remain unchanged.

Notes Database → Jobs → Edit a note title proves the public path: exact signed 64-bit ID lookup, nonblank new title, no-op/missing-note results, parameterized old-title-guarded update, explicit SQL/value review and recovery snapshot. The action also appears in global Jobs. It does not auto-select a row, rewrite bodies, insert metadata or save automatically. Native read-only inspection/preview remains possible; saving requires licensed unlock. Refresh the Notes listing explicitly or return to the raw spreadsheet after saving.

Verification: all six field types through the real helper; frozen arrays; malformed registration and typed/default/budget validation; IDs above JavaScript's safe integer range; recovery/no-op/missing notes; revoked/stale previews; native text input and layout in light/dark appearances, numeric drafts, frozen runs, pinned confirmations and close/cancel cleanup. Existing workspace/raw-refresh and inspector tests remain in the regression suite.

Notes reference app workflow — implemented, bounded

The bundled Notes package uses only the public App/template, inspector/workspace and reviewed job APIs. Its optional Jobs menu now includes Create a note and Edit note title and body, retaining title-only editing and whitespace cleanup. No private bridge or new permission is involved. Opening/enabling/matching never creates or modifies notes.

Create requires a nonblank title and explicit body storage: NULL or text (including empty text). SQLite allocates the INTEGER PRIMARY KEY at commit; the preview deliberately reports no future ID. Reload Notes after saving, or use View Raw Database. Creation conservatively accepts only the simple three-column Notes schema (id INTEGER PRIMARY KEY, title TEXT NOT NULL, body TEXT, in that order, ordinary unquoted/double-quoted names). Extra columns/constraints, STRICT/WITHOUT ROWID, different key types, comments and other SQL spellings may reject even otherwise compatible schemas. This gate avoids pretending arbitrary id columns allocate IDs. Use the raw editor for other schemas; this is not a general schema parser or adoption operation.

Edit uses an exact integer ID supplied as text. A body action explicitly chooses Keep existing body, Replace with text, or Set to NULL. Keep does not read or bind the body, so existing large/binary/multiline values are preserved unchanged. Replacement reads the current body within the existing query budget and requires ordinary text or NULL; binary/raw-text/oversized values and truncated query rows fail explicitly and remain editable through the raw browser. Empty text differs from NULL. Entered body text with Keep/NULL is rejected rather than silently ignored. Current form inputs remain single-line and limited to 1,024 UTF-8 bytes each; this is not a rich-text editor. No automatic field prefill or row selection is implied.

Changes produce parameterized plans with old-value predicates (body IS ? handles NULL), exact expected row counts and retained database-version checks. Missing/unchanged notes return no-op results. Saving uses the existing explicit review, licensed unlock, cancellation/revocation, mandatory recovery snapshot and atomic transaction. Completed notes are visible after explicit listing refresh; raw browsing remains the default and full editor. No automatic metadata insertion, deletion, scheduling or new persistence layer was added.

Proof: real template creation with sample → locked raw opening → workspace create preview → locked denial → unlock/snapshot/save → refreshed listing with SQLite-generated exact ID → body/title edit → recovery snapshot of prior NULL → refreshed listing → raw grid. Core tests additionally cover generated IDs above 2^53, NULL versus empty text, keeping a 100-KiB BLOB untouched, no-op/missing notes, stale-body conflict, malformed/oversized input, incompatible creation schema and disabled-plan rejection. Existing general rollback/cancellation/replacement tests remain authoritative for the unchanged engine. This fulfills a bounded reference-app proof, not the full 1.4 LTS release or specialized vertical-app requirements.

Plugin-local storage — implemented, experimental

Declare storage permission and obtain normal digest-bound enablement consent. Commands only receive context.storage; registration, import/export/preview callbacks and the inspector/action/job planning contexts do not gain this capability. No database is needed and this permission never unlocks or modifies an opened database.

const oldValue = await context.storage.get('preference'); // undefined if missing; JSON null stays null
await context.storage.set('preference', {showInternal:false});
await context.storage.remove('preference');

Values must serialize as finite JSON, at most 4 KiB and 16 nesting levels. Undefined/function/symbol/BigInt/nonfinite values are rejected, including nested values. Keys use [a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}. Each plugin has up to 64 keys / 64 KiB encoded total (JSON string escaping counts). A call returns the stored value, or undefined after removal. Read/modify/write across multiple calls is not an atomic transaction; concurrent independent invocations should not treat this as a counter/database API. The reference visit counter is an explicit diagnostic demonstration, not an accounting system.

The host chooses the plugin namespace under Petti's app-support PluginStorage directory next to its approval state. Plugins cannot supply root paths or another ID. Operations serialize, take a cross-process file lock, check bounded regular files, refuse direct directory/file symlinks and hard-linked files, and publish a flushed temporary file by rename. Lock waits are bounded to one second. Existing corrupt/oversized/unreadable files produce errors without overwrite. Missing values differ from stored null. Arbitrary ancestor-directory replacement by another same-user process is not a hardened adversarial boundary.

Calls share the existing eight-call IPC budget and command deadline. Disable/discovery/cancellation prevents queued/unpublished work; a final cancellation check precedes atomic rename. A published preference remains saved if later JavaScript/transport/cancellation fails. Command errors disclose prior publication so users can read the saved value before retrying. No automatic rollback, silent recovery, database metadata, secret logging or filesystem grant is added. This is preferences storage, not a credential vault. User execution requires the signed isolated helper and explicit consent.

Database Tools demonstrates save/read/reset with Remember a tools visit, Read saved tools visits, and Reset saved tools visits. Nothing runs automatically. Re-enabling the changed bundled package requires renewed approval.

Structured command logs — implemented

Commands receive context.log(level, message); jobs retain their existing context.log behavior. Levels are info, warning, error. Each message is nonempty and at most 1,024 UTF-8 bytes; at most 64 log messages per invocation (within the existing total event cap). Invalid levels/types/oversized or excess messages fail execution. Messages stream through an acknowledged bounded channel; callbacks cannot outrun the host.

The palette shows a collapsible Command Log. Actual earlier messages remain visible after a command fails; starting another operation, cancellation or closing clears them. Logs are kept in memory only, not a persistent log file, analytics or automatic DB-content capture. Plugins choose the text and should omit secrets. Late messages cannot repopulate a closed/replaced panel. General inspector/action/preview logging is not exposed yet. Database Tools' storage demonstration emits a real post-save log.

Detailed table metadata — implemented

Where a public context already exposes database, it now includes:

await context.database.tableSchema('orders');               // columns
await context.database.tableSchema('orders', 'foreignKeys');
await context.database.tableSchema('orders', 'indexes');

Requires schema.read, independently of database.read. Returns the existing tagged {columns,rows,truncated} table. Sections mirror SQLite's table_xinfo (including hidden/generated flags), foreign_key_list (one row per key column) and index_list (index summary, not expression/column expansion). Names are main-schema table/view names, at most 512 UTF-8 bytes and no NUL; unknown names/sections fail explicitly. A missing object does not masquerade as an empty schema.

The host generates quoted metadata-only PRAGMAs on genuine read-only connections. Plugins cannot pass PRAGMA text or options; arbitrary PRAGMA/table-valued PRAGMA access through query() remains denied. Existing row/column/cell/byte/deadline limits, closed/replaced session checks and revocation apply. Each call consumes one bridge call. Separate sections can observe different committed schema revisions, not a cross-call snapshot. No table-row scans, COUNT or writes occur.

Database Tools' Inspect columns, keys and indexes table action uses this public API, showing up to the first 20 metadata rows per section and bounded field excerpts. Large metadata reports truncation/errors instead of materializing the full schema. This metadata method does not itself subscribe to changes or edit schema. The separate changes/onChange and owned-App migration APIs are documented below.

Composed native pages — implemented, experimental (2026-09-30)

Inspectors and workspace pages may add a layout value to registration and return {page: node} from run. Legacy table/tabs/metrics/chart outputs still work. layout and legacy sections cannot be combined. No JavaScript rendering, native view reference or raw database handle crosses this boundary. The host provides the normal Run/Cancel/Done controls even if the layout has no buttons. Nothing executes merely by opening the page.

A node has unique id, type, optional title and the following type-specific properties:

field, button, and results belong only in registered layouts; returned result pages cannot introduce executable controls or new inputs. Every declared field must be referenced exactly once. Existing eight-field, field-type and validation limits remain. Node IDs are unique per page, at most 80 UTF-8 bytes. A page allows 64 nodes, depth eight, 200 total table rows, and 256 KiB encoded; text at most 8 KiB per node and titles 160 bytes. Container-only children and type-specific payloads are validated before native publication. Transport is additionally preflighted for JSON nesting before recursive decoding. Existing registry/result/runtime limits also apply, including 16-KiB registration metadata, eight bridge calls and inspector runtime deadline.

petti.registerInspector({
  id:'search', title:'Search', description:'Read-only example', actionTitle:'Search',
  fields:[{id:'name',type:'text',label:'Name contains',initialValue:''}],
  layout:{id:'page',type:'page',children:[
    {id:'form',type:'form',children:[{id:'name-input',type:'field',field:'name'}]},
    {id:'progress',type:'progress',title:'Loading'},
    {id:'results',type:'results'}
  ]},
  async run(context, fields) {
    context.progress(0,1);
    const table=await context.database.query(
      'SELECT name FROM sqlite_schema WHERE instr(name,?)>0 LIMIT 100',
      [{type:'text',value:fields.name}]);
    context.progress(1,1);
    return {page:{id:'result',type:'table',table}};
  }
});

Inspector context.progress(completed,total) uses safe integers and the existing acknowledged bounded event protocol: fixed positive total, monotonic completed in range, at most 128 total events. It runs off MainActor. Invalid/regressing progress fails execution, and cancellation/disable/close prevent stale publication. Progress does not grant writes or extend time limits. Inspectors remain read-only; writable workspace CRUD uses the separate reviewed record forms below. Buttons currently invoke/reset the registered inspector, not arbitrary callback graphs or wizard state.

Trees

A cell previewer may return {title,text,tree:[{id,label,value,children?}]}. title and text remain required for compatibility and safe text copying. The host displays the tree with native disclosure/keyboard expansion. Tree components in pages use the same value format. Limits: 500 nodes, depth 32, unique IDs ≤160 bytes, labels ≤512 bytes, values ≤2,048 bytes, encoded tree ≤128 KiB, plus the enclosing output/page budget. This is bounded display data, not a lazy recursive query API. Bundled JSON Tools supplies a 256-node/16-level outline and explicitly labels partial containers; original raw cell bytes stay intact.

Charts

{type,title,points:[{id,x,y,series?}]} supports bar, line, area, pie, donut, scatter. Up to 100 points / eight series, unique IDs ≤80 bytes, x labels ≤80 bytes; y is a finite decimal string with magnitude ≤1e15. Pie/donut values are nonnegative. Scatter x must also be a finite numeric string within ±1e15; other x values are ordered categories supplied by the plugin. Native Swift Charts renders geometry through Double; the Exact values checkbox reveals the original decimal strings in an accessible native table. Labels and VoiceOver values preserve supplied strings. Empty/zero pie data is explicit. No database query executes from a chart descriptor: plugins use the permission-checked read API and supply bounded results. Multiple charts can appear in page stacks/tabs; general unbounded dashboard queries and editable charts are not implied.

Calendar/schedule

{title,events:[{id,title,start,end,detail?}]} supports up to 100 uniquely identified events. IDs ≤80 bytes, titles ≤160, details ≤1,024. Start/end must be valid ISO timestamps with seconds and an explicit Z or numeric timezone; end cannot precede start. The native graphical day picker shows an agenda for the selected UTC day, including overlapping multi-day events, sorted by actual start time. Empty days are explicit; an initial nonempty schedule opens at its earliest event. This is a read-only schedule: drag editing, recurrence rules, conflict resolution and timetable generation are separate features. It does not alter the source schema or supply fabricated events.

Bundled Database Tools uses only these public APIs for Schema Dashboard (filter form, notice, progress, metrics, table and pie) and Appointment Schedule (calendar, source rows and line chart). The latter requires an existing appointments(id,title,starts_at,ends_at) table, reads at most 101 rows and displays at most 100 with truncation notice. Missing/incompatible data produces an error. It never creates a sample table in a user's database. Existing simple table browsing and View Raw Database remain unchanged.

Reviewed table/database write actions — implemented, experimental

Both action registries accept mode: 'read' | 'write' (default read). Read actions preserve their original output and behavior. Write actions require database.write in addition to existing registry permissions. A table action still requires selection.read; database actions require read/schema permission. The callback receives the existing read-only action context. It cannot call transaction/write methods.

petti.registerTableAction({
  id: 'trim-title', title: 'Trim title', mode: 'write',
  async run(context) {
    if (context.table.name !== 'notes') throw new Error('Choose notes.');
    const rows = await context.database.query('SELECT id,title FROM notes LIMIT 1');
    if (rows.truncated || !rows.rows.length) throw new Error('No complete record.');
    const [id, title] = rows.rows[0];
    if (title.type !== 'text') throw new Error('Expected text.');
    return {title:'Review title', text:'Trim the selected table’s first note.',
      statements:[{sql:'UPDATE notes SET title=? WHERE id=? AND title IS ?',
        parameters:[{type:'text',value:title.value.trim()},id,title],expectedChanges:1}]};
  }
});

The returned object uses the write-job result/mutation format (title, text, optional metadata, statements). All existing bounded mutation budgets apply. Explicit Preview Changes computes a plan; it never modifies data. Save requires exact SQL/parameter review, confirmation, licensed unlock, a recovery snapshot and one atomic transaction. Table actions are restricted by the SQLite authorizer to the chosen ordinary table. Database actions use the existing ordinary-table DML whitelist. Neither gains DDL, arbitrary PRAGMAs, handles, filesystem, native views or an independent writer.

Plans retain source identity, generation and the original connection's data_version. Saving captures the current lock/license epoch and enforces it throughout mutation. External writes/stale contexts require a new preview. Cancel/close/disable invalidates the plan; failed expectations or SQL roll back. Notes App's table Review note title cleanup and database Review Notes title cleanup implementations use only these public APIs and examine at most 20 notes.

Writable workspace records — implemented, experimental

A workspace may declare up to four optional forms (within its existing 8-KiB registration budget). This requires database.read, schema.read and database.write. Each target table must appear in match.tables.

forms: [{id:'note-records',title:'Edit Notes',table:'notes',key:'id',fields:[
  {id:'title',type:'text',label:'Title',initialValue:''},
  {id:'body',type:'text',label:'Body',initialValue:''}
]}]

The optional native Records menu loads the first 50 records by indexed INTEGER PRIMARY KEY. Larger sets are explicitly labeled; View Raw Database remains available for all rows. Registration/matching/opening the database never writes or automatically loads these records. Forms support New, select, edit, delete, reload and explicit NULL toggles. Every mutation goes through the reviewed snapshot-backed action/job boundary. No JavaScript save callback or raw SQL is needed: Petti generates quoted parameterized statements and guards updates/deletes with the exact key and original mapped values.

Each form has 1–8 existing typed fields; IDs map to actual column names and must satisfy both field and SQL-identifier validators: a lowercase first letter, then lowercase letters/digits, maximum 64 characters (underscores and hyphens are not accepted by this intersection). The key must be a single ordinary INTEGER PRIMARY KEY rowid alias and cannot be a field. WITHOUT ROWID/virtual/shadow tables and incompatible schemas are rejected. New records let SQLite allocate the key. Existing signed 64-bit keys are retained as tagged integer strings, never converted to JavaScript numbers.

Mapping: text/date/select → declared TEXT; multiSelect → TEXT containing a JSON string array; checkbox → INTEGER 0/1; number → INTEGER when integer:true, otherwise REAL. Existing range/date/options rules apply. Numeric input is finite and bounded to ±(2^53−1); larger data needs Raw Database. BLOBs, arbitrary affinity conversions, composite/text keys and direct editing of inspector result tables are not supported. NULL is distinct from empty text and permitted only for nullable mapped columns. Unmapped columns retain their values/defaults; ordinary SQLite constraints still apply.

A stale loaded form cannot overwrite an external change: source revision is checked before planning and again before saving. Reload resets selection/inputs. Closing, plugin revocation and subsequent previews discard outstanding reviews. Notes Database → Records → Edit Notes provides real create/update/delete against an ordinary matching database without adding Petti metadata.

Broader app schema migrations — implemented, experimental

Each ordered migration retains tables: [] and may add operations: []. There must be 1–8 combined table creations/operations per version. Table creation happens first, then operations in array order. Supported operation objects:

const operationExamples = [
  {kind:'addColumn',table:'notes',column:{name:'color',type:'TEXT',defaultValue:{type:'text',value:'blue'}}},
  {kind:'renameColumn',table:'notes',from:'title',name:'heading'},
  {kind:'dropColumn',table:'notes',name:'color'},
  {kind:'renameTable',table:'notes',name:'entries'},
  {kind:'dropTable',table:'entries'},
  {kind:'createIndex',table:'notes',name:'notes_title_index',columns:['title'],unique:false},
  {kind:'dropIndex',name:'notes_title_index'}
];

Examples are alternatives, not one valid sequence. Identifiers are host-validated/quoted; operations can target only declared app objects. Columns optionally accept bounded typed literal defaultValue (≤4 KiB), never SQL expressions. Types must match; required added columns need a non-NULL default. Adding a primary key, dropping a primary-key/last/indexed column, invalid references/name collisions and unsupported operation shapes are rejected. Drop the declared index before its column. An index contains 1–8 columns. At most 90 active declared tables/indexes are supported, retaining existing per-table/version limits.

Before upgrading an owned app with these operations, Petti verifies the current physical schema exactly matches its declared migration history. Unexpected external tables/indexes/triggers or rewritten definitions fail closed. Expected schema is constructed in a private in-memory SQLite database off the UI thread; no user rows are copied/scanned for matching. Reviewed upgrades reserve the writer, create a recovery snapshot and run all pending DDL/history in one transaction. Failures/cancellation/relock roll back. Operations that require expensive scans may hit the existing migration deadline and safely fail; this is not an unbounded maintenance API.

Destructive operation SQL is visible in the existing confirmation review. Ordinary database opening never adopts, migrates or creates _petti_* metadata. Explicit exact-schema adoption understands the schema at the selected version, including declared indexes/renames. Templates validate seeds against the final schema. Historical migrations without operations/defaultValue retain their prior serialized fingerprints, so existing version history is compatible.

Notes App schema version 4 adds note_labels.color with a literal default and notes_title_index, exercising upgrade/snapshot/restore through the public DSL. Petti's product version is unchanged. Raw SQL migrations, data transforms, arbitrary foreign-key/constraint rebuilding and cross-plugin schema ownership remain unavailable.

Expanded permissions, explicit grants and local installation — implemented, experimental

Commands → Install Local Plugin… reviews a selected .petti-plugin directory's manifest and single entry script before writing anything. The native permission dialog explains requested capabilities, including database modification. Cancel installs nothing. Approved bytes are captured at review, so later source edits cannot replace what was approved. Installation publishes under Application Support/Petti/Plugins/<id>.petti-plugin; it never replaces an installed package or accepts a reserved bundled identifier. The current format installs manifest + entry script only; auxiliary assets/modules are not executable API inputs.

User packages are installed disabled. Installation is not approval to execute. Enabling requires a signed isolated helper and digest-bound permission consent, even for packages requesting no permissions. User packages mimicking a reserved bundled ID cannot execute. No marketplace, downloads, network access, auto-enable or database mutation is introduced. Existing bundled packages still require digest-bound enablement approval, and changed bundled code invalidates prior consent.

Two additional permissions:

• clipboard.read: receive a bounded text snapshot only after the user chooses Share Clipboard for that plugin's next command. No arbitrary pasteboard polling.
• database.events: observe bounded committed-data/schema invalidation hints on the current database during an explicitly running operation. It does not grant row reads, schema reads or writes.

file.readSelected now also permits the native Attach File… command input. The host reads a regular non-symlink file off the UI thread, at most 64 KiB. A grant belongs to one palette/plugin, is consumed on the next run and is cleared by cancellation/close. A host-only permission revision captured at sharing time invalidates it after any plugin configuration change, including changes from another window and disable/re-enable. Stale inputs are rejected before helper execution; reopen Commands and share again. Selecting a different plugin never shares the grant with it. No file picker opens merely because a plugin asks for permission.

// Available only when the user supplied that specific input.
const file = context.files?.readSelected();
// {name, byteCount, base64, text}; text is null for invalid UTF-8.
const clipboard = context.clipboard?.readText();
// A string, including an explicitly shared empty string.

These synchronous getters return frozen snapshots, not paths, handles or a general filesystem API. File names omit parent directories. Binary bytes retain base64 exactly; UTF-8 text is validated against those bytes. Missing grants omit the corresponding context member. Permission and size checks happen in the host before helper execution.

clipboard.write retains explicit Copy Result with a fresh host permission check. file.writeSelected now permits Save Result… after a command produces output. The host saves the exact reviewed result using an opaque publication ID, rechecks permission/generation/session/lease, stages atomically and publishes only to a new destination. It refuses overwrite, symlink destinations, open database/sidecar paths or aliases and managed snapshots. Even commands without database.read retain host-side source protection. Another command/window cannot substitute its output for an older preview; disabling/closing invalidates the appropriate result. Text saves retain the existing 64-KiB output limit and contain the displayed result, including any explicit preview-truncation notice.

Shared Input Tools exercises attached file, clipboard, typed selection, Copy and Save through these same APIs. Input inspection explicitly labels its 12,000-character preview limit; it is not a streaming conversion tool. Existing selected-file importer/exporter APIs are unchanged.

Typed selection context — implemented, experimental

Commands with selection.read additionally receive:

context.selection.table // captured table name or null
context.selection.value // exact tagged value of one complete loaded cell, or null
context.selection.grid  // {columns, rows, truncated}, or null

Integers remain decimal strings, BLOBs base64, and SQL NULL tagged null; they are not coerced to JavaScript numbers/empty strings. Existing .text and .cell APIs remain backward compatible. The editable text .cell identity is still a separate exact identity structure.

Grid capture uses the current Data browser's loaded cells only, in visible column/row order: at most 32 rows, 16 columns, 64 cells and 32 KiB encoded data. Deferred/oversized/nonrepresentable or unloaded rows are skipped and the result is marked truncated; capturing never fetches another page. Empty partial results are explicit. The selection is a captured value snapshot for the invocation and does not follow later UI changes. It is not an unlimited export, a row identity resolver or a live selected-row cursor. Query-result grid selection is not included. Existing schema/tableSchema metadata and command storage/logging APIs remain available under their original permissions/bounds.

Database change API — implemented, experimental

Available in commands, jobs and reviewed write-action planning contexts that hold database.events, with their existing call/deadline/cancellation limits. Ordinary read-only inspector/table/database action contexts retain their original read/schema-only permissions; preview/import/export callbacks have no event access. A fresh retained read-only observer connection is created only on first use, never on ordinary database opening or scrolling. It samples PRAGMA data_version and schema_version, not table rows/counts. No trigger, metadata table or source mutation is installed.

const first = await context.database.changes();
let cursor = first.rows.at(-1)[0].value;
const next = await context.database.onChange(event => {
  // Frozen {cursor, kind, timestamp}; callback runs inside this invocation.
  context.log('info', event.kind); // commands/jobs with existing logging
}, cursor);
cursor = next.rows.at(-1)[0].value;

changes(cursor = null) returns immediately after one sample. onChange(callback, cursor = null) is a one-shot bounded subscription, waiting at most one second for a change (and no longer than the remaining operation deadline). It invokes the callback for each non-idle event in the returned batch, then finishes. Call again explicitly to continue observing while the operation remains active. No callback/job survives closing its panel, cancellation, disable, source replacement or the operation deadline. At most eight bridge calls per invocation remain allowed; there is no hidden persistent watcher or automatic write/refresh.

The result uses the existing tagged table transport with columns cursor, kind, timestamp. Kinds: opened, databaseChanged, schemaChanged, reset, idle. Timestamps indicate observation time, not an exact commit timestamp. The final row always supplies the latest cursor, even on an idle timeout. Cursors are opaque/session-scoped. There are at most 32 retained hints; cursor gaps set truncated and emit reset. A cursor from a reopened session resets safely. Replay can coalesce multiple commits into one invalidation; it does not attribute a process/table/row or count mutations. Rolled-back transactions do not produce committed-change hints. Snapshot creation itself is not a source-database commit event.

Database Tools → Observe database changes (up to 6 seconds) demonstrates real repeated subscriptions, logs and completed watch-interval progress through the public read-only job API. It performs no schema/data analysis or automatic updates. Persistent change history, unattended schedules and reactive background workspaces are separate work; bounded explicit subscriptions are the implemented contract.

Configured templates and installed dependencies — implemented, experimental

Templates may add typed fields, configurationData, requires and appPlugin:

petti.registerTemplate({
  id:'personal-notes', title:'Personal Notes', description:'Your first note.',
  app:'notes', appPlugin:'com.petti.notes-app', workspace:'notes',
  requires:[{id:'com.petti.notes-app', minimumVersion:'1.0.0'}],
  fields:[{id:'title',type:'text',label:'First title',initialValue:'Welcome'}],
  configurationData:[{table:'notes',columns:['title'],fields:['title']}],
  sampleData:[]
});

The provider requires database.write. Native File → New renders the existing typed fields (≤8), validates the submitted values, and generates bound seed inserts into the declared app's final schema. Each configurationData entry inserts one row (≤8 entries); column/field lists correspond positionally and every field must be used. Types must match declared columns: text/date/select/multiSelect→TEXT (multiSelect JSON array), checkbox→INTEGER 0/1, integer number→INTEGER, other number→REAL. Existing finite/exact-number/date/options limits apply. Configuration rows and optional sample data share existing ≤8 seed groups, ≤100 rows and 64-KiB limits. No executable configuration callback or raw SQL crosses the boundary.

Up to eight requires entries identify installed, enabled, trusted, valid packages and minimum numeric major.minor.patch versions. Comparison handles large numeric components without integer overflow. No dependency is fetched or enabled automatically. Missing/disabled/incompatible dependencies produce a visible unavailable-template reason and prevent Create. The user enables the required installed package through the existing permission screen. An external appPlugin must be declared in requires; omitted means the provider's own app. workspace, if present, belongs to that app owner and must match its declared final tables.

The database records the actual schema owner's plugin/app metadata, not the template provider's. Dependencies are rechecked at creation and any plugin configuration change revokes in-flight new-file work. All migrations, configuration rows and selected samples commit in the existing atomic staging/new-only publication flow, with license/cancellation/rollback/no-overwrite checks. Bad fields/constraints leave no partly created destination. Ordinary opened databases are unaffected. Inputs reset on close/reload; creation opens in the normal read-only browser with View Raw Database available.

The bundled Personal Notes Template depends on Notes App, collects title/body and creates a real note without optional sample data. It demonstrates cross-package resolution using the same public API. Remote package resolution/installation, arbitrary schema conversion remain outside this contract. Local dependencies require their own enablement/permissions and isolated-helper eligibility.

Native streaming importer/exporter registrations (implemented, experimental V1)

petti.registerImporter({id:'csv-all',title:'Import CSV (whole file)',nativeFormat:'csv'});
petti.registerExporter({id:'typed-all',title:'Export Typed JSONL (whole table)',
  fileExtension:'jsonl',nativeFormat:'typed-jsonl'});

nativeFormat is either csv or typed-jsonl, on either registry. Omit parse/render; combining a native format and a callback is rejected. IDs, registration counts and permissions are unchanged: import requires file.readSelected + database.write; export requires database.read + file.writeSelected. Bundled JSONL Import/Export register both through this same API. Packages need fresh digest consent after a bundled update.

Petti owns the codec and the entire native transfer. No whole dataset, file path, spool path, raw handle or transfer callback enters JavaScript. This is not an unrestricted streaming JS engine. Existing custom callbacks and their smaller budgets remain unchanged.

Import flow: explicitly choose a regular file → private immutable disk capture → parse/stage all rows in private SQLite → review at most 20 rows/64 KiB plus exact staged total → map source to distinct editable destination columns → confirm → reserve writer, create recovery snapshot and commit every staged row in one transaction. Preview may run while locked; saving requires the existing lowest-layer license/lock/session/plugin checks. Changed destination schema, trigger/virtual/internal-table writes, REPLACE conflict policies, errors or revocation fail closed. Skipped columns retain SQLite defaults. The host records the committed count and recovery snapshot in Plugin Edit History. No implicit schema creation or App adoption occurs.

Export flow: explicitly preview up to 20 rows → native Save panel → export the entire ordinary table in one fresh read transaction. Data may differ from preview at save time; changed schema requires another preview. Grid filter/sort/selection do not apply. UI and button state clearly distinguish whole-table output from custom preview-only output. Export works while locked. Existing source/companion/alias protection, replacement consent, staged fsync and atomic publication apply; cancellation/error preserves the previous destination until publication.

Bounds: 1 GiB input/output, 10 million rows, 64 columns, 64 KiB per decoded cell and 1 MiB per encoded row. Preparation and each transfer have five-minute deadlines; these maxima are ceilings, not completion-time guarantees. Spool size is capped at 1 GiB; input capture temporarily needs additional disk space. Only bounded row previews are retained in memory. At most 16 live staging leases are admitted; closed drafts delete staging, and subsequent preparations remove abandoned unlocked staging from interrupted processes. Active leases are not removed. Cancellation, progress and source checks run off the UI thread; no automatic COUNT is used.

CSV: UTF-8, header required, comma delimiter, quoted multiline fields, all imported fields are TEXT (including empty strings). SQLite destination affinity still applies. Export quotes fields; NULL becomes empty text and BLOB is base64. CSV therefore does not preserve storage types and is not a lossless SQLite round-trip format.

Typed JSONL: first line is {"format":"petti-sqlite-jsonl-1","columns":["id","value"]}; every following line is an array of exact tagged SQL values in that order, e.g. [{"type":"integer","value":"9223372036854775807"},{"type":"null"}]. Supported tags are integer, finite real, UTF-8 text, base64 blob and null (no payload). This preserves the represented SQLite values; destination affinity/constraints still apply. It is distinct from the custom object-per-line JSONL importer. Invalid UTF-8 TEXT and deferred/oversized values fail explicitly; use ordinary SQL export for raw-byte preservation. Empty typed files still require the header; empty tables export a header.

Verification: PluginStreamingTests/UITests test real bundled registration, whole-file/whole-table native flow, immutable source review, exact integer/NULL/BLOB/multiline values, bounded previews, typed round-trip, symlink/sidecar protection, changed schema, atomic replacement, relock/rollback/revocation, temporary cleanup and native UI. PETTI_STREAM_STRESS_ROWS=1000000 swift test --filter PluginStreamingTests.testHundredThousandRowsExactRoundTripAndImmutableReview generates a larger fixture and checks process memory.

Persistent plugin mutation history (implemented, native host UI)

… → Plugin Edit History is a host feature, not a new JavaScript permission or a cross-plugin data API. The journal is under Application Support/Petti/PluginHistory, separate from every user database. It retains the latest 1,000 operations across files, with 50-entry keyset pages. Opening a database or running a read-only command does not create source metadata or a mutation record.

Records identify plugin, host operation label, source path/file identity, start/finish time, commit outcome, known changed-row count and an existing recovery snapshot where available. SQL text/parameters and cell values are not copied into the journal. Plugin-authored operation labels should not contain secrets. Current coverage: command transactions, custom/streaming imports, reviewed jobs/actions/forms, new App/template publication and owned upgrade/adoption. This is not a complete audit of normal spreadsheet edits, SQL console writes or other applications.

The initial durable outcome is unknown. Only accepted SQLite COMMIT / atomic App file publication becomes committed, independently of helper completion. Failed/rolled-back calls are not labeled committed. A process interruption or history-result publication failure may leave unknown; the UI explicitly instructs inspection before retrying. The history database and user database cannot share an atomic commit. If initial history recording fails, the mutation does not start; a result-publication failure after accepted commit is reported as committed/uncertain history, never as rollback. History retention can also evict an unusually long-lived record; that publication failure is surfaced.

Recovery opens the recorded snapshot genuinely read-only and never overwrites the source. Missing/deleted snapshots surface an error. Missing/replaced source identities are flagged; a reused path is not treated as proof that it is the original file. Command/custom-import operations without snapshots explicitly show no Undo/recovery. Reviewed jobs/forms/actions/upgrades and native streaming imports retain their snapshot-before-write policy. History eviction does not delete manually managed recovery snapshots; use Snapshots to remove unwanted copies.

Owned-App bulk results (implemented; API v1 experimental addition)

A registered write job may return materialization instead of statements:

return {
  title: 'Review normalized results',
  text: 'Replace the complete outputs table after review.',
  materialization: {
    app: 'my-app',
    table: 'outputs',
    columns: ['id', 'value'],
    sql: 'SELECT id, upper(value) AS value FROM inputs WHERE id >= ?',
    parameters: [{type: 'integer', value: '1'}]
  }
};

Requires database.read, schema.read, database.write, an App registered by the same plugin, and a database already created or explicitly adopted into that App at its current version. Host checks canonical owned schema/history. Merely matching a workspace never grants ownership. This API cannot adopt a database, change schema, write App metadata, append arbitrary SQL or target another App's tables. Read jobs, commands and table/database actions do not accept this result shape.

The native host executes one authorizer-restricted read-only SELECT against the current database, captures its complete output in private disk staging, and shows the actual destination row count, actual staged count, mapped columns, SQL/bindings and at most 20 preview rows. SELECT column aliases must exactly match columns in order; supplied columns must exist in the ordinary destination table. Other destination columns receive their normal defaults/NULL/rowid allocation. Type affinity and constraints apply at insertion, as in SQLite. A failed constraint rolls back the entire replacement.

Saving never executes the SELECT again. After explicit native confirmation, the host checks the retained data revision, reserves the writer with BEGIN IMMEDIATE, validates ownership again, makes a recovery snapshot, deletes existing destination rows and inserts the staged rows in one transaction. An empty result intentionally clears the table and is explicitly reviewed. All source tables remain unchanged unless the user explicitly selected that same table as the output. Changed-row history counts deleted + inserted rows. Cancellation/relock/license revocation/disable/close before SQLite accepts COMMIT rejects or rolls back the operation; cancellation after accepted COMMIT cannot undo it. A post-commit history-publication error can leave an unknown journal outcome, as documented for existing writes.

Limits: one destination; SQL <=32 KiB; descriptor <=64 KiB; <=128 exact tagged parameters; <=64 columns; <=64 KiB/cell; <=1 MiB encoded row; <=1 GiB encoded output and private SQLite max page count 262144; <=10 million input destination rows and output rows; five-minute staging and insertion deadlines (snapshot uses existing backup bounds). Disk staging previews share the 16-active-preview ceiling with native transfers. SQLite caches are bounded to 2 MiB per handle and temp queries use file storage. Sorting/grouping can still require temporary disk space and explicit scans; this is an opt-in job, never normal-open work. No arbitrary JavaScript bulk loop, raw handle or staging path is exposed.

Allowed SELECT functions match the ordinary read allowlist plus row_number, rank, dense_rank, lag, lead. ATTACH, PRAGMA, extension loading and unknown functions are denied. CTEs are permitted; canonical owned-schema validation rejects added views/triggers before staging and again under the writer reservation. The existing 20-statement/100-row ordinary mutation limit is unchanged. User-installed packages use the same bounds and require isolated-helper eligibility plus explicit consent.

Analytics Workbook reference (implemented, bounded)

Enable com.petti.analytics, then File → New Database → Analytics Workbook. Optional sample data is off by default. A new workbook remains ordinary SQLite and opens in the normal read-only browser. Open the optional Analytics workspace explicitly. Its Start Here page describes the complete workflow; Records edits persisted steps/labels/chart settings. No native-only plugin escape hatch is used.

• Two inputs (raw_data, reference_data) and one saved results table, each with eight generic columns c1…c8 declared BLOB affinity so existing SQLite types remain intact. id is a generated INTEGER PRIMARY KEY. CSV mapping and omitted/default columns use existing native rules; never map source fields to id unless you intentionally supply unique exact IDs.
• CSV and typed JSONL import/export stream whole datasets through the public nativeFormat registrations. A separate JSON-array importer accepts 1–20 flat objects /32 KiB, 1–8 matching keys, text/NULL/bool/safe integers; it rejects duplicate/escaped duplicate keys, fractional/exponent number spellings, oversized integers and nested values before any write. Quote exact decimals/large integers. For a SQLite source, export typed JSONL from its source window and import into the workbook; there is no arbitrary ATTACH bridge. Clipboard data uses the normal spreadsheet paste workflow; no unattended clipboard polling or external file synchronization is implied.
• Up to 16 persisted ordered SELECT steps (each ≤1,024 UTF-8 bytes when edited with Records). Each reads the preceding input and returns c1…c8. SQLite SQL implements filtering, sorting, joins against reference_data, grouping/aggregates, calculated columns, DISTINCT, casts, date expressions and clearing unused output columns with NULL. SQL display labels can be changed separately in column_labels; this deliberately does not rename physical c1…c8 columns. There is no visual node canvas or arbitrary dynamic output schema. Duplicate positions, excessive/incomplete steps, bad columns or non-SELECT operations fail the entire preparation rather than silently truncating it.
• Run Pipeline stages the complete output using the materialization API. Review and snapshot-backed save replace only results; all inputs/steps remain intact. No steps means a complete input copy. A changed input/step invalidates an outstanding review. Saved output is explicitly labeled as potentially out of date until another successful run, not a reactive live view or immutable provenance/audit ledger.
• Saved Results shows up to 50 rows; the raw grid and whole-table export expose the complete saved result. Native bar/line/pie charts show up to the first 100 stored result rows in saved order, with an explicit limit notice, exact-value alternative and explicit COUNT metric. Charts do not silently aggregate or coerce invalid numeric data. Add a grouping step when aggregate totals are intended. Reading a chart can hit normal query deadlines on a very large table; it is never run on ordinary open.
• Type conversion follows SQLite: invalid numeric CAST can produce zero; date() can yield NULL; REAL calculations are approximate. Use integer minor units and explicit input validation for exact monetary calculations. Advanced analytical/business domain correctness is the plugin author's responsibility, not a claim made by the sample sales pipeline.

Scope intentionally excluded: XLSX/Parquet/Arrow, streaming arbitrary JSON arrays, inferred column schemas, visual transform editors, scheduled pipelines, result provenance/run archives and external connectors. These do not masquerade as inactive UI controls. The normal browser/editor remains the default experience.

Native automation — implemented, opt-in

… → Automations composes existing public registerJob jobs; there is no new JavaScript registration, event emitter, permission, filesystem grant or background write capability. Database Tools and Analytics use the same public job API. Example: enable Analytics and Database Tools, create a rule for File imported matching raw_data, add Run Pipeline then Sample Storage, and enable it for the current database. Importing CSV queues the rule. Choose Run Pending Chain, inspect Pipeline's complete materialization, confirm Snapshot and Save, and the read-only sampler runs only after the save succeeds.

Rules bind to the canonical file path plus device/inode/creation identity and each job's approved package digest. Preferences live in Application Support/Petti/Automation, never in the source database. Each file has at most 16 rules, each with 1–8 ordered registered jobs; one rule is at most 32 KiB and the whole file at most 512 KiB. Invalid, oversized, linked or duplicate preferences are rejected. Replaced/renamed files do not inherit another file's rules. Rule preferences persist; pending/running executions and step results do not. Opening an ordinary file reads only bounded host preferences and does not execute jobs, adopt an App, inspect large tables or write database metadata.

Initial triggers:

• Manual Run, available for every enabled rule.
• Database opened, after successful session preparation. A saved rule queues a new request; it does not replay an interrupted run.
• Database files changed, using the existing once-per-second coalesced main/WAL/SHM monitor. It cannot attribute changes to another process or infer row insertions. Events during a running chain are suppressed; a delayed change from Petti's own writes may still queue a request, but cannot start work.
• File imported, only after successful native CSV or plugin import completion. The optional condition is an exact destination table name. No input file contents/paths are passed to jobs through the trigger.
• Row inserted in Petti, only after confirmed browser New Row or public workspace record-form insertion. SQL commands, bulk imports and external file changes are not interpreted as individual row events.
• Job completed, after a read job returns successfully or a reviewed write job commits. An optional condition is exact plugin-id/job-id. Chain-origin completions cannot recursively queue another chain. Actions/forms are not falsely represented as registered-job completions.

Conditions are deliberately simple exact table/job matching; there is no expression interpreter. Events are a bounded 32-notification native stream and coalesce to at most one pending request per rule (16 total). Busy bursts/disabled rules/chain-origin completions never create an unlimited queue. Rules are local to an open database window; no cross-process scheduler or exactly-once execution guarantee is implied.

Execution is attended: events only queue work and show a subtle notice. The user starts a chain. Read jobs run sequentially with actual progress/logs. Each write step stops at the existing immutable review with source revision checks, actual RO/license enforcement, recovery snapshot and atomic transaction; it cannot silently save because a rule exists. Empty write plans need explicit Continue and make no write. Steps use registered default field inputs; the first native rule editor does not persist custom input editing. Final per-step summaries are bounded to 4,096 characters, at most eight; detailed mutation/recovery records remain in Plugin Edit History.

Failure, cancel, package revocation, database replacement or closing the panel stops the chain. An accepted commit remains committed; previous successful steps are not rolled back with later steps. There is no automatic retry, resume-after-restart, unattended commit, schedule or cross-step transaction. Changing a plugin digest invalidates a saved step and requires recreating the rule after plugin approval. Disabling/deleting rules remains available even if their plugin is unavailable. View Raw Database/Escape remains an obvious exit, with normal browsing refreshed after attempted writes.

Runner process resource containment — implemented

All invocations now share a host-process admission ceiling of four concurrent runners (excess requests fail visibly, without an unbounded waiting queue). Each child has existing CPU limits, a 512-KiB RLIMIT_FSIZE, 64-descriptor RLIMIT_NOFILE, and disabled core dumps. Failure to set a limit stops the runner before evaluating plugin code.

A native timer independent of awaited database callbacks samples child physical footprint every 20 ms, stops a child over 256 MiB, and enforces the invocation wall deadline. Repeated unavailable accounting also stops execution. This is a watchdog, not a hard heap quota: allocations can overshoot between samples or scheduler delays. Four admitted children are not an aggregate resident-memory reservation. Tests use a lower 64-MiB threshold and accept either allocator rejection or watchdog termination; a subsequent invocation still works.

These process limits complement the fixed allocator and OS sandbox below. See PLUGIN_ISOLATION_NOTES.md for the native proof and remaining release matrix.

Fixed allocation and OS isolation — implemented

The engine-only QuickJS dependency is limited to the helper. Its custom allocator reserves exactly 64 MiB per invocation, splits/coalesces blocks inside that arena and fails allocations when exhausted; it never falls back to the system allocator. Runtime/context, strings, objects, ArrayBuffer/SharedArrayBuffer and pending Promise jobs use it. A 512-KiB JavaScript stack limit and interrupt deadline complement kernel CPU/process/file/descriptor limits. Four-runner admission and the independent footprint watchdog remain in force; neither is described as a hard whole-process RSS cap. Native Foundation/code/stack and bounded wire copies exist outside the arena.

The only sandbox entitlement is App Sandbox. No JIT, network or user-selected-file entitlement is granted to the helper. The host provides approved values over pipes, never database handles, raw file descriptors to databases or filesystem paths as capabilities. Frames have distinct kinds and preallocation length limits: request/final 512 KiB, database call 128 KiB, reply 256 KiB, event 4 KiB. Events require acknowledgements; calls cannot overlap. Existing eight-call/128-event/deadline limits apply. Plugin installation is inert; explicit Enable binds approval to package content. Removal, disable, changed content, database closure and unsafe helper signatures invalidate execution.

Native sandbox probes verify denied reads/writes outside the code directory, network connection and fork on the current host. The OS may permit public system/code resources; this is not a promise that the sandbox sees no files. No network/native module bridge is exposed. See PLUGIN_ISOLATION_NOTES.md for evidence and supported-OS release limits. The documentation syntax checker still uses JavaScriptCore only to parse examples; actual plugin execution and compatibility tests use QuickJS.