@jskit-ai/agent-docs 0.1.280 → 0.1.281

package/reference/autogen/packages/auth-provider-local-core.md

@@ -34,7 +34,8 @@ Exports
 - `PROVIDER_ID`
 - `buildAuthPayload({ user, session, profileProjector, profileOptions = {} })`
 - `buildAuthResult({ user, session, appProfile })`
-- `buildSessionAuthPayload({ appProfileProjection, devAuth, profileProjector, request, session, user, syncProfile = true })`
+- `buildProfileChangePayload({ user, profileProjector })`
+- `buildSessionAuthPayload({ appProfileProjection, devAuth, profileProjector, request, session, user, syncProfile = true, onlyWhenChanged = false })`
 - `findExistingAppProfile(user, profileProjector)`
 - `isAuthenticatingSession(session)`
 Local functions

package/reference/autogen/packages/connectors-catalog.md

@@ -951,6 +951,14 @@ Exports
 - `zohoOAuthMetadata(accounts)`
 - `normalizeZohoTokenResponse(response, expectedApiOrigin)`
 
+### `src/shared/ai-definition.js`
+Exports
+- `aiAccessLabels`
+- `aiDefinition`
+- `byAccessThenKey(a, b)`
+- `catalogueProvider(provider, connection)`
+- `configurableProviders`
+
 ### `src/shared/ai.js`
 Exports
 - `aiCatalogue`

package/reference/autogen/packages/database-runtime.md

@@ -16,6 +16,7 @@ Use this on demand; do not load the full index at startup.
 
 ### `src/server/database.js`
 Exports
+- `RUNTIME_QUERY_CHANNEL`
 - `createDatabase({ driver, env })`
 Local functions
 - `resolveDriverDialectId(driver)`
@@ -55,6 +56,38 @@ Local functions
 Exports
 - `DatabaseProvider`
 
+### `src/server/testDatabaseFile.js`
+Exports
+- None
+Local functions
+- `isRunning(pid)`
+- `claimDatabase(directory, databases)`
+
+### `src/server/testDatabases.js`
+Exports
+- `RUN_SETTINGS_FILE`
+- `countQueries(knex, work)`
+- `countRuntimeQueries(work)`
+- `matchesSnapshot(knexConfig, database, snapshot)`
+- `prepareTestDatabases({ knexConfig, environment, variable = "TEST_DB_NAME", count = 1, seed, schema = {}, appRoot = process.cwd() })`
+- `requireDisposableDatabase(environment, variable, count = 1, { connected = "" } = {})`
+- `restoreTestDatabase(knexConfig, database, snapshot)`
+- `testDatabaseNames(name, count)`
+- `testDatabaseRun({ knexConfig, environment, count, schema, appRoot = process.cwd() })`
+- `testDatabaseSnapshotKey(knexConfig, { appRoot = process.cwd(), schemaFiles = [] } = {})`
+- `type TestDatabaseSchema`
+Local functions
+- `folded(value)`
+- `milliseconds(since)`
+- `ledgerOf(knexConfig)`
+- `connectedDatabaseName(environment)`
+- `knexOn(knexConfig, database, connectionOptions = {})`
+- `withKnex(knexConfig, database, use, connectionOptions)`
+- `ledgerNames(knex, ledger, tables)`
+- `dialectOf(knexConfig)`
+- `refusedPrivilege(error)`
+- `recordStatements(listen, work)`
+
 ### `src/server/types.js`
 Exports
 - `type RuntimeDatabase`

package/reference/autogen/packages/kernel.md

@@ -538,6 +538,8 @@ Local functions
 - `isSurfaceRootRecord(record)`
 - `hostsChildViews(record)`
 - `hashScrollMargin(hash)`
+- `isLazyRouteComponent(component)`
+- `preloadOpeningRouteComponents(router, fallbackRoute)`
 
 ### `client/shellRouting.js`
 Exports
@@ -604,8 +606,12 @@ Local functions
 - `hasClientExport(packageJson)`
 - `isPathInsideRoot(rootPath, candidatePath)`
 - `splitSpecifierSuffix(source)`
+- `exportFile(target)`
+- `resolveClientBootImports(installedPackage, { packageMetadataUiRoutes, packageMetadataClientProviders })`
 - `resolveClientModulesFromInstalledPackages(installedPackages = [])`
 - `normalizeClientModulePackageMetadataEntries(value)`
+- `normalizeBootProviders(bootImports)`
+- `clientBootSpecifiers(entry)`
 - `resolveClientRuntimeDedupeSpecifiers(userResolveConfig = {})`
 
 ### `client/vite/index.js`
@@ -798,6 +804,12 @@ Local functions
 - `emptyInput()`
 - `handlerAsGiven(handler)`
 
+### `server/http/lib/deepFrozen.js`
+Exports
+- `isDeepFrozen(value)`
+Local functions
+- `isFrozenThroughout(node, checked)`
+
 ### `server/http/lib/errors.js`
 Exports
 - `HttpKernelError`
@@ -831,6 +843,10 @@ Exports
 - `type ActionCatalogue`
 - `type RuntimeFastify`
 Local functions
+- `sharedValidationSchema(schema)`
+- `namesEveryType(value)`
+- `isSharedResponseSchema(entry)`
+- `copyRouteSchema(schema)`
 - `toFastifyRouteOptions(route)`
 - `shouldStripFastifyBodySchema(route, schema)`
 - `normalizeHeaderValue(value)`
@@ -860,6 +876,7 @@ Exports
 - `resolveRouteValidatorOptions({ method = "", path = "", options = {} } = {})`
 Local functions
 - `stripJsonRestTransportExtensions(value)`
+- `stripSchemaCopy(value)`
 - `normalizeRouteSchemaSection(value, { context = "route section", defaultMode = "patch" } = {})`
 - `normalizeResponseDefinition(value, { context = "route responses" } = {})`
 - `normalizeAdvancedFastifySchema(value, { context = "route validator" } = {})`
@@ -869,9 +886,14 @@ Local functions
 ### `server/http/responseSerializerFactory.js`
 Exports
 - `createCachedResponseSerializerFactory(buildSerializer)`
+- `schemaCacheKey(schema)`
 Local functions
+- `schemaTools()`
 - `isJsonValue(value, ancestors = new Set())`
-- `schemaCacheKey(schema)`
+- `assertValidSchema(schema, name)`
+- `filedSchemaId(schema, fallback)`
+- `everyRefResolves(schema, externalSchemas)`
+- `compiledOnFirstUse(compile, options, key)`
 
 ### `server/http/securityHeaders.js`
 Exports
@@ -1055,6 +1077,7 @@ Exports
 Local functions
 - `fileLockError(message = "", code = FILE_LOCK_ERROR_CODE)`
 - `normalizedAbsolutePath(value = "", label = "path", errorCode = FILE_LOCK_ERROR_CODE)`
+- `lockThroughDescriptor(fd, cwd)`
 
 ### `server/support/importFreshModuleFromAbsolutePath.js`
 Exports
@@ -1146,3 +1169,6 @@ Local functions
 - `resolveFileDependencyRoot(appRoot, specifier = "")`
 - `resolveInstalledPackageRoot({ appRoot, packageId, parentPackageRoot = "" })`
 - `resolvePackageRoots({ appRoot, packageId, directSpecifier = "", parentPackageRoot = "" })`
+- `fileStamp(filePath)`
+- `stampsOf(filePaths)`
+- `walkInstalledPackages(normalizedAppRoot)`

package/reference/autogen/packages/oidc-issuer-core.md

@@ -174,7 +174,6 @@ Local functions
 - `isHubPath(url)`
 - `bearerToken(request)`
 - `sendRegistrationError(reply, error)`
-- `onProviderStatus(reply, matches, action)`
 - `parseJsonBody(buffer)`
 
 ### `src/server/mailer.js`

package/reference/autogen/packages/realtime.md

@@ -76,6 +76,7 @@ Exports
 - `type RuntimeDatabase`
 - `type RuntimeLogger`
 - `type ActorRoomsResolver`
+- `type ActorsRoomsResolver`
 - `type AudienceContributors`
 Local functions
 - `flattenEntries(value)`
@@ -107,16 +108,17 @@ Exports
 
 ### `src/server/realtimeDelivery.js`
 Exports
-- `createRealtimeDelivery({ io, database, logger, authService, audiences: { mayContribute, resolveActorRooms } })`
+- `createRealtimeDelivery({ io, database, logger, authService, audiences: { mayContribute, resolveActorsRooms } })`
 - `matchesRealtimeEvent(event)`
 - `type AuthService`
 - `type ActorRoomsResolver`
+- `type ActorsRoomsResolver`
 - `type AudienceContributors`
 Local functions
 - `publicRealtimePayload(event)`
-- `valueAsKey(value)`
-- `sharedWithinPass(load, keyOf = valueAsKey)`
-- `createPassChecks(authService, resolveActorRooms)`
+- `sharedWithinPass(load, keyOf)`
+- `createPassChecks(authService, resolveActorsRooms)`
+- `rememberedActorId(socket)`
 
 ### `src/server/RealtimeProvider.js`
 Exports
@@ -133,7 +135,7 @@ Exports
 - `REDIS_NAMESPACE_ENV_KEY`
 - `resolveRealtimeRedisUrl(env)`
 - `resolveRealtimeRedisNamespace(env)`
-- `configureSocketIoRedisAdapter(io, { redisUrl = "", redisNamespace = "", logger, createRedisAdapter = createSocketIoRedisAdapter, createRedisConnection = createRedisClient })`
+- `configureSocketIoRedisAdapter(io, { redisUrl = "", redisNamespace = "", logger, createRedisAdapter, createRedisConnection })`
 - `closeSocketIoRedisConnections({ pubClient, subClient })`
 - `countConnectedClients(io)`
 Local functions
@@ -149,6 +151,7 @@ Exports
 Exports
 - `type RuntimeRealtime`
 - `type ActorRoomsResolver`
+- `type ActorsRoomsResolver`
 - `type AudienceContributors`
 - `type RealtimeAudienceContributor`
 

package/reference/autogen/packages/shell-web.md

@@ -500,10 +500,11 @@ Exports
 - `resolveAppPlacementTopologyExport(exported, logger)`
 Local functions
 - `loadAppModule({ importModule, specifier, label, resolve, invalidExportMessage = "", loadFailureMessage, fallback, logger, asyncModuleRecoveryRuntime })`
-- `loadAppPlacementDefinitions(logger, asyncModuleRecoveryRuntime)`
-- `loadAppPlacementTopology(logger, asyncModuleRecoveryRuntime)`
+- `importAppModules()`
+- `loadAppPlacementDefinitions(logger, asyncModuleRecoveryRuntime, pendingImport)`
+- `loadAppPlacementTopology(logger, asyncModuleRecoveryRuntime, pendingImport)`
 - `createErrorConfigToolkit(errorRuntime)`
-- `loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime)`
+- `loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime, pendingImport)`
 - `installVueErrorBridge(vueApp, errorRuntime, logger)`
 - `installRouterErrorBridge(router, errorRuntime, logger)`
 

package/reference/autogen/packages/workspaces-core.md

@@ -252,7 +252,7 @@ Exports
 Exports
 - `WorkspacesIntegrationsProvider`
 Local functions
-- `resolveWorkspaceRealtimeScopes(workspaceMemberships, actorId)`
+- `resolveWorkspaceRealtimeScopes(workspaceMemberships, actorIds)`
 
 ### `src/server/workspacesRuntime.js`
 Exports

package/reference/autogen/tooling/jskit-catalog.md

@@ -14,6 +14,45 @@ Use this on demand; do not load the full index at startup.
 
 ### scripts
 
+### `scripts/browser-test-build.mjs`
+Exports
+- `buildFrontend({ appRoot = process.cwd(), build = "npm run build", run = runToCompletion } = {})`
+Local functions
+- `seconds(since)`
+- `digest(file)`
+- `buildFingerprint(appRoot, build, env = process.env)`
+- `runToCompletion(command, appRoot)`
+- `lastBuild(appRoot)`
+- `isRunning(pid)`
+- `lockBuild(appRoot)`
+- `isCurrent(appRoot, inputs)`
+
+### `scripts/browser-test-servers.mjs`
+Exports
+- None
+Local functions
+- `seconds(since)`
+- `words(command)`
+- `prepareWorkers(appRoot, prepare, workers, baseUrls)`
+- `signInWorkers(appRoot, signIn, baseUrls, environments, signedInStates)`
+- `waitUntilReady(url, server, name)`
+- `stopServers()`
+
+### `scripts/browser-test-times.mjs`
+Exports
+- None
+
+### `scripts/browser-tests.mjs`
+Exports
+- `SETTINGS_VARIABLE`
+- `browserTestConfig({ testDir = "./tests/e2e", port = DEFAULT_PORT, server = "node ./bin/server.js", build = "npm run build", prepare = "", signIn = "", env = {}, health = "/api/health", globalTimeout = GLOBAL_TIMEOUT_MS, environment = process.env, cwd = process.cwd() } = {})`
+- `browserTestWorkers({ env = process.env, argv = process.argv } = {})`
+Local functions
+- `positiveInteger(value)`
+- `managedBaseUrl(env)`
+- `commandLineWorkers(argv)`
+- `preparedWorkerEnvironment(file, index)`
+
 ### `scripts/build-catalog.mjs`
 Exports
 - None
@@ -245,10 +284,26 @@ Exports
 Exports
 - `planTestRuns(args, { cwd = process.cwd(), concurrency = testConcurrency() } = {})`
 - `runTests(args)`
+- `withTimeReporter(run, destination)`
 Local functions
 - `findTestFiles(patterns, cwd)`
 - `readAloneFiles(files, cwd)`
-- `runNode(args)`
+- `aloneDestination(destination)`
+- `aloneRunOptions(options)`
+- `aloneShard(files, options)`
+- `runNode(args, env)`
+
+### `scripts/test-databases.mjs`
+Exports
+- `DATABASES_OPTION`
+- `testDatabaseRunFor(count, cwd = process.cwd())`
+Local functions
+- `withOwnEnvironment(load)`
+
+### `scripts/test-file-stop.mjs`
+Exports
+- `STOPPED_PREFIX`
+- `STOPS_VARIABLE`
 
 ### `scripts/test-runs.mjs`
 Exports
@@ -262,8 +317,23 @@ Local functions
 - `configOption(args)`
 - `lineOf(contents, needle, after = "")`
 - `findConfig(directory, explicit, names)`
+- `usesBrowserHarness(source)`
+- `developmentServerCommand(source)`
+- `checkPlaywrightIsolation({ file, source, report })`
 - `checkRunnerConfig({ root, configPath, directory, runner, report })`
 
+### `scripts/test-time-report.mjs`
+Exports
+- `BOUNDS_FILE`
+- `FILE_TIMES`
+- `checkTestTimes({ bounds, files, tests, wallMs, stopped = [] })`
+- `fileStop({ bound, recorded })`
+- `reportTestTimes({ cwd, collected, directory, wallMs })`
+- `writeFileStops({ cwd, files, directory })`
+Local functions
+- `seconds(ms)`
+- `readTestTimeBounds(cwd)`
+
 ### `scripts/verify-packages.mjs`
 Exports
 - `main()`

package/skills/jskit/SKILL.md

@@ -131,9 +131,11 @@ slowest files. Find why a check is slow; never raise its time limit. Typed
 features' repository and Tests rules say how.
 
 Test files run in parallel by default, bounded by the machine: a script runs
-`jskit test`, never `node --test` or a fixed `--test-concurrency`, and
-Playwright's `workers` and Vitest's `maxWorkers` are `testConcurrency()` from
-`@jskit-ai/jskit-catalog/test-budget`; plain `jskit check` fails anything else.
-Files that collide when run together get isolated (their own port, temporary
-directory and database), never serialised. A file that truly must run alone
-says why on its first line, `// jskit-test: alone - <reason>`.
+`jskit test` (`--databases`: a `TEST_DB_NAME` copy per file), never
+`node --test` or a fixed `--test-concurrency`; Playwright's config is
+`browserTestConfig()` from `@jskit-ai/jskit-catalog/browser-tests` and Vitest's
+`maxWorkers` is `testConcurrency()` from `@jskit-ai/jskit-catalog/test-budget`.
+Plain `jskit check` fails anything else. Files that collide when run together
+get isolated (their own port, temporary directory and database), never
+serialised. A file that truly must run alone says why on its first line,
+`// jskit-test: alone - <reason>`.

package/skills/jskit/references/client-features.md

@@ -232,7 +232,7 @@ const ConversationClientProvider = defineProvider({
   },
   /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
-    components.register("conversation.web.settings.element", ConversationSettingsElement);
+    components.register("conversation.web.status.widget", ConversationStatusWidget);
   }
 });
 
@@ -241,6 +241,40 @@ const components = new Map();
 export function registerComponent(id, component) { components.set(id, component); }
 ```
 
+### Provider subpaths
+
+**Export each client provider by a subpath of its own. The provider's file
+imports only what every page needs, such as a widget the shell always shows; a
+screen that only some routes show is imported by those routes.**
+
+Why: every page of every app loads the client providers, and what they import,
+before it shows anything. The client bootstrap imports a provider through the
+subpath export that names its file, so the screens `./client` re-exports, and
+their libraries, load only with the routes that show them. A provider without a
+subpath, or a `./client` that declares `routeComponents` or `clientRoutes` or
+uses `export *`, brings all of `./client` to every page.
+
+```json
+// good: package.json
+"exports": {
+  "./client": "./src/client/index.js",
+  "./client/providers/ConversationClientProvider": "./src/client/providers/ConversationClientProvider.js"
+}
+
+// bad: package.json, no subpath for the provider, so every page loads all of ./client
+"exports": {
+  "./client": "./src/client/index.js"
+}
+```
+
+```js
+// good: the provider's file imports the widget every page shows
+import ConversationStatusWidget from "../components/ConversationStatusWidget.vue";
+
+// bad: the provider's file imports a screen that only its route shows
+import ConversationSettingsScreen from "../components/ConversationSettingsScreen.vue";
+```
+
 ### Injected values
 
 **`inject()` takes the owner's exported key, never a literal. A required value

package/skills/jskit/references/existing-application-migration.md

@@ -128,7 +128,13 @@ The foundation servers reuse compiled response serializers for identical JSON
 schemas through `createCachedResponseSerializerFactory` from
 `@jskit-ai/kernel/server/http`. This reduces duplicate startup compilation and
 retained memory in applications with many routes. Each Fastify compiler context
-keeps its own cache; request data and response payloads are not cached.
+keeps its own cache; request data and response payloads are not cached. A
+serializer is compiled when a response first uses it, in every environment, so
+startup compiles none. Startup still checks every response schema as
+fast-json-stringify would before building it: an invalid schema or a `$ref`
+that does not resolve stops the server. A problem fast-json-stringify only
+finds while generating a serializer fails the first response that uses it, so
+keep a test that calls each route.
 
 Existing applications adopt the same setup in their own `server.js` after
 upgrading JSKIT and declaring the directly used

package/skills/jskit/references/heuristics/typed-features.md

@@ -85,9 +85,9 @@ ends with the same link.
   - [Tests are not callers](../typed-features.md#tests-are-not-callers)
 - `…ForTests`, `__reset…`, `testOnly…` exports (`jskit/no-test-only-export`)
   - [No test-only exports](../typed-features.md#no-test-only-exports)
-- a list, batch or write test with one to three rows, no query count, a fixed query ceiling tuned to pass, a slow endpoint first seen with real data
+- a list, batch or write test with one to three rows, no query count, a fixed query ceiling tuned to pass, a slow endpoint first seen with real data, a hand-written `knex.on("query")` counter, a patched `Client.prototype.query`, `countQueries`, `countRuntimeQueries`, a route's query count
   - [Query counts at realistic sizes](../typed-features.md#query-counts-at-realistic-sizes)
-- `node --test --test-concurrency=1`, `workers: 1`, `fileParallelism: false`, a suite that runs one file at a time, test files that collide when run together, `test/*` findings of `jskit check`
+- `node --test --test-concurrency=1`, `workers: 1`, `fileParallelism: false`, a suite that runs one file at a time, test files that collide when run together, a Playwright webServer running `npm run develop` or `vite`, a browser suite that takes hours, `test/*` findings of `jskit check`
   - [Test files run in parallel](../typed-features.md#test-files-run-in-parallel)
 - `knex.migrate.latest()` in each test file, a template database rebuilt by migrating, test preparation slower than its tests
   - [Test databases are prepared once](../typed-features.md#test-databases-are-prepared-once)

package/skills/jskit/references/heuristics/ui-testing.md

@@ -50,23 +50,28 @@ Rules:
 ## Keep startup incremental
 
 Run related cases in one suite invocation. Prepare the isolated database and
-fixtures once for that invocation, never once per test. Retain the test schema
-and migration ledger, apply only pending migrations, and reset fixture data
-deterministically. Restore any migration-owned baseline rows through the test
-seed. MySQL applications start from the `database/mysql-application` pattern's
-`example/tests/browser/database.js`. Require a repeat-start regression test that
-proves unchanged migration history, removal of stale data, pending migration
-application, and isolation from the normal database.
-
-Use `BROWSER_TEST_DB_NAME` for that retained schema and a different
-`TEST_DB_NAME` for disposable integration and migration tests. Reject a name
-collision before connecting. Include disposable cleanup between browser starts
-in the regression: one test's teardown must not erase another test's migrations.
-
-Do not drop/recreate the database, replay completed migrations, build every
-module fixture, or run a production frontend build for each focused check. A
+fixtures once for that invocation, never once per test. An app's
+`playwright.config.mjs` is `browserTestConfig()` from
+`@jskit-ai/jskit-catalog/browser-tests`: the production build, made once and
+reused while its sources are unchanged, and one server, port and database per
+worker. Its `prepare` module (the `database/mysql-application` and
+`database/postgres-application` patterns' `example/tests/e2e/databases.js`)
+restores each worker's copy of `BROWSER_TEST_DB_NAME` from the stored schema
+snapshot and runs the fixture seed, which restores any migration-owned
+baseline rows. The migrations are replayed only when one changes, so a second
+run reports a stored snapshot, no stale rows, and an unchanged normal
+database.
+
+Use `BROWSER_TEST_DB_NAME` for the browser copies and a different
+`TEST_DB_NAME` for disposable integration and migration tests; the harness
+refuses a collision, or one with the application's database, before
+connecting.
+
+Do not replay completed migrations, build every module fixture, or run a
+production frontend build for each focused check. A
 build made once for a whole run is different: it is the fix when a development
-server makes every page load slow. Choose small fixture sets for the selected
+server makes every page load slow, and browser tests never run on the
+development server. Choose small fixture sets for the selected
 suite; realistic row counts belong in the database tests that compare each
 endpoint's query counts. Fresh-schema
 migration tests and production-artifact tests are separate operations. Measure

package/skills/jskit/references/multi-homing.md

@@ -56,8 +56,12 @@ config.tenancyPolicy = {
 ```
 
 Provisioning runs in the users profile-sync lifecycle after registration and
-sign-in. The first run creates the personal workspace, its owner membership and
-its settings; later runs reuse it. The default name is the user's display name,
+sign-in, at each session refresh, and on a request whose identity's email or
+display name changed. The first run creates the personal workspace, its owner
+membership and its settings; later runs reuse it. An ordinary request only reads
+the existing profile, so a personal workspace, owner membership or settings row
+deleted while the person is signed in comes back at their next sign-in or
+session refresh, not at their next request. The default name is the user's display name,
 or email, followed by "'s Workspace". To choose another, provide the
 `workspaces.personal-workspace-name` capability from an application feature. It
 receives the synchronized profile (`id`, `displayName`, `email`, `username`), and