feat(spec): ADR-0079 record display-name foundation — nameField + resolver

os-zhuang · claude · os-zhuang · commit 954a5d1627cf · 2026-06-29T00:32:09.000+08:00
- Add canonical `nameField` to ObjectSchema; `displayNameField` kept as a
  deprecated back-compat alias (parse/safeParse/create map it → nameField).
- New `data/display-name.ts`: isTitleEligible, resolveDisplayField (nameField
  → displayNameField → ranked type-aware derivation), resolveRecordDisplayName
  (Record #&lt;id&gt; floor, never "Untitled"), provisionPrimary (designate-or-
  synthesize, idempotent), objectTitleCompleteness. 36 unit tests.
- Consumers (objectql search, plugin-approvals) read nameField ?? displayNameField.
- Blueprint object schema carries optional `nameField` (AI authoring).
- Migrate single-field-title sys objects to explicit nameField (additive).
- Auto-provision NOT wired at registry (synthesize would migrate system tables);
  seam + designate-only path documented as TODO(ADR-0079). titleFormat retained.

Gates: @objectstack/spec 6642/6642, objectql 719/719 — green.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts
@@ -1927,7 +1927,9 @@ export class ObjectQL implements IDataEngine {
           fields: _findSchema.fields as any,
           searchableFields: (_findSchema as any).searchableFields,
           requestedFields: _reqFields,
-          displayField: (_findSchema as any).displayNameField,
+          // [ADR-0079] `nameField` is the canonical primary-title pointer;
+          // `displayNameField` is the deprecated alias (still honored).
+          displayField: (_findSchema as any).nameField ?? (_findSchema as any).displayNameField,
         });
         if (_searchFilter) {
           ast.where = ast.where ? { $and: [ast.where, _searchFilter] } : _searchFilter;
diff --git a/packages/objectql/src/registry.ts b/packages/objectql/src/registry.ts
@@ -567,6 +567,21 @@ export class SchemaRegistry {
     // applySystemFields().
     schema = applySystemFields(schema, { multiTenant: this.multiTenant });
 
+    // TODO(ADR-0079): wire `provisionPrimary` (from `@objectstack/spec/data`)
+    // HERE — this is the object materialization seam. It should run for
+    // `ownership === 'own'` only (extensions must not synthesize a title) and
+    // AFTER `applySystemFields` (so a synthesized `name` co-exists with system
+    // columns). NOT wired yet on purpose: `provisionPrimary` SYNTHESIZES a real
+    // `name` text field when nothing is title-eligible, which the driver's
+    // `syncSchema` would materialize as a new DB column on dozens of title-less
+    // system/append-only tables (e.g. sys_record_share, sys_member) that today
+    // rely on `titleFormat`. Enabling that is a schema-migration-bearing change
+    // and must be staged behind the ADR-0079 required-title refine. Until then
+    // the canonical pointer is resolved on read via `resolveDisplayField`.
+    // To wire the DESIGNATE-only half safely (set nameField when derivable,
+    // never synthesize), split `provisionPrimary` or add a `{ synthesize:false }`
+    // option and call it here for own-objects.
+
     const shortName = schema.name;
     const fqn = computeFQN(namespace, shortName);
 
diff --git a/packages/platform-objects/src/audit/sys-email-template.object.ts b/packages/platform-objects/src/audit/sys-email-template.object.ts
@@ -25,6 +25,7 @@ export const SysEmailTemplate = ObjectSchema.create({
   managedBy: 'config',
   description: 'Outbound email template (subject + body + variables) resolved by name+locale',
   displayNameField: 'label',
+  nameField: 'label', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['name', 'label', 'category', 'locale', 'active'],
 
diff --git a/packages/platform-objects/src/audit/sys-email.object.ts b/packages/platform-objects/src/audit/sys-email.object.ts
@@ -27,6 +27,7 @@ export const SysEmail = ObjectSchema.create({
   managedBy: 'append-only',
   description: 'Outbound email delivery log',
   displayNameField: 'subject',
+  nameField: 'subject', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{subject}',
   compactLayout: ['subject', 'to', 'status', 'sent_at'],
 
diff --git a/packages/platform-objects/src/audit/sys-job-queue.object.ts b/packages/platform-objects/src/audit/sys-job-queue.object.ts
@@ -33,6 +33,7 @@ export const SysJobQueue = ObjectSchema.create({
   managedBy: 'system',
   description: 'Durable job/message queue including dead letters',
   displayNameField: 'queue',
+  nameField: 'queue', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{queue} #{id}',
   compactLayout: ['queue', 'status', 'attempts', 'scheduled_for', 'last_error'],
 
diff --git a/packages/platform-objects/src/audit/sys-job-run.object.ts b/packages/platform-objects/src/audit/sys-job-run.object.ts
@@ -24,6 +24,7 @@ export const SysJobRun = ObjectSchema.create({
   managedBy: 'append-only',
   description: 'Background job execution audit trail',
   displayNameField: 'job_name',
+  nameField: 'job_name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{job_name} @ {started_at}',
   compactLayout: ['job_name', 'status', 'started_at', 'duration_ms', 'attempt'],
 
diff --git a/packages/platform-objects/src/audit/sys-job.object.ts b/packages/platform-objects/src/audit/sys-job.object.ts
@@ -24,6 +24,7 @@ export const SysJob = ObjectSchema.create({
   managedBy: 'system',
   description: 'Catalogue of registered background jobs',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'schedule_type', 'active', 'last_run_at', 'last_status'],
 
diff --git a/packages/platform-objects/src/audit/sys-notification.object.ts b/packages/platform-objects/src/audit/sys-notification.object.ts
@@ -34,6 +34,7 @@ export const SysNotification = ObjectSchema.create({
   managedBy: 'system',
   description: 'Notification events — one row per emit() (ADR-0030 Layer 2 ingress)',
   displayNameField: 'topic',
+  nameField: 'topic', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{topic}',
   compactLayout: ['topic', 'severity', 'source_object', 'created_at'],
 
diff --git a/packages/platform-objects/src/audit/sys-saved-report.object.ts b/packages/platform-objects/src/audit/sys-saved-report.object.ts
@@ -32,6 +32,7 @@ export const SysSavedReport = ObjectSchema.create({
   managedBy: 'platform',
   description: 'Persisted ObjectQL report definition — re-runnable and schedulable',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'object_name', 'format', 'owner_id', 'updated_at'],
 
diff --git a/packages/platform-objects/src/identity/sys-api-key.object.ts b/packages/platform-objects/src/identity/sys-api-key.object.ts
@@ -30,6 +30,7 @@ export const SysApiKey = ObjectSchema.create({
   },
   description: 'API keys for programmatic access',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'prefix', 'user_id', 'expires_at', 'revoked'],
 
diff --git a/packages/platform-objects/src/identity/sys-business-unit.object.ts b/packages/platform-objects/src/identity/sys-business-unit.object.ts
@@ -29,6 +29,7 @@ export const SysBusinessUnit = ObjectSchema.create({
   managedBy: 'platform',
   description: 'Canonical Business Unit tree — hierarchical org/data-partition node (company / division / department / region / office). ADR-0057 D2.',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'kind', 'parent_business_unit_id', 'manager_user_id'],
 
diff --git a/packages/platform-objects/src/identity/sys-device-code.object.ts b/packages/platform-objects/src/identity/sys-device-code.object.ts
@@ -35,6 +35,7 @@ export const SysDeviceCode = ObjectSchema.create({
     docsUrl: 'https://docs.objectstack.ai/adr/0010-metadata-protection',
   },
   description: 'OAuth 2.0 Device Authorization Grant (RFC 8628) pending requests',
+  nameField: 'user_code', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
   titleFormat: '{user_code}',
   compactLayout: ['user_code', 'status', 'client_id', 'expires_at'],
 
diff --git a/packages/platform-objects/src/identity/sys-oauth-application.object.ts b/packages/platform-objects/src/identity/sys-oauth-application.object.ts
@@ -34,6 +34,7 @@ export const SysOauthApplication = ObjectSchema.create({
   },
   description: 'Registered OAuth/OIDC client applications',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'client_id', 'type', 'disabled'],
 
diff --git a/packages/platform-objects/src/identity/sys-organization.object.ts b/packages/platform-objects/src/identity/sys-organization.object.ts
@@ -27,6 +27,7 @@ export const SysOrganization = ObjectSchema.create({
   },
   description: 'Organizations for multi-tenant grouping',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'slug'],
 
diff --git a/packages/platform-objects/src/identity/sys-scim-provider.object.ts b/packages/platform-objects/src/identity/sys-scim-provider.object.ts
@@ -41,6 +41,7 @@ export const SysScimProvider = ObjectSchema.create({
   },
   description: 'SCIM 2.0 connections (bearer tokens) external IdPs use to provision/deprovision this environment\'s users',
   displayNameField: 'provider_id',
+  nameField: 'provider_id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{provider_id}',
   compactLayout: ['provider_id', 'organization_id'],
 
diff --git a/packages/platform-objects/src/identity/sys-session.object.ts b/packages/platform-objects/src/identity/sys-session.object.ts
@@ -31,6 +31,7 @@ export const SysSession = ObjectSchema.create({
   },
   description: 'Active user sessions',
   displayNameField: 'user_id',
+  nameField: 'user_id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: 'Session — {user_id}',
   compactLayout: ['user_id', 'ip_address', 'expires_at'],
 
diff --git a/packages/platform-objects/src/identity/sys-sso-provider.object.ts b/packages/platform-objects/src/identity/sys-sso-provider.object.ts
@@ -55,6 +55,7 @@ export const SysSsoProvider = ObjectSchema.create({
   },
   description: 'External SSO identity providers (OIDC / SAML) this environment federates login to',
   displayNameField: 'provider_id',
+  nameField: 'provider_id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{provider_id}',
   compactLayout: ['provider_id', 'issuer', 'domain'],
 
diff --git a/packages/platform-objects/src/identity/sys-team.object.ts b/packages/platform-objects/src/identity/sys-team.object.ts
@@ -27,6 +27,7 @@ export const SysTeam = ObjectSchema.create({
   },
   description: 'Teams within organizations for fine-grained grouping',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'organization_id'],
 
diff --git a/packages/platform-objects/src/identity/sys-user-preference.object.ts b/packages/platform-objects/src/identity/sys-user-preference.object.ts
@@ -27,6 +27,7 @@ export const SysUserPreference = ObjectSchema.create({
   // surface in Setup is a support/diagnostic view only.
   managedBy: 'system',
   description: 'Per-user key-value preferences (theme, locale, etc.)',
+  nameField: 'key', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
   titleFormat: '{key}',
   compactLayout: ['user_id', 'key'],
 
diff --git a/packages/platform-objects/src/identity/sys-user.object.ts b/packages/platform-objects/src/identity/sys-user.object.ts
@@ -28,6 +28,7 @@ export const SysUser = ObjectSchema.create({
   },
   description: 'User accounts for authentication',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{name}',
   compactLayout: ['name', 'email', 'email_verified'],
 
diff --git a/packages/platform-objects/src/system/sys-setting.object.ts b/packages/platform-objects/src/system/sys-setting.object.ts
@@ -40,6 +40,7 @@ export const SysSetting = ObjectSchema.create({
   managedBy: 'system',
   description: 'Generic K/V store backing the SettingsManifest contract.',
   displayNameField: 'key',
+  nameField: 'key', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{namespace}.{key}',
   compactLayout: ['namespace', 'key', 'scope', 'updated_at'],
 
diff --git a/packages/plugins/plugin-approvals/src/approval-service.ts b/packages/plugins/plugin-approvals/src/approval-service.ts
@@ -1419,7 +1419,9 @@ export class ApprovalService implements IApprovalService {
     try {
       const schema: any = (this.engine as any).getSchema?.(object);
       const fields = schema?.fields ?? {};
-      const declared = schema?.displayNameField;
+      // [ADR-0079] `nameField` is the canonical primary-title pointer;
+      // `displayNameField` is the deprecated alias (still honored).
+      const declared = schema?.nameField ?? schema?.displayNameField;
       if (declared && declared !== 'id' && fields[declared]) return declared;
       for (const cand of ['name', 'title', 'subject', 'label']) {
         if (fields[cand]) return cand;
diff --git a/packages/plugins/plugin-approvals/src/sys-approval-action.object.ts b/packages/plugins/plugin-approvals/src/sys-approval-action.object.ts
@@ -22,6 +22,7 @@ export const SysApprovalAction = ObjectSchema.create({
   managedBy: 'append-only',
   description: 'Append-only audit trail for approval actions',
   displayNameField: 'id',
+  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{action} · {step_name}',
   compactLayout: ['request_id', 'step_name', 'action', 'actor_id', 'created_at'],
 
diff --git a/packages/plugins/plugin-approvals/src/sys-approval-approver.object.ts b/packages/plugins/plugin-approvals/src/sys-approval-approver.object.ts
@@ -33,6 +33,7 @@ export const SysApprovalApprover = ObjectSchema.create({
   managedBy: 'system',
   description: 'Normalized pending-approver rows for indexed inbox queries',
   displayNameField: 'id',
+  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{approver} · {request_id}',
   compactLayout: ['request_id', 'approver', 'created_at'],
 
diff --git a/packages/plugins/plugin-approvals/src/sys-approval-request.object.ts b/packages/plugins/plugin-approvals/src/sys-approval-request.object.ts
@@ -31,6 +31,7 @@ export const SysApprovalRequest = ObjectSchema.create({
   managedBy: 'system',
   description: 'Live approval instance tracked per submission',
   displayNameField: 'id',
+  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{process_name} · {record_id}',
   compactLayout: ['process_name', 'object_name', 'record_id', 'status', 'current_step', 'submitter_id', 'updated_at'],
 
diff --git a/packages/plugins/plugin-approvals/src/sys-approval-token.object.ts b/packages/plugins/plugin-approvals/src/sys-approval-token.object.ts
@@ -22,6 +22,7 @@ export const SysApprovalToken = ObjectSchema.create({
   managedBy: 'system',
   description: 'Single-use tokens behind actionable approval links',
   displayNameField: 'id',
+  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
 
   fields: {
     id: Field.text({ label: 'Token ID', required: true, readonly: true, group: 'System' }),
diff --git a/packages/plugins/plugin-audit/src/objects/sys-activity.object.ts b/packages/plugins/plugin-audit/src/objects/sys-activity.object.ts
@@ -25,6 +25,7 @@ export const SysActivity = ObjectSchema.create({
   managedBy: 'append-only',
   description: 'Recent activity stream entries (lightweight, denormalized)',
   displayNameField: 'summary',
+  nameField: 'summary', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{type} · {summary}',
   compactLayout: ['timestamp', 'type', 'actor_name', 'summary'],
 
diff --git a/packages/plugins/plugin-audit/src/objects/sys-audit-log.object.ts b/packages/plugins/plugin-audit/src/objects/sys-audit-log.object.ts
@@ -22,6 +22,7 @@ export const SysAuditLog = ObjectSchema.create({
   managedBy: 'append-only',
   description: 'Immutable audit trail for platform events',
   displayNameField: 'action',
+  nameField: 'action', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{action} · {object_name}',
   compactLayout: ['created_at', 'action', 'object_name', 'record_id', 'user_id'],
 
diff --git a/packages/plugins/plugin-audit/src/objects/sys-comment.object.ts b/packages/plugins/plugin-audit/src/objects/sys-comment.object.ts
@@ -26,6 +26,7 @@ export const SysComment = ObjectSchema.create({
   managedBy: 'platform',
   description: 'Threaded comments attached to records via thread_id',
   displayNameField: 'body',
+  nameField: 'body', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{author_name}: {body}',
   compactLayout: ['created_at', 'author_name', 'body'],
 
diff --git a/packages/plugins/plugin-security/src/objects/sys-capability.object.ts b/packages/plugins/plugin-security/src/objects/sys-capability.object.ts
@@ -39,6 +39,7 @@ export const SysCapability = ObjectSchema.create({
   },
   description: 'Authorization capability definitions (ADR-0066 D1). Referenced by name from permission-set systemPermissions and resource requiredPermissions.',
   displayNameField: 'label',
+  nameField: 'label', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['label', 'name', 'scope', 'managed_by', 'active'],
 
diff --git a/packages/plugins/plugin-security/src/objects/sys-permission-set.object.ts b/packages/plugins/plugin-security/src/objects/sys-permission-set.object.ts
@@ -27,6 +27,7 @@ export const SysPermissionSet = ObjectSchema.create({
   },
   description: 'Named permission groupings for fine-grained access control',
   displayNameField: 'label',
+  nameField: 'label', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['label', 'name', 'active'],
 
diff --git a/packages/plugins/plugin-security/src/objects/sys-role.object.ts b/packages/plugins/plugin-security/src/objects/sys-role.object.ts
@@ -30,6 +30,7 @@ export const SysRole = ObjectSchema.create({
   },
   description: 'Role definitions for RBAC access control',
   displayNameField: 'label',
+  nameField: 'label', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['label', 'name', 'active', 'is_default'],
 
diff --git a/packages/plugins/plugin-sharing/src/objects/sys-sharing-rule.object.ts b/packages/plugins/plugin-sharing/src/objects/sys-sharing-rule.object.ts
@@ -39,6 +39,7 @@ export const SysSharingRule = ObjectSchema.create({
   userActions: { create: true, edit: true, delete: true, import: false },
   description: 'Declarative sharing rule that auto-materialises sys_record_share grants. Authored via defineSharingRule() in code or the Studio criteria builder.',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['name', 'object_name', 'recipient_type', 'recipient_id', 'access_level', 'active'],
 
diff --git a/packages/plugins/plugin-webhooks/src/sys-webhook.object.ts b/packages/plugins/plugin-webhooks/src/sys-webhook.object.ts
@@ -45,6 +45,7 @@ export const SysWebhook = ObjectSchema.create({
   userActions: { create: true, edit: true, delete: true, import: false },
   description: 'Outbound HTTP webhook subscription. Authored via defineWebhook() in code or the Studio editor; executed by the HTTP connector plugin.',
   displayNameField: 'name',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
   compactLayout: ['name', 'object_name', 'url', 'active', 'updated_at'],
 
diff --git a/packages/services/service-automation/src/sys-automation-run.object.ts b/packages/services/service-automation/src/sys-automation-run.object.ts
@@ -37,6 +37,7 @@ export const SysAutomationRun = ObjectSchema.create({
   managedBy: 'system',
   description: 'Durable state of a suspended automation flow run (ADR-0019)',
   displayNameField: 'id',
+  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{flow_name} · {node_id}',
   compactLayout: ['flow_name', 'node_id', 'status', 'correlation', 'started_at', 'updated_at'],
 
diff --git a/packages/services/service-messaging/src/objects/http-delivery.object.ts b/packages/services/service-messaging/src/objects/http-delivery.object.ts
@@ -36,6 +36,7 @@ export const HttpDelivery = ObjectSchema.create({
     description:
         'Durable outbox row for one outbound-HTTP attempt (ADR-0018). Managed by @objectstack/service-messaging; do not write directly.',
     displayNameField: 'id',
+    nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
     titleFormat: '{label} → {url}',
     compactLayout: ['source', 'url', 'status', 'attempts', 'next_retry_at'],
 
diff --git a/packages/services/service-messaging/src/objects/inbox-message.object.ts b/packages/services/service-messaging/src/objects/inbox-message.object.ts
@@ -23,6 +23,7 @@ export const InboxMessage = ObjectSchema.create({
     pluralLabel: 'Inbox Messages',
     icon: 'inbox',
     description: 'User-facing in-app notification rows materialized by the inbox messaging channel.',
+    nameField: 'title', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
     titleFormat: '{title}',
     compactLayout: ['title', 'user_id', 'severity', 'created_at'],
 
diff --git a/packages/services/service-storage/src/objects/system-file.object.ts b/packages/services/service-storage/src/objects/system-file.object.ts
@@ -24,6 +24,7 @@ export const SystemFile = ObjectSchema.create({
   pluralLabel: 'System Files',
   icon: 'file',
   description: 'Storage service file metadata (fileId ↔ key mapping)',
+  nameField: 'name', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
   titleFormat: '{name}',
   compactLayout: ['name', 'mime_type', 'size', 'status', 'created_at'],
 
diff --git a/packages/services/service-storage/src/objects/system-upload-session.object.ts b/packages/services/service-storage/src/objects/system-upload-session.object.ts
@@ -17,6 +17,7 @@ export const SystemUploadSession = ObjectSchema.create({
   pluralLabel: 'System Upload Sessions',
   icon: 'upload-cloud',
   description: 'Resumable multipart upload sessions tracked by service-storage',
+  nameField: 'filename', // [ADR-0079] canonical primary-title pointer (single-field titleFormat)
   titleFormat: '{filename}',
   compactLayout: ['filename', 'status', 'uploaded_chunks', 'total_chunks', 'expires_at'],
 
diff --git a/packages/spec/src/ai/solution-blueprint.zod.ts b/packages/spec/src/ai/solution-blueprint.zod.ts
@@ -47,6 +47,8 @@ export const BlueprintObjectSchema = lazySchema(() => z.object({
   label: z.string().optional().describe('Human-readable singular label'),
   description: z.string().optional().describe('What this object represents'),
   fields: z.array(BlueprintFieldSchema).describe('Fields to create on the object'),
+  nameField: z.string().regex(SNAKE_CASE).optional()
+    .describe('The record title field — which field holds the human-readable name shown on cards, lookup chips, breadcrumbs and search (ADR-0079). Set it to the object\'s text label field (e.g. "product_name"). For a numbered entity (invoice/ticket), set it to a formula field that composes number + name (e.g. "{order_no} · {customer}"). Omitting it lets the platform auto-pick a text field, but declaring it is strongly preferred.'),
 }));
 export type BlueprintObject = z.infer<typeof BlueprintObjectSchema>;
 
diff --git a/packages/spec/src/data/display-name.test.ts b/packages/spec/src/data/display-name.test.ts
diff --git a/packages/spec/src/data/display-name.ts b/packages/spec/src/data/display-name.ts
diff --git a/packages/spec/src/data/index.ts b/packages/spec/src/data/index.ts
diff --git a/packages/spec/src/data/object.test.ts b/packages/spec/src/data/object.test.ts
diff --git a/packages/spec/src/data/object.zod.ts b/packages/spec/src/data/object.zod.ts
