Custom-widget packages and installations

A package is portable code plus a manifest. An installation is a workspace-owned widget that pins one immutable package version and binds its logical inputs to local data. A placement is that installed widget pinned on a particular dashboard, with optional placement settings.

Create and version#

Package creation submits source and a validated manifest to the workspace package endpoint. BankSync builds it server-side, stores source behind a private content reference, computes the digest from the bundle + manifest + SDK/runtime/toolchain provenance, and writes version 1 immutably.

Submitting changed source or manifest creates a new version. Reusing a version number is idempotent only when every immutable field is identical; different content is rejected.

Penny and MCP may build the same source-and-manifest contract into an inert package proposal. That proposal is not package persistence, installation, binding, or consent. The in-app Penny handoff opens the ordinary creator and installer for explicit review. MCP returns the portable artifact to its caller; direct MCP-to-app import is a later surface and generation cannot authorize data.

Install#

After a successful author build, Create package stores the immutable version and opens the installer. An existing workspace package can also be opened from Add a widget → Packages. Installation chooses a package version, local widget name/slug, installation settings, and one local binding for each required input. The server—not the browser—validates the package status, loads the immutable version, resolves the selected source's actually available schema, compiles field mappings and source scopes, fills setting defaults, and creates the v2 Widget. No source bytes are copied into the Widget document.

The beta installer accepts direct feed and direct bank inputs. It provides server-authoritative auto-mapping, manual field repair, bank-account scope, transaction/trade date scope, and declarative installation settings. It fails loudly for missing inputs, unknown input IDs, incompatible fields, archived packages, or unsupported composed sources.

Upgrade#

An upgrade is not a floating latest reference. The installation continues to pin its old digest until the inspector shows a newer version and the user explicitly upgrades. The inspector summarizes input, setting, and capability changes. Compatible direct bindings are recompiled against the target manifest; a new required input blocks the one-click upgrade until that input can be configured. The previous grant never transfers automatically: the new digest pauses data until consent is reviewed.

Portability rule#

Exportable package/template metadata may contain a package reference and logical input requirements. It must not contain concrete feed IDs, bank IDs, account IDs, query IDs, source fingerprints, credentials, grants, or installation binding fingerprints. Those are collected again in the target workspace.

Visibility and distribution#

Current creation supports private and workspace visibility. Repository models reserve unlisted and public states, but public creation, marketplace listing, public/portal execution, publisher verification, signing, moderation, and takedown distribution are gated off. Archived packages are a render/install kill switch; deprecated packages may continue running while users migrate.

Assumptions#

• Package IDs are global opaque identifiers; visibility checks still apply in the requesting workspace.
• Versions and content-addressed source/bundle references are retained while installations pin them.
• Slug uniqueness, automated upgrade rollout, marketplace ranking, billing, and publisher identity policy are outside the private workspace beta and must be designed before public launch.
• The current package contract editor is JSON-oriented for developer beta users; a future visual contract builder may author the same manifest without changing package identity.
• Reserved public model states do not imply public availability.