@prisma-next/sql-contract-psl 0.12.0-dev.3 → 0.12.0-dev.31

package/dist/provider.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"provider.mjs","names":[],"sources":["../src/provider.ts"],"sourcesContent":["import { readFile } from 'node:fs/promises';\nimport type { ContractConfig } from '@prisma-next/config/config-types';\nimport type { CodecLookup } from '@prisma-next/framework-components/codec';\nimport type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';\nimport { parsePslDocument } from '@prisma-next/psl-parser';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { notOk, ok } from '@prisma-next/utils/result';\nimport { basename, extname } from 'pathe';\nimport { interpretPslDocumentToSqlContract } from './interpreter';\nimport type { ColumnDescriptor } from './psl-column-resolution';\n\nexport interface PrismaContractOptions {\n  readonly output?: string;\n  readonly target: TargetPackRef<'sql', string>;\n  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];\n}\n\n/**\n * Derives the emit output path from the schema input path so artefacts land\n * colocated with the source (e.g. `src/contract/schema.prisma` →\n * `src/contract/contract.json`). The provider owns this because it is the\n * only layer that knows the input path; the upstream `normalizeContractConfig`\n * default is a last-resort fallback for providers that don't carry one.\n */\nfunction defaultOutputFromSchemaPath(schemaPath: string): string {\n  const ext = extname(schemaPath);\n  if (ext.length === 0) return `${schemaPath}.json`;\n  const base = schemaPath.slice(0, -ext.length);\n  // PSL schemas commonly use `schema.prisma`; the emitted JSON is called\n  // `contract.json` to mirror the rest of the toolchain, not `schema.json`.\n  // Match only the exact basename `schema` so files like `my-schema.prisma`\n  // are not silently rewritten to `my-contract.json`.\n  if (basename(base) === 'schema') {\n    return `${base.slice(0, -'schema'.length)}contract.json`;\n  }\n  return `${base}.json`;\n}\n\nfunction buildColumnDescriptorMap(\n  scalarTypeDescriptors: ReadonlyMap<string, string>,\n  codecLookup: CodecLookup,\n): ReadonlyMap<string, ColumnDescriptor> {\n  const result = new Map<string, ColumnDescriptor>();\n  for (const [typeName, codecId] of scalarTypeDescriptors) {\n    const nativeType = codecLookup.targetTypesFor(codecId)?.[0];\n    if (nativeType === undefined) continue;\n    result.set(typeName, { codecId, nativeType });\n  }\n  return result;\n}\n\nexport function prismaContract(schemaPath: string, options: PrismaContractOptions): ContractConfig {\n  return {\n    source: {\n      inputs: [schemaPath],\n      load: async (context) => {\n        const [absoluteSchemaPath] = context.resolvedInputs;\n        if (absoluteSchemaPath === undefined) {\n          throw new Error(\n            'prismaContract: context.resolvedInputs is empty. The CLI config loader should populate it positional-matched with source.inputs.',\n          );\n        }\n        let schema: string;\n        try {\n          schema = await readFile(absoluteSchemaPath, 'utf-8');\n        } catch (error) {\n          const message = String(error);\n          return notOk({\n            summary: `Failed to read Prisma schema at \"${schemaPath}\"`,\n            diagnostics: [\n              {\n                code: 'PSL_SCHEMA_READ_FAILED',\n                message,\n                sourceId: schemaPath,\n              },\n            ],\n            meta: { schemaPath, absoluteSchemaPath, cause: message },\n          });\n        }\n\n        const document = parsePslDocument({\n          schema,\n          sourceId: schemaPath,\n        });\n\n        const scalarTypeDescriptors = buildColumnDescriptorMap(\n          context.scalarTypeDescriptors,\n          context.codecLookup,\n        );\n\n        const interpreted = interpretPslDocumentToSqlContract({\n          document,\n          target: options.target,\n          authoringContributions: context.authoringContributions,\n          scalarTypeDescriptors,\n          ...ifDefined(\n            'composedExtensionPacks',\n            context.composedExtensionPacks.length > 0\n              ? [...context.composedExtensionPacks]\n              : undefined,\n          ),\n          ...ifDefined(\n            'composedExtensionPackRefs',\n            options.composedExtensionPackRefs?.length\n              ? options.composedExtensionPackRefs\n              : undefined,\n          ),\n          controlMutationDefaults: context.controlMutationDefaults,\n        });\n        if (!interpreted.ok) {\n          return interpreted;\n        }\n\n        return ok(interpreted.value);\n      },\n    },\n    output: options.output ?? defaultOutputFromSchemaPath(schemaPath),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAS,4BAA4B,YAA4B;CAC/D,MAAM,MAAM,QAAQ,UAAU;CAC9B,IAAI,IAAI,WAAW,GAAG,OAAO,GAAG,WAAW;CAC3C,MAAM,OAAO,WAAW,MAAM,GAAG,CAAC,IAAI,MAAM;CAK5C,IAAI,SAAS,IAAI,MAAM,UACrB,OAAO,GAAG,KAAK,MAAM,GAAG,EAAgB,EAAE;CAE5C,OAAO,GAAG,KAAK;AACjB;AAEA,SAAS,yBACP,uBACA,aACuC;CACvC,MAAM,yBAAS,IAAI,IAA8B;CACjD,KAAK,MAAM,CAAC,UAAU,YAAY,uBAAuB;EACvD,MAAM,aAAa,YAAY,eAAe,OAAO,IAAI;EACzD,IAAI,eAAe,KAAA,GAAW;EAC9B,OAAO,IAAI,UAAU;GAAE;GAAS;EAAW,CAAC;CAC9C;CACA,OAAO;AACT;AAEA,SAAgB,eAAe,YAAoB,SAAgD;CACjG,OAAO;EACL,QAAQ;GACN,QAAQ,CAAC,UAAU;GACnB,MAAM,OAAO,YAAY;IACvB,MAAM,CAAC,sBAAsB,QAAQ;IACrC,IAAI,uBAAuB,KAAA,GACzB,MAAM,IAAI,MACR,kIACF;IAEF,IAAI;IACJ,IAAI;KACF,SAAS,MAAM,SAAS,oBAAoB,OAAO;IACrD,SAAS,OAAO;KACd,MAAM,UAAU,OAAO,KAAK;KAC5B,OAAO,MAAM;MACX,SAAS,oCAAoC,WAAW;MACxD,aAAa,CACX;OACE,MAAM;OACN;OACA,UAAU;MACZ,CACF;MACA,MAAM;OAAE;OAAY;OAAoB,OAAO;MAAQ;KACzD,CAAC;IACH;IAEA,MAAM,WAAW,iBAAiB;KAChC;KACA,UAAU;IACZ,CAAC;IAED,MAAM,wBAAwB,yBAC5B,QAAQ,uBACR,QAAQ,WACV;IAEA,MAAM,cAAc,kCAAkC;KACpD;KACA,QAAQ,QAAQ;KAChB,wBAAwB,QAAQ;KAChC;KACA,GAAG,UACD,0BACA,QAAQ,uBAAuB,SAAS,IACpC,CAAC,GAAG,QAAQ,sBAAsB,IAClC,KAAA,CACN;KACA,GAAG,UACD,6BACA,QAAQ,2BAA2B,SAC/B,QAAQ,4BACR,KAAA,CACN;KACA,yBAAyB,QAAQ;IACnC,CAAC;IACD,IAAI,CAAC,YAAY,IACf,OAAO;IAGT,OAAO,GAAG,YAAY,KAAK;GAC7B;EACF;EACA,QAAQ,QAAQ,UAAU,4BAA4B,UAAU;CAClE;AACF"}
+{"version":3,"file":"provider.mjs","names":[],"sources":["../src/provider.ts"],"sourcesContent":["import { readFile } from 'node:fs/promises';\nimport type { ContractConfig } from '@prisma-next/config/config-types';\nimport { applySpecifierDefaultControlPolicy } from '@prisma-next/contract/apply-specifier-default-control-policy';\nimport type { ControlPolicy } from '@prisma-next/contract/types';\nimport type { CodecLookup } from '@prisma-next/framework-components/codec';\nimport type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';\nimport { parsePslDocument } from '@prisma-next/psl-parser';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { notOk, ok } from '@prisma-next/utils/result';\nimport { basename, extname } from 'pathe';\nimport { interpretPslDocumentToSqlContract } from './interpreter';\nimport type { ColumnDescriptor } from './psl-column-resolution';\n\nexport interface PrismaContractOptions {\n  readonly output?: string;\n  readonly target: TargetPackRef<'sql', string>;\n  readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];\n  readonly defaultControlPolicy?: ControlPolicy;\n}\n\n/**\n * Derives the emit output path from the schema input path so artefacts land\n * colocated with the source (e.g. `src/contract/schema.prisma` →\n * `src/contract/contract.json`). The provider owns this because it is the\n * only layer that knows the input path; the upstream `normalizeContractConfig`\n * default is a last-resort fallback for providers that don't carry one.\n */\nfunction defaultOutputFromSchemaPath(schemaPath: string): string {\n  const ext = extname(schemaPath);\n  if (ext.length === 0) return `${schemaPath}.json`;\n  const base = schemaPath.slice(0, -ext.length);\n  // PSL schemas commonly use `schema.prisma`; the emitted JSON is called\n  // `contract.json` to mirror the rest of the toolchain, not `schema.json`.\n  // Match only the exact basename `schema` so files like `my-schema.prisma`\n  // are not silently rewritten to `my-contract.json`.\n  if (basename(base) === 'schema') {\n    return `${base.slice(0, -'schema'.length)}contract.json`;\n  }\n  return `${base}.json`;\n}\n\nfunction buildColumnDescriptorMap(\n  scalarTypeDescriptors: ReadonlyMap<string, string>,\n  codecLookup: CodecLookup,\n): ReadonlyMap<string, ColumnDescriptor> {\n  const result = new Map<string, ColumnDescriptor>();\n  for (const [typeName, codecId] of scalarTypeDescriptors) {\n    const nativeType = codecLookup.targetTypesFor(codecId)?.[0];\n    if (nativeType === undefined) continue;\n    result.set(typeName, { codecId, nativeType });\n  }\n  return result;\n}\n\nexport function prismaContract(schemaPath: string, options: PrismaContractOptions): ContractConfig {\n  return {\n    source: {\n      inputs: [schemaPath],\n      load: async (context) => {\n        const [absoluteSchemaPath] = context.resolvedInputs;\n        if (absoluteSchemaPath === undefined) {\n          throw new Error(\n            'prismaContract: context.resolvedInputs is empty. The CLI config loader should populate it positional-matched with source.inputs.',\n          );\n        }\n        let schema: string;\n        try {\n          schema = await readFile(absoluteSchemaPath, 'utf-8');\n        } catch (error) {\n          const message = String(error);\n          return notOk({\n            summary: `Failed to read Prisma schema at \"${schemaPath}\"`,\n            diagnostics: [\n              {\n                code: 'PSL_SCHEMA_READ_FAILED',\n                message,\n                sourceId: schemaPath,\n              },\n            ],\n            meta: { schemaPath, absoluteSchemaPath, cause: message },\n          });\n        }\n\n        const document = parsePslDocument({\n          schema,\n          sourceId: schemaPath,\n        });\n\n        const scalarTypeDescriptors = buildColumnDescriptorMap(\n          context.scalarTypeDescriptors,\n          context.codecLookup,\n        );\n\n        const interpreted = interpretPslDocumentToSqlContract({\n          document,\n          target: options.target,\n          authoringContributions: context.authoringContributions,\n          scalarTypeDescriptors,\n          ...ifDefined(\n            'composedExtensionPacks',\n            context.composedExtensionPacks.length > 0\n              ? [...context.composedExtensionPacks]\n              : undefined,\n          ),\n          ...ifDefined(\n            'composedExtensionPackRefs',\n            options.composedExtensionPackRefs?.length\n              ? options.composedExtensionPackRefs\n              : undefined,\n          ),\n          controlMutationDefaults: context.controlMutationDefaults,\n        });\n        if (!interpreted.ok) {\n          return interpreted;\n        }\n\n        return ok(\n          applySpecifierDefaultControlPolicy(interpreted.value, options.defaultControlPolicy),\n        );\n      },\n    },\n    output: options.output ?? defaultOutputFromSchemaPath(schemaPath),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AA2BA,SAAS,4BAA4B,YAA4B;CAC/D,MAAM,MAAM,QAAQ,UAAU;CAC9B,IAAI,IAAI,WAAW,GAAG,OAAO,GAAG,WAAW;CAC3C,MAAM,OAAO,WAAW,MAAM,GAAG,CAAC,IAAI,MAAM;CAK5C,IAAI,SAAS,IAAI,MAAM,UACrB,OAAO,GAAG,KAAK,MAAM,GAAG,EAAgB,EAAE;CAE5C,OAAO,GAAG,KAAK;AACjB;AAEA,SAAS,yBACP,uBACA,aACuC;CACvC,MAAM,yBAAS,IAAI,IAA8B;CACjD,KAAK,MAAM,CAAC,UAAU,YAAY,uBAAuB;EACvD,MAAM,aAAa,YAAY,eAAe,OAAO,IAAI;EACzD,IAAI,eAAe,KAAA,GAAW;EAC9B,OAAO,IAAI,UAAU;GAAE;GAAS;EAAW,CAAC;CAC9C;CACA,OAAO;AACT;AAEA,SAAgB,eAAe,YAAoB,SAAgD;CACjG,OAAO;EACL,QAAQ;GACN,QAAQ,CAAC,UAAU;GACnB,MAAM,OAAO,YAAY;IACvB,MAAM,CAAC,sBAAsB,QAAQ;IACrC,IAAI,uBAAuB,KAAA,GACzB,MAAM,IAAI,MACR,kIACF;IAEF,IAAI;IACJ,IAAI;KACF,SAAS,MAAM,SAAS,oBAAoB,OAAO;IACrD,SAAS,OAAO;KACd,MAAM,UAAU,OAAO,KAAK;KAC5B,OAAO,MAAM;MACX,SAAS,oCAAoC,WAAW;MACxD,aAAa,CACX;OACE,MAAM;OACN;OACA,UAAU;MACZ,CACF;MACA,MAAM;OAAE;OAAY;OAAoB,OAAO;MAAQ;KACzD,CAAC;IACH;IAEA,MAAM,WAAW,iBAAiB;KAChC;KACA,UAAU;IACZ,CAAC;IAED,MAAM,wBAAwB,yBAC5B,QAAQ,uBACR,QAAQ,WACV;IAEA,MAAM,cAAc,kCAAkC;KACpD;KACA,QAAQ,QAAQ;KAChB,wBAAwB,QAAQ;KAChC;KACA,GAAG,UACD,0BACA,QAAQ,uBAAuB,SAAS,IACpC,CAAC,GAAG,QAAQ,sBAAsB,IAClC,KAAA,CACN;KACA,GAAG,UACD,6BACA,QAAQ,2BAA2B,SAC/B,QAAQ,4BACR,KAAA,CACN;KACA,yBAAyB,QAAQ;IACnC,CAAC;IACD,IAAI,CAAC,YAAY,IACf,OAAO;IAGT,OAAO,GACL,mCAAmC,YAAY,OAAO,QAAQ,oBAAoB,CACpF;GACF;EACF;EACA,QAAQ,QAAQ,UAAU,4BAA4B,UAAU;CAClE;AACF"}

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@prisma-next/sql-contract-psl",
-  "version": "0.12.0-dev.3",
+  "version": "0.12.0-dev.31",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "PSL-to-SQL ContractIR interpreter for Prisma Next",
   "dependencies": {
-    "@prisma-next/config": "0.12.0-dev.3",
-    "@prisma-next/contract": "0.12.0-dev.3",
-    "@prisma-next/framework-components": "0.12.0-dev.3",
-    "@prisma-next/psl-parser": "0.12.0-dev.3",
-    "@prisma-next/sql-contract": "0.12.0-dev.3",
-    "@prisma-next/sql-contract-ts": "0.12.0-dev.3",
-    "@prisma-next/utils": "0.12.0-dev.3",
+    "@prisma-next/config": "0.12.0-dev.31",
+    "@prisma-next/contract": "0.12.0-dev.31",
+    "@prisma-next/framework-components": "0.12.0-dev.31",
+    "@prisma-next/psl-parser": "0.12.0-dev.31",
+    "@prisma-next/sql-contract": "0.12.0-dev.31",
+    "@prisma-next/sql-contract-ts": "0.12.0-dev.31",
+    "@prisma-next/utils": "0.12.0-dev.31",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@prisma-next/contract-authoring": "0.12.0-dev.3",
-    "@prisma-next/test-utils": "0.12.0-dev.3",
-    "@prisma-next/tsconfig": "0.12.0-dev.3",
-    "@prisma-next/tsdown": "0.12.0-dev.3",
+    "@prisma-next/contract-authoring": "0.12.0-dev.31",
+    "@prisma-next/test-utils": "0.12.0-dev.31",
+    "@prisma-next/tsconfig": "0.12.0-dev.31",
+    "@prisma-next/tsdown": "0.12.0-dev.31",
     "arktype": "^2.2.0",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",

package/src/interpreter.ts

@@ -8,6 +8,7 @@ import type {
   ContractField,
   ContractModel,
   ContractValueObject,
+  ControlPolicy,
 } from '@prisma-next/contract/types';
 import { crossRef } from '@prisma-next/contract/types';
 import type {
@@ -23,7 +24,6 @@ import type {
   MutationDefaultGeneratorDescriptor,
 } from '@prisma-next/framework-components/control';
 import type { Namespace } from '@prisma-next/framework-components/ir';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type {
   ParsePslDocumentResult,
   PslAttribute,
@@ -58,6 +58,7 @@ import {
   mapFieldNamesToColumns,
   parseAttributeFieldList,
   parseConstraintMapArgument,
+  parseControlPolicyAttribute,
   parseMapName,
   parseObjectLiteralStringMap,
   parseQuotedStringLiteral,
@@ -229,10 +230,6 @@ const UNSPECIFIED_PSL_NAMESPACE_NAME = '__unspecified__';
  * slot empty (which means the late-bound default at the `StorageTable`
  * layer; emitted JSON omits the field).
  */
-function defaultSqlNamespaceIdForTarget(targetId: string): string {
-  return targetId === 'postgres' ? 'public' : UNBOUND_NAMESPACE_ID;
-}
-
 function resolveNamespaceIdForSqlTarget(input: {
   readonly bucketName: string;
   readonly targetId: string;
@@ -647,6 +644,8 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     : undefined;
   const hasInlinePrimaryKey = primaryKey !== undefined;
   let blockPrimaryKeyDeclared = false;
+  let controlPolicyDeclared = false;
+  let controlPolicy: ControlPolicy | undefined;
 
   const resultBackrelationCandidates: ModelBackrelationCandidate[] = [];
   for (const field of model.fields) {
@@ -733,6 +732,27 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
     if (modelAttribute.name === 'discriminator' || modelAttribute.name === 'base') {
       continue;
     }
+    if (modelAttribute.name === 'control') {
+      if (controlPolicyDeclared) {
+        diagnostics.push({
+          code: 'PSL_DUPLICATE_ATTRIBUTE',
+          message: `\`@@control\` declared more than once on model "${model.name}".`,
+          sourceId,
+          span: modelAttribute.span,
+        });
+        continue;
+      }
+      controlPolicyDeclared = true;
+      const parsed = parseControlPolicyAttribute({
+        attribute: modelAttribute,
+        sourceId,
+        diagnostics,
+      });
+      if (parsed !== undefined) {
+        controlPolicy = parsed;
+      }
+      continue;
+    }
     const attributeLabel = `Model "${model.name}" @@${modelAttribute.name}`;
     if (modelAttribute.name === 'id') {
       if (blockPrimaryKeyDeclared) {
@@ -1103,6 +1123,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       ...(uniqueConstraints.length > 0 ? { uniques: uniqueConstraints } : {}),
       ...(indexNodes.length > 0 ? { indexes: indexNodes } : {}),
       ...(foreignKeyNodes.length > 0 ? { foreignKeys: foreignKeyNodes } : {}),
+      ...ifDefined('control', controlPolicy),
     },
     fkRelationMetadata: resultFkRelationMetadata,
     backrelationCandidates: resultBackrelationCandidates,
@@ -1310,7 +1331,7 @@ function resolvePolymorphism(
   modelNames: Set<string>,
   modelMappings: ReadonlyMap<string, ModelNameMapping>,
   modelNamespaceIds: ReadonlyMap<string, string>,
-  targetId: string,
+  defaultNamespaceId: string,
   sourceId: string,
   diagnostics: ContractSourceDiagnostic[],
 ): Record<string, ContractModel> {
@@ -1416,7 +1437,7 @@ function resolvePolymorphism(
         ...variantModel,
         base: crossRef(
           baseDecl.baseName,
-          modelNamespaceIds.get(baseDecl.baseName) ?? defaultSqlNamespaceIdForTarget(targetId),
+          modelNamespaceIds.get(baseDecl.baseName) ?? defaultNamespaceId,
         ),
         ...(resolvedTable ? { storage: { ...variantModel.storage, table: resolvedTable } } : {}),
       },
@@ -1700,7 +1721,7 @@ export function interpretPslDocumentToSqlContract(
     modelNames,
     modelMappings,
     modelNamespaceIds,
-    input.target.targetId,
+    input.target.defaultNamespaceId,
     sourceId,
     polyDiagnostics,
   );
@@ -1736,7 +1757,7 @@ export function interpretPslDocumentToSqlContract(
             ...(namespaceSlice.valueObjects !== undefined
               ? { valueObjects: namespaceSlice.valueObjects }
               : {}),
-            ...(namespaceId === defaultSqlNamespaceIdForTarget(input.target.targetId) &&
+            ...(namespaceId === input.target.defaultNamespaceId &&
             Object.keys(valueObjects).length > 0
               ? { valueObjects }
               : {}),

package/src/provider.ts

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import type { ContractConfig } from '@prisma-next/config/config-types';
+import { applySpecifierDefaultControlPolicy } from '@prisma-next/contract/apply-specifier-default-control-policy';
+import type { ControlPolicy } from '@prisma-next/contract/types';
 import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
 import { parsePslDocument } from '@prisma-next/psl-parser';
@@ -13,6 +15,7 @@ export interface PrismaContractOptions {
   readonly output?: string;
   readonly target: TargetPackRef<'sql', string>;
   readonly composedExtensionPackRefs?: readonly ExtensionPackRef<'sql', string>[];
+  readonly defaultControlPolicy?: ControlPolicy;
 }
 
 /**
@@ -111,7 +114,9 @@ export function prismaContract(schemaPath: string, options: PrismaContractOption
           return interpreted;
         }
 
-        return ok(interpreted.value);
+        return ok(
+          applySpecifierDefaultControlPolicy(interpreted.value, options.defaultControlPolicy),
+        );
       },
     },
     output: options.output ?? defaultOutputFromSchemaPath(schemaPath),

package/src/psl-attribute-parsing.ts

@@ -1,4 +1,5 @@
 import type { ContractSourceDiagnostic } from '@prisma-next/config/config-types';
+import type { ControlPolicy } from '@prisma-next/contract/types';
 import type { PslAttribute, PslSpan } from '@prisma-next/psl-parser';
 import { getPositionalArgument, parseQuotedStringLiteral } from '@prisma-next/psl-parser';
 
@@ -411,6 +412,71 @@ export function findDuplicateFieldName(fieldNames: readonly string[]): string |
   return undefined;
 }
 
+const CONTROL_POLICY_LITERALS = [
+  'managed',
+  'tolerated',
+  'external',
+  'observed',
+] as const satisfies readonly ControlPolicy[];
+
+const CONTROL_POLICY_LITERAL_SET = new Set<string>(CONTROL_POLICY_LITERALS);
+
+function isControlPolicyLiteral(value: string): value is ControlPolicy {
+  return CONTROL_POLICY_LITERAL_SET.has(value);
+}
+
+export function parseControlPolicyAttribute(input: {
+  readonly attribute: PslAttribute;
+  readonly sourceId: string;
+  readonly diagnostics: ContractSourceDiagnostic[];
+}): ControlPolicy | undefined {
+  const namedArgs = input.attribute.args.filter((arg) => arg.kind === 'named');
+  if (namedArgs.length > 0) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+      message:
+        '`@@control` does not accept named arguments; pass the policy positionally as `@@control(external)`.',
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  const positionalArgs = getPositionalArguments(input.attribute);
+  if (positionalArgs.length === 0) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+      message:
+        '`@@control` requires exactly one positional argument: `managed`, `tolerated`, `external`, or `observed`.',
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+  if (positionalArgs.length > 1) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+      message: `\`@@control\` accepts exactly one positional argument; got ${positionalArgs.length}.`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  const token = unquoteStringLiteral(positionalArgs[0] ?? '').trim();
+  if (!isControlPolicyLiteral(token)) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+      message: `\`@@control\` argument \`${token}\` is not a known policy. Allowed: \`managed\`, \`tolerated\`, \`external\`, \`observed\`.`,
+      sourceId: input.sourceId,
+      span: input.attribute.span,
+    });
+    return undefined;
+  }
+
+  return token;
+}
+
 export function mapFieldNamesToColumns(input: {
   readonly modelName: string;
   readonly fieldNames: readonly string[];