feat(app-showcase): bind persona positions on kernel:listening + announcements; document isDefault dual-track (#2926 ②⑤)

A fresh deploy booted with ZERO position↔permission-set bindings — every
persona silently degraded to the everyone baseline. Bindings are
record-authoritative (ADR-0090/0094) and cannot be a declarative seed (the
seed loader runs before the security bootstrap creates sys_position /
sys_permission_set, so name references can't resolve). They are ensured
imperatively by registerShowcasePositionBindings on kernel:listening — the
phase that fires only after every kernel:ready handler (incl. the security
bootstrap) has settled, so the referenced rows exist. everyone→member_default
is bound here too: the framework only auto-binds an app's isDefault set to
everyone when it is application-owned; the showcase ships as a package, so its
default lands in sys_audience_binding_suggestion (pending admin confirmation)
and is not live until confirmed.

Also seeds showcase_announcement demo rows and documents the isDefault
dual-track (app-level auto-bind vs package-level suggestion) in the spec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017bJWtKmZ2mFpRFAmmmoeqe

Author: claude

.changeset/spec-2926-isdefault-dualtrack.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): rewrite the `isDefault` permission-set docs to describe the actual dual-track behavior (#2926 ②): app-level `isDefault` sets are resolved as the SecurityPlugin's fallback and idempotently auto-bound to the `everyone` anchor at boot (guarded by the high-privilege-bits check), while package-level sets are never auto-bound and instead materialize a `sys_audience_binding_suggestion` an admin confirms. The previous "never auto-bound" wording contradicted the shipped app-level track.

examples/app-showcase/objectstack.config.ts

@@ -16,6 +16,7 @@ import { ShowcaseExternalDatasource } from './src/system/datasources/showcase-ex
 import { ExternalCustomer, ExternalOrder } from './src/data/objects/external/index.js';
 import { setupShowcaseExternalDatasource } from './src/system/datasources/external-fixture.js';
 import { registerRecalcEndpoint } from './src/system/server/recalc-endpoint.js';
+import { registerShowcasePositionBindings } from './src/security/bind-position-sets.js';
 import { TaskViews, ProjectViews, InquiryViews, BusinessUnitViews } from './src/ui/views/index.js';
 import { ShowcaseApp } from './src/ui/apps/index.js';
 import { ChartGalleryDashboard, OpsDashboard } from './src/ui/dashboards/index.js';
@@ -218,4 +219,7 @@ export const onEnable = async (ctx: unknown): Promise<void> => {
   await setupShowcaseExternalDatasource(ctx as Parameters<typeof setupShowcaseExternalDatasource>[0]);
   // Mount the custom REST endpoint behind the `showcase_recalc_estimate` api action.
   registerRecalcEndpoint(ctx as Parameters<typeof registerRecalcEndpoint>[0]);
+  // [#2926 ②] Ensure the persona position↔permission-set bindings exist after
+  // the security bootstraps (cannot be a seed — see bind-position-sets.ts).
+  registerShowcasePositionBindings(ctx as Parameters<typeof registerShowcasePositionBindings>[0]);
 };

examples/app-showcase/src/data/seed/index.ts

@@ -13,6 +13,7 @@ import { Product, Invoice, InvoiceLine } from '../objects/invoice.object.js';
 import { Contact } from '../objects/contact.object.js';
 import { Inquiry } from '../objects/inquiry.object.js';
 import { FieldZoo } from '../objects/field-zoo.object.js';
+import { Announcement } from '../objects/announcement.object.js';
 
 /**
  * Seed data sized to "feed every view": every Kanban column is populated,
@@ -161,6 +162,13 @@ const orgUnits = SeedSchema.parse({
   ],
 });
 
+// [#2926 ②] Position ↔ permission-set bindings are NOT seeded here: the seed
+// loader runs before the security bootstrap creates the sys_position /
+// sys_permission_set rows, so the required name references cannot resolve.
+// They are ensured imperatively on kernel:listening instead (after every
+// kernel:ready handler, incl. the security bootstrap, has settled) — see
+// `src/security/bind-position-sets.ts` (wired via `onEnable`).
+
 const teams = defineSeed(Team, {
   mode: 'upsert',
   externalId: 'name',
@@ -286,4 +294,20 @@ const preferences = defineSeed(Preference, {
   ],
 });
 
-export const ShowcaseSeedData = [accounts, contacts, inquiries, products, projects, tasks, categories, businessUnits, orgUnits, teams, memberships, fieldZoo, invoices, invoiceLines, preferences];
+/**
+ * [#2926 ⑤] Announcements — the read-visibility demo object finally ships
+ * with data, so its assertions stop dry-running on a fresh DB. The object has
+ * NO `name` field (display name derives from `title`); `owner_id` stays
+ * unset — users can't be seeded, and creation rights are deliberately narrow
+ * (only `showcase_ops` may create; everyone else is read-only by design).
+ */
+const announcements = defineSeed(Announcement, {
+  mode: 'upsert',
+  externalId: 'title',
+  records: [
+    { title: 'Welcome to the Showcase workspace', body: 'This demo org exercises the full permission model: positions, permission sets, sharing rules and field-level security. Log in as different personas to compare what each can see and edit.' },
+    { title: 'Q3 field-ops rollout', body: 'Field Operations onboards the new inquiry intake flow this quarter. New public inquiries are shared automatically with the Field Ops subtree.' },
+  ],
+});
+
+export const ShowcaseSeedData = [accounts, contacts, inquiries, products, projects, tasks, categories, businessUnits, orgUnits, teams, memberships, fieldZoo, invoices, invoiceLines, preferences, announcements];

examples/app-showcase/src/security/bind-position-sets.ts

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#2926 ②] Position ↔ permission-set bindings for the showcase personas.
+ *
+ * The permission model is record-authoritative (ADR-0090/0094): bindings live
+ * only as `sys_position_permission_set` rows. A fresh deploy used to boot with
+ * ZERO bindings — every persona silently degraded to the `everyone` baseline
+ * until an admin hand-assigned all sets.
+ *
+ * This cannot be a declarative SEED: the seed loader runs before the security
+ * bootstrap creates the `sys_position` / `sys_permission_set` rows, so the name
+ * references cannot resolve and the required lookups fail validation. So we play
+ * the admin's part imperatively — inserting each missing binding idempotently
+ * (dedup by position+set pair, stable ids).
+ *
+ * Timing matters. `kernel:ready` handlers run SEQUENTIALLY, each awaited, in
+ * registration order (`kernel.ts` `trigger`). The showcase AppPlugin starts
+ * BEFORE the Security plugin, so an app hook on `kernel:ready` runs *before*
+ * the security bootstrap has created the position/set rows — the rows never
+ * appear from inside that hook. We therefore bind on **`kernel:listening`**,
+ * the phase the kernel fires only AFTER every `kernel:ready` handler has
+ * completed (`kernel.ts` Phase 4 / `lite-kernel.ts`), so the bootstrap rows are
+ * guaranteed present.
+ *
+ * `everyone → showcase_member_default` IS bound here. The security plugin only
+ * auto-binds an app's `isDefault` set to `everyone` when that set is
+ * application-owned; the showcase ships as a package, so its default lands in
+ * `sys_audience_binding_suggestion` (pending admin confirmation) and is NOT
+ * live until confirmed. Binding it here keeps the demo's baseline working out
+ * of the box, idempotently and alongside the suggestion.
+ */
+
+const BINDINGS: ReadonlyArray<readonly [position: string, permissionSet: string]> = [
+  ['everyone', 'showcase_member_default'],
+  ['contributor', 'showcase_contributor'],
+  ['manager', 'showcase_manager'],
+  ['exec', 'showcase_executive'],
+  ['auditor', 'showcase_auditor'],
+  ['ops', 'showcase_ops'],
+  ['field_ops_delegate', 'showcase_field_ops_delegate'],
+  ['client_portal_user', 'showcase_guest_portal'],
+];
+
+const SYS = { isSystem: true } as const;
+
+interface BindHostContext {
+  ql: {
+    find: (object: string, query: unknown, options?: unknown) => Promise<unknown>;
+    insert: (object: string, data: Record<string, unknown>, options?: unknown) => Promise<unknown>;
+  };
+  logger?: { info?: (...a: unknown[]) => void; warn?: (...a: unknown[]) => void };
+  hook?: (event: string, handler: () => Promise<void> | void) => void;
+}
+
+/** Find one row by `name`, passing the system context the way the engine's own
+ * read path expects it (merged from `query.context`; see objectql `find`). */
+async function findOneByName(ctx: BindHostContext, object: string, name: string): Promise<{ id?: string } | undefined> {
+  try {
+    const rows = (await ctx.ql.find(object, { where: { name }, limit: 1, context: SYS })) as
+      | Array<{ id?: string }>
+      | { records?: Array<{ id?: string }> };
+    if (Array.isArray(rows)) return rows[0];
+    return rows?.records?.[0];
+  } catch (err) {
+    ctx.logger?.warn?.('[showcase] position binding lookup failed', {
+      object,
+      name,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+}
+
+export function registerShowcasePositionBindings(ctx: BindHostContext): void {
+  const run = async (): Promise<void> => {
+    let created = 0;
+    for (const [positionName, setName] of BINDINGS) {
+      const position = await findOneByName(ctx, 'sys_position', positionName);
+      const set = await findOneByName(ctx, 'sys_permission_set', setName);
+      if (!position?.id || !set?.id) {
+        ctx.logger?.warn?.('[showcase] position binding skipped (row missing)', { position: positionName, set: setName });
+        continue;
+      }
+      const existing = (await ctx.ql.find(
+        'sys_position_permission_set',
+        { where: { position_id: position.id, permission_set_id: set.id }, limit: 1, context: SYS },
+      )) as unknown;
+      const hit = Array.isArray(existing) ? existing[0] : (existing as { records?: unknown[] })?.records?.[0];
+      if (hit) continue;
+      try {
+        await ctx.ql.insert(
+          'sys_position_permission_set',
+          { id: `ppsb_showcase_${positionName}`, position_id: position.id, permission_set_id: set.id },
+          { context: SYS },
+        );
+        created += 1;
+      } catch (err) {
+        ctx.logger?.warn?.('[showcase] position binding insert failed', {
+          position: positionName,
+          set: setName,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    ctx.logger?.info?.('[showcase] position bindings ensured', { created, total: BINDINGS.length });
+  };
+
+  // Bind on `kernel:listening` — the phase that fires only after every
+  // `kernel:ready` handler (incl. the security bootstrap that seeds the
+  // position/set rows) has completed. Fall back to a deferred immediate run
+  // if the host context somehow omits the hook registrar.
+  if (typeof ctx.hook === 'function') {
+    ctx.hook('kernel:listening', run);
+  } else {
+    setTimeout(() => void run(), 0);
+  }
+}

packages/spec/src/security/permission.zod.ts

@@ -179,12 +179,24 @@ export const PermissionSetSchema = lazySchema(() => z.object({
     .describe('[ADR-0086 D3] Record provenance: package (upgrade-owned metadata) vs platform/user (env config)'),
 
   /**
-   * [ADR-0090 D5] Package SUGGESTION: on install the admin is prompted to bind
-   * this set to the built-in `everyone` position (default grants for
-   * authenticated users). Never auto-bound; carries no runtime semantics of
-   * its own. (The former `isProfile` flag was removed by ADR-0090 D2.)
+   * [ADR-0090 D5] Marks this set as the app's baseline for the built-in
+   * `everyone` position (default grants for authenticated users). Two tracks
+   * consume it (#2926 ②):
+   *
+   *  - **App-level** (the set is declared by the served app itself): the CLI
+   *    resolves the first `isDefault` set as the SecurityPlugin's
+   *    `fallbackPermissionSet`, and the plugin IDEMPOTENTLY AUTO-BINDS it to
+   *    `everyone` at boot — after a high-privilege-bits check refuses
+   *    dangerous sets. Without this a fresh deploy boots with zero bindings
+   *    and every persona silently degrades.
+   *  - **Package-level** (the set ships in an installed package with a
+   *    `packageId`): never auto-bound — it materializes a pending
+   *    `sys_audience_binding_suggestion` row that an admin confirms in Setup.
+   *
+   * Carries no runtime semantics of its own beyond these boot-time effects.
+   * (The former `isProfile` flag was removed by ADR-0090 D2.)
    */
-  isDefault: z.boolean().default(false).describe('[ADR-0090 D5] Install-time suggestion to bind this set to the everyone position (admin confirms; never auto-bound)'),
+  isDefault: z.boolean().default(false).describe('[ADR-0090 D5] App baseline for the everyone position: app-level sets are auto-bound at boot (guarded, idempotent); package-level sets become install-time suggestions an admin confirms'),
 
   /** Object Permissions Map: <entity_name> -> permissions */
   objects: z.record(z.string(), ObjectPermissionSchema).describe('Entity permissions'),