feat(sql): add updatedAt timestamp authoring

Adds phase-specific execution defaults to SQL TS authoring so generated IDs stay on-create-only while updatedAt can use both create and update phases.

Wires Prisma-compatible @updatedat lowering for Postgres and SQLite PSL, plus field.updatedAt() helpers backed by target-owned timestampNow generators. Empty update payloads skip onUpdate defaults so no-op updates do not advance updatedAt.

Author: jkomyno

docs/products/psl/README.md

@@ -7,7 +7,7 @@ Scope: **PSL → SQL Contract IR** via `@prisma-next/psl-parser` and `@prisma-ne
 ## What PSL v1 can do today (high level)
 
 - **Models, enums, and named types** (`types { ... }`) with deterministic parsing and span-aware diagnostics.
-- **SQL storage mapping** for a Postgres-first subset: tables, columns, primary keys, uniques, indexes, and foreign keys.
+- **SQL storage mapping** for a SQL subset: tables, columns, primary keys, uniques, indexes, and foreign keys.
 - **Defaults** for a curated set of TS-aligned functions and literals, lowered into either storage defaults or execution defaults.
 - **Extension-pack parity (minimal)**: namespaced constructor expressions such as `pgvector.Vector(...)` when the corresponding pack is composed in config.
 
@@ -60,6 +60,10 @@ This is a deliberate “strict subset” choice: PSL v1 is bounded by the curren
 - Supported defaults are split into:
   - **Storage defaults**: literals, `autoincrement()`, `now()`, `dbgenerated("...")`
   - **Execution defaults** (mutation-time generators): `uuid()`, `uuid(4)`, `uuid(7)`, `cuid(2)`, `ulid()`, `nanoid()`, `nanoid(n)`
+- Timestamp authoring follows Prisma ORM’s shape for supported SQL targets:
+  - create timestamps use `DateTime @default(now())`, which remains a storage default owned by the database
+  - update timestamps use no-argument `DateTime @updatedAt`, which lowers to a `timestampNow` execution default on create and non-empty update mutations
+- Prisma Next does not add a PSL `@createdAt` alias.
 - **`cuid()` (cuid v1) is explicitly unsupported**; diagnostics guide users to `cuid(2)`.
 - **`dbgenerated("...")` is string-literal based** and (in v1) preserves the parsed contents as-is (escape sequences are not normalized).
 

packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts

@@ -63,10 +63,16 @@ export type AuthoringColumnDefaultTemplate =
   | AuthoringColumnDefaultTemplateLiteral
   | AuthoringColumnDefaultTemplateFunction;
 
+export interface AuthoringExecutionDefaultsTemplate {
+  readonly onCreate?: AuthoringTemplateValue;
+  readonly onUpdate?: AuthoringTemplateValue;
+}
+
 export interface AuthoringFieldPresetOutput extends AuthoringStorageTypeTemplate {
   readonly nullable?: boolean;
   readonly default?: AuthoringColumnDefaultTemplate;
   readonly executionDefault?: AuthoringTemplateValue;
+  readonly executionDefaults?: AuthoringExecutionDefaultsTemplate;
   readonly id?: boolean;
   readonly unique?: boolean;
 }
@@ -327,6 +333,29 @@ function resolveAuthoringColumnDefaultTemplate(
   };
 }
 
+function resolveAuthoringExecutionDefaultsTemplate(
+  template: AuthoringExecutionDefaultsTemplate,
+  args: readonly unknown[],
+): {
+  readonly onCreate?: unknown;
+  readonly onUpdate?: unknown;
+} {
+  return {
+    ...ifDefined(
+      'onCreate',
+      template.onCreate !== undefined
+        ? resolveAuthoringTemplateValue(template.onCreate, args)
+        : undefined,
+    ),
+    ...ifDefined(
+      'onUpdate',
+      template.onUpdate !== undefined
+        ? resolveAuthoringTemplateValue(template.onUpdate, args)
+        : undefined,
+    ),
+  };
+}
+
 export function instantiateAuthoringTypeConstructor(
   descriptor: AuthoringTypeConstructorDescriptor,
   args: readonly unknown[],
@@ -358,6 +387,10 @@ export function instantiateAuthoringFieldPreset(
         readonly expression: string;
       };
   readonly executionDefault?: unknown;
+  readonly executionDefaults?: {
+    readonly onCreate?: unknown;
+    readonly onUpdate?: unknown;
+  };
   readonly id: boolean;
   readonly unique: boolean;
 } {
@@ -376,6 +409,12 @@ export function instantiateAuthoringFieldPreset(
         ? resolveAuthoringTemplateValue(descriptor.output.executionDefault, args)
         : undefined,
     ),
+    ...ifDefined(
+      'executionDefaults',
+      descriptor.output.executionDefaults !== undefined
+        ? resolveAuthoringExecutionDefaultsTemplate(descriptor.output.executionDefaults, args)
+        : undefined,
+    ),
     id: descriptor.output.id ?? false,
     unique: descriptor.output.unique ?? false,
   };

packages/1-framework/1-core/framework-components/test/framework-components.authoring.test.ts

@@ -345,6 +345,49 @@ describe('authoring template resolution', () => {
     });
   });
 
+  it('resolves phase-specific execution defaults from field presets', () => {
+    const descriptor = {
+      kind: 'fieldPreset',
+      output: {
+        codecId: 'test/timestamp@1',
+        nativeType: 'timestamp',
+        executionDefaults: {
+          onCreate: {
+            kind: 'arg',
+            index: 0,
+            path: ['create'],
+          },
+          onUpdate: {
+            kind: 'arg',
+            index: 0,
+            path: ['update'],
+          },
+        },
+      },
+    } as const;
+
+    expect(
+      instantiateAuthoringFieldPreset(descriptor, [
+        {
+          create: { kind: 'generator', id: 'timestampNow' },
+          update: { kind: 'generator', id: 'timestampNow' },
+        },
+      ]),
+    ).toEqual({
+      descriptor: {
+        codecId: 'test/timestamp@1',
+        nativeType: 'timestamp',
+      },
+      nullable: false,
+      executionDefaults: {
+        onCreate: { kind: 'generator', id: 'timestampNow' },
+        onUpdate: { kind: 'generator', id: 'timestampNow' },
+      },
+      id: false,
+      unique: false,
+    });
+  });
+
   it('stringifies primitive function default expressions', () => {
     const descriptor = {
       kind: 'fieldPreset',

packages/2-sql/2-authoring/contract-psl/README.md

@@ -15,6 +15,7 @@ This keeps core/CLI source-agnostic while giving PSL-first SQL users a one-line
 
 - Interpret `ParsePslDocumentResult` into SQL `Contract`
 - Interpret generic PSL attributes into SQL contract semantics (`@id`, `@unique`, `@default`, `@relation`, `@map`, `@@map`)
+- Interpret SQL timestamp semantics: `DateTime @default(now())` as a storage default and `DateTime @updatedAt` as an execution mutation default
 - Lower shared constructor expressions in both `types {}` blocks and inline field positions (for example `ShortName = sql.String(length: 35)` and `embedding pgvector.Vector(length: 1536)?`)
 - Lower supported default functions through composed registry inputs
 - Support selected Postgres native-type attributes on named types for brownfield round-trips (`@db.Char`, `@db.VarChar`, `@db.Numeric`, `@db.Uuid`, `@db.SmallInt`, `@db.Real`, `@db.Timestamp`, `@db.Timestamptz`, `@db.Date`, `@db.Time`, `@db.Timetz`, `@db.Json`)
@@ -42,7 +43,7 @@ The **pure interpreter entrypoint** specifically excludes:
 - Artifact emission (`contract.json`, `contract.d.ts`) and hashing
 - CLI or ControlClient orchestration
 
-Current scope is SQL/Postgres-first: callers pass Postgres-oriented scalar descriptors and target context in v1.
+Current scope is SQL target-specific: callers pass scalar descriptors and target context assembled for the active SQL target.
 
 Unsupported PSL constructs in v1 (strict errors):
 
@@ -63,6 +64,12 @@ Supported `@default(...)` surface in v1 when composed contributors provide handl
 - Explicitly unsupported in v1: `cuid()` (diagnostic suggests `cuid(2)`)
 - `dbgenerated("...")` preserves the parsed PSL string-literal contents as-is (escaped sequences are not normalized in v1).
 
+Supported timestamp attribute surface:
+
+- `createdAt DateTime @default(now())` lowers to the target storage default and does not create an execution mutation default.
+- `updatedAt DateTime @updatedAt` lowers to `timestampNow` on create and on non-empty update mutations. This is application-side because Prisma’s `@updatedAt` semantics are mutation-aware, not a database trigger.
+- `@createdAt` is not supported as a PSL alias.
+
 ## Public API
 
 - `@prisma-next/sql-contract-psl`

packages/2-sql/2-authoring/contract-psl/src/interpreter.ts

@@ -77,19 +77,19 @@ import {
 
 export interface InterpretPslDocumentToSqlContractInput {
   readonly document: ParsePslDocumentResult;
-  readonly target: TargetPackRef<'sql', 'postgres'>;
+  readonly target: TargetPackRef<'sql', string>;
   readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
   readonly composedExtensionPacks?: readonly string[];
-  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', 'postgres'>[];
+  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];
   readonly controlMutationDefaults?: ControlMutationDefaults;
   readonly authoringContributions?: AuthoringContributions;
 }
 
 function buildComposedExtensionPackRefs(
-  target: TargetPackRef<'sql', 'postgres'>,
+  target: TargetPackRef<'sql', string>,
   extensionIds: readonly string[],
-  extensionPackRefs: readonly ExtensionPackRef<'sql', 'postgres'>[] = [],
-): Record<string, ExtensionPackRef<'sql', 'postgres'>> | undefined {
+  extensionPackRefs: readonly ExtensionPackRef<'sql', string>[] = [],
+): Record<string, ExtensionPackRef<'sql', string>> | undefined {
   if (extensionIds.length === 0) {
     return undefined;
   }
@@ -106,7 +106,7 @@ function buildComposedExtensionPackRefs(
           familyId: target.familyId,
           targetId: target.targetId,
           version: '0.0.1',
-        } satisfies ExtensionPackRef<'sql', 'postgres'>),
+        } satisfies ExtensionPackRef<'sql', string>),
     ]),
   );
 }
@@ -763,6 +763,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
         nullable: resolvedField.field.optional,
         ...ifDefined('default', resolvedField.defaultValue),
         ...ifDefined('executionDefault', resolvedField.executionDefault),
+        ...ifDefined('executionDefaults', resolvedField.executionDefaults),
       })),
       ...(primaryKeyColumns.length > 0
         ? {

packages/2-sql/2-authoring/contract-psl/src/provider.ts

@@ -10,8 +10,8 @@ import type { ColumnDescriptor } from './psl-column-resolution';
 
 export interface PrismaContractOptions {
   readonly output?: string;
-  readonly target: TargetPackRef<'sql', 'postgres'>;
-  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', 'postgres'>[];
+  readonly target: TargetPackRef<'sql', string>;
+  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];
 }
 
 function buildColumnDescriptorMap(

packages/2-sql/2-authoring/contract-psl/src/psl-field-resolution.ts

@@ -1,5 +1,9 @@
 import type { ContractSourceDiagnostic } from '@prisma-next/config/config-types';
-import type { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import type {
+  ColumnDefault,
+  ExecutionMutationDefault,
+  ExecutionMutationDefaultValue,
+} from '@prisma-next/contract/types';
 import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
 import type {
   ControlMutationDefaultRegistry,
@@ -27,6 +31,7 @@ export type ResolvedField = {
   readonly descriptor: ColumnDescriptor;
   readonly defaultValue?: ColumnDefault;
   readonly executionDefault?: ExecutionMutationDefaultValue;
+  readonly executionDefaults?: Omit<ExecutionMutationDefault, 'ref'>;
   readonly isId: boolean;
   readonly isUnique: boolean;
   readonly idName?: string;
@@ -64,6 +69,7 @@ const BUILTIN_FIELD_ATTRIBUTE_NAMES: ReadonlySet<string> = new Set([
   'id',
   'unique',
   'default',
+  'updatedAt',
   'relation',
   'map',
 ]);
@@ -138,6 +144,88 @@ function extractFieldConstraintNames(input: {
   return { idAttribute, uniqueAttribute, idName, uniqueName };
 }
 
+const TIMESTAMP_NOW_GENERATOR_ID = 'timestampNow';
+
+function reportInvalidUpdatedAt(input: {
+  readonly model: PslModel;
+  readonly field: PslField;
+  readonly attribute: PslAttribute;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+  readonly message: string;
+}): void {
+  input.diagnostics.push({
+    code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+    message: `Field "${input.model.name}.${input.field.name}" @updatedAt ${input.message}`,
+    sourceId: input.sourceId,
+    span: input.attribute.span,
+  });
+}
+
+function lowerUpdatedAtAttribute(input: {
+  readonly model: PslModel;
+  readonly field: PslField;
+  readonly attribute: PslAttribute;
+  readonly descriptor: ColumnDescriptor;
+  readonly defaultAttribute: PslAttribute | undefined;
+  readonly generatorDescriptorById: ReadonlyMap<string, MutationDefaultGeneratorDescriptor>;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly sourceId: string;
+}): Omit<ExecutionMutationDefault, 'ref'> | undefined {
+  if (input.attribute.args.length > 0) {
+    reportInvalidUpdatedAt({
+      ...input,
+      message: 'does not accept arguments. Use @updatedAt.',
+    });
+    return undefined;
+  }
+  if (input.defaultAttribute) {
+    reportInvalidUpdatedAt({
+      ...input,
+      message: 'cannot be combined with @default.',
+    });
+    return undefined;
+  }
+  if (input.field.optional) {
+    reportInvalidUpdatedAt({
+      ...input,
+      message: 'cannot be optional. Remove "?" or remove @updatedAt.',
+    });
+    return undefined;
+  }
+  if (input.field.list) {
+    reportInvalidUpdatedAt({
+      ...input,
+      message: 'cannot be a list field. Use a singular DateTime field.',
+    });
+    return undefined;
+  }
+
+  const generatorDescriptor = input.generatorDescriptorById.get(TIMESTAMP_NOW_GENERATOR_ID);
+  if (!generatorDescriptor) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_DEFAULT_APPLICABILITY',
+      message: `Field "${input.model.name}.${input.field.name}" @updatedAt requires mutation default generator "${TIMESTAMP_NOW_GENERATOR_ID}".`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+  if (!generatorDescriptor.applicableCodecIds.includes(input.descriptor.codecId)) {
+    reportInvalidUpdatedAt({
+      ...input,
+      message: `requires a timestamp-compatible field, received codecId "${input.descriptor.codecId}".`,
+    });
+    return undefined;
+  }
+
+  const generated = { kind: 'generator' as const, id: TIMESTAMP_NOW_GENERATOR_ID };
+  return {
+    onCreate: generated,
+    onUpdate: generated,
+  };
+}
+
 export function collectResolvedFields(input: CollectResolvedFieldsInput): ResolvedField[] {
   const {
     model,
@@ -235,6 +323,19 @@ export function collectResolvedFields(input: CollectResolvedFieldsInput): Resolv
     }
 
     const defaultAttribute = getAttribute(field.attributes, 'default');
+    const updatedAtAttribute = getAttribute(field.attributes, 'updatedAt');
+    const updatedAtExecutionDefaults = updatedAtAttribute
+      ? lowerUpdatedAtAttribute({
+          model,
+          field,
+          attribute: updatedAtAttribute,
+          descriptor,
+          defaultAttribute,
+          generatorDescriptorById,
+          diagnostics,
+          sourceId,
+        })
+      : undefined;
     const loweredDefault = defaultAttribute
       ? lowerDefaultForField({
           modelName: model.name,
@@ -283,6 +384,7 @@ export function collectResolvedFields(input: CollectResolvedFieldsInput): Resolv
       descriptor,
       ...ifDefined('defaultValue', loweredDefault.defaultValue),
       ...ifDefined('executionDefault', loweredDefault.executionDefault),
+      ...ifDefined('executionDefaults', updatedAtExecutionDefaults),
       isId: Boolean(idAttribute),
       isUnique: Boolean(uniqueAttribute),
       ...ifDefined('idName', idName),