Vector

Operating and routing guidance for an AI coding agent working on a Kinetis application that installs kinetis/vector, the optional schema-driven admin package. This is not a human tutorial: a developer wants the Vector manual instead. Read Agent Workflow first; this page adds what Vector needs on top of it.

Confirm the package is installed

Call orbitron_inspect where Orbitron is registered, or read the project’s own composer.lock, and confirm that kinetis/vector is installed. When it is not, nothing on this page applies. This page is no reason to install Vector: install it only when the task or the user asks for an admin.

Where the guidance comes from

This page is kinetis://docs/vector, read with kinetis_read_doc like every page Agent Workflow routes through. The Vector manual it links to is published on the web, not served as kinetis://docs/* resources. Both describe main, so either can describe a newer Vector than the one installed.

The installed package is the authority for the exact contract:

  1. Read kinetis/vector’s own composer.json with orbitron_read_package_source for its requirements, its Kinetis\Vector\ autoload root under src/, and extra.kinetis.

  2. Read its README.md for the installed version’s setup and feature summary.

  3. Settle a signature, a default, a config key or a failure code in src/ with orbitron_search_package_source_tree when the file is unknown, orbitron_search_package_source when it is known, and a window around the reported line with orbitron_read_package_source. orbitron_list_package_source lists a directory when the layout is what you need. The descriptor’s JSON schema is resources/schema/descriptor.schema.json.

Without Orbitron, read the same files under the project’s own vendor/kinetis/vector.

@kinetis/vector-ui, the npm package a standalone admin is built from, is JavaScript that neither documentation server nor Orbitron’s installed-source tools reach. Read its package.json, the lockfile and its source with your own file-reading tools.

Workflow

  1. Confirm the installed version of kinetis/vector and of every Kinetis package the task touches.

  2. Route the task through the list below to the manual page that covers it, and read that section.

  3. Read the installed source for anything version-sensitive.

  4. Make the smallest change. A resource, dashboard, settings group, policy or action is ordinary application code, discovered from its attribute where it has one; there is no registry to edit.

  5. Run the verification checklist below, then review the change against Agent Correctness Review.

Task routing

  • Install and migrations. vendor/bin/kinetis vector:install publishes Vector’s migrations and the hosted UI bundle a released package ships, and is idempotent: run it again after every upgrade, then migrate. --connection=<name> puts Vector’s tables on a named connection, read at runtime from VECTOR_DB_CONNECTION. Getting started, Databases.

  • Resources, fields, forms, lists, records, actions, dashboards, settings and audit. A #[Resource] class extending VectorResource declares fields(), actions() and widgets(); a #[Dashboard] class extending VectorDashboard and a #[Settings] class extending SettingsGroup add dashboards and settings groups. All of them compile into the descriptor. Resources, Fields, Forms, Lists, Records, Actions, Dashboards and widgets, Settings, Audit trail and impersonation.

  • Authentication, authorization and field concealment. The application’s authentication middleware joins the vector middleware group and registers Kinetis\Http\CurrentUserInterface; Vector’s VectorAccessMiddleware then asks the application’s VectorAccessInterface whether that user may enter the admin at all. What an admitted user sees is the resource’s policy() class (a ResourcePolicyInterface), its scope() for rows, and the policy’s viewField() for fields. Authentication, Authorization, Field visibility.

  • The REST API and the MCP tools. Every route is under /vector. The MCP tools — vector_resources, vector_describe, vector_query, vector_get, vector_create, vector_update, vector_delete, vector_run_action and vector_widget — call the same services and policies under the caller’s identity. Over HTTP (POST /mcp) the authentication middleware joins the mcp group as well as vector. REST API, MCP tools, Serving them, Model Context Protocol (MCP).

  • Files, imports and exports. Uploads are checked by their bytes, never their name, and stored privately under a generated key. Export is CSV or Excel (XLSX), and every XLSX export runs as a job; import is CSV only, and always a job. Files and images, Export and import, Excel exports, Imports.

  • Jobs: queued or inline, terminal state, reaping. Actions that declare queued(), exports above the resource’s exportLimit(), every XLSX export and every import run on the application’s queue as the admin who started them; everything else runs in the request. Background jobs, Delivery, Stalled jobs, How an action runs.

  • Hosted or standalone UI, and the customization tiers. Standalone is a Nuxt application extending @kinetis/vector-ui on its own origin, signing in with a bearer token; hosted is the bundle the PHP application serves at /vector/ui behind its session. Customization has three tiers: descriptor and settings, runtime extensions, and the application’s own build. Deployment, Customizing the UI.

  • Database, queue and storage topology. An entity on a named connection, Vector’s own tables on another (VECTOR_DB_CONNECTION), Vector’s jobs on a named queue (VECTOR_QUEUE) or queue connection (VECTOR_QUEUE_CONNECTION), and uploads on a named storage connection (VECTOR_STORAGE_CONNECTION). Databases, Where the jobs go, Configuration.

  • Exact shapes and bounds. Every route, envelope and error is in the REST API, every environment key in Configuration, and every enforced bound in Limits.

Correctness boundaries

  • Definitions are compiled and request-neutral. The descriptor is compiled by kinetis build (or at boot, in development) from every resource, settings group and dashboard, and is immutable. A resource’s definition methods return the same data for every request; what varies per request belongs in its request-time hooks. The descriptor, Request-time hooks, Caching & AOT Compilation.

  • Identity and policy stay request-scoped. CurrentUserInterface is what the application’s authentication middleware registers for each request, and policies, hooks, actions and widgets are built by the request container. The VectorAccessInterface implementation is bound on the application scope and answers for every request, so it holds no request state. A job carries only the actor’s id, and ActorResolverInterface rebuilds the user in the worker. Request scope, Appendix: Container Lifecycle.

  • Vector’s own database connection is explicit. VECTOR_DB_CONNECTION names it, default when unset; it is never inferred from an administered entity’s connection. Vector’s own tables.

  • Relations and transactions do not span databases. The ORM refuses a relation across two connections at build time, and each connection commits on its own: Vector’s own rows (action log, audit, jobs) commit on its connection after the entity changes they describe. Entities on several connections, ORM, Database.

  • A queued job is not finished work. A queued action, export or import answers only that the job was pushed. Its row moves through queued, running, and then done or failed; a job is pushed for one attempt and claims its row with one conditional write, so a duplicate delivery does not run twice. Delivery, Queue.

  • The actor and the terminal state have to be proven. Without kinetis/queue and an ActorResolverInterface binding, queued actions and imports answer 403 and large exports are refused. A worker that dies mid-job leaves the row running; once it has reported no progress for the configured minutes it is answered as stalled, and vector:jobs:reap, run by a scheduler, marks it failed. Stalled jobs.

  • Uploads, export formats and the queue are optional capabilities. The descriptor’s capabilities (uploads, exportFormats, queue) report what this deployment has configured; a change that needs one does not assume it. Requirements, Storage.

  • Hosted and standalone authentication, and the CSP, are deployment concerns. Standalone sends Authorization: Bearer … from another origin and needs CORS; hosted sends the session cookie with X-CSRF-Token and needs a login page (VECTOR_LOGIN_URL). One middleware may accept both. The hosted shell runs under the application’s own SECURITY_CSP with its nonce, or under VECTOR_SHELL_CSP for that page alone. Deployment, Content Security Policy, One API, both modes.

Verification checklist

  • Boot and compile. The application boots, or kinetis build compiles, with every resource, action, widget, dashboard and settings group the change touches; vendor/bin/kinetis vector:list prints what compiled. A deliberate definition mistake fails naming the class and field. Checked at build.

  • Authorization and concealment. A restricted user gets the same refusal through REST and MCP, and a field viewField() hides is absent everywhere: the descriptor, records, the audit trail, exports and MCP results, with a filter, sort, grouping, column or written value naming it refused as unknown. Field visibility, Authorization.

  • The real backend. A claim about the database, queue or storage is checked against the connection, queue or filesystem Vector actually uses: “Read installed source to settle a fact” in Agent Correctness Review.

  • Settlement. Queued work is followed to its terminal state — done, failed, or stalled and then reaped as failed — never the push alone.

  • Request isolation. No identity, impersonation or record selection is read back on a later request or in a resident Fiber: “Request state leakage” in Agent Correctness Review.

  • The UI mode. Hosted or standalone is exercised only when the change touches UI behavior.

See also